9. Tools

The tools array declares the tools exposed by the MCP server. Each tool represents a server-side function that clients can invoke.

9.1 Tool Object

Property	Type	Required	Description
`name`	string	Yes	Programmatic tool name (identifier).
`title`	string	No	Human-readable display name for UI contexts. Since MCP 2025-06-18.
`description`	string	No	Human-readable tool description.
`inputSchema`	object	No	JSON Schema for tool input parameters.
`outputSchema`	object	No	JSON Schema for structured tool output. Since MCP 2025-06-18.
`annotations`	Tool Annotations Object	No	Behavioral hints. Since MCP 2025-03-26.
`execution`	Execution Object	No	Execution properties. Since MCP 2025-11-25.
`icons`	array<Icon>	No	Icons for UI display. Since MCP 2025-11-25.
`tags`	array<string>	No	Categorization tags. When a root-level `tags` array is present, values MUST reference declared tag names (see Section 12.3).
`deprecated`	boolean	No	Whether the tool is deprecated.
`_meta`	object	No	Protocol-reserved metadata. Since MCP 2025-06-18.

9.2 Input and Output Schemas

The inputSchema property, when present, MUST be a valid JSON Schema object describing the tool’s input parameters. It typically has "type": "object" with properties and required fields.

The outputSchema property, when present, MUST be a valid JSON Schema object describing the tool’s structured output. It defaults to JSON Schema 2020-12 dialect when no explicit $schema is provided.

Both schemas MAY include an explicit $schema property to declare the JSON Schema dialect (since MCP 2025-11-25).

9.3 Tool Annotations

Tool annotations provide hints about tool behavior. These are advisory — implementations MUST NOT rely on annotations being accurate.

Property	Type	Default	Description
`title`	string	—	Human-readable title for the tool
`readOnlyHint`	boolean	`false`	Tool does not modify its environment
`destructiveHint`	boolean	`true`	Tool may perform destructive updates
`idempotentHint`	boolean	`false`	Repeated calls with same arguments have no additional effect
`openWorldHint`	boolean	`true`	Tool may interact with external entities

The annotations object allows additional properties for forward compatibility.

9.4 Execution Object

Property	Type	Default	Description
`taskSupport`	string	`"forbidden"`	Whether the tool supports task-augmented execution: `"forbidden"`, `"optional"`, or `"required"`

9.5 Example

{
  "tools": [
    {
      "name": "analyze_game",
      "title": "Analyze Chess Game",
      "description": "Analyze a chess game from PGN notation and return evaluation scores",
      "inputSchema": {
        "type": "object",
        "properties": {
          "pgn": {
            "type": "string",
            "description": "Game in Portable Game Notation (PGN) format"
          },
          "depth": {
            "type": "integer",
            "description": "Analysis depth in half-moves",
            "minimum": 1,
            "maximum": 40
          }
        },
        "required": ["pgn"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "evaluation": { "type": "number", "description": "Centipawn evaluation" },
          "best_move": { "type": "string", "description": "Best move in algebraic notation" },
          "blunders": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "move_number": { "type": "integer" },
                "move": { "type": "string" },
                "evaluation_loss": { "type": "number" }
              }
            }
          }
        }
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true
      },
      "tags": ["analysis", "chess"]
    },
    {
      "name": "get_player_rating",
      "title": "Get Player Rating",
      "description": "Get the current Elo rating and rating history for a chess player",
      "inputSchema": {
        "type": "object",
        "properties": {
          "player_id": {
            "type": "string",
            "description": "Unique player identifier"
          },
          "rating_type": {
            "type": "string",
            "enum": ["classical", "rapid", "blitz", "bullet"],
            "description": "Type of rating to retrieve"
          }
        },
        "required": ["player_id"]
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false
      },
      "tags": ["rating", "player"]
    },
    {
      "name": "record_game_result",
      "title": "Record Game Result",
      "description": "Record the result of a chess game and update player ratings",
      "inputSchema": {
        "type": "object",
        "properties": {
          "white_player_id": { "type": "string", "description": "White player identifier" },
          "black_player_id": { "type": "string", "description": "Black player identifier" },
          "result": {
            "type": "string",
            "enum": ["1-0", "0-1", "1/2-1/2"],
            "description": "Game result in standard notation"
          },
          "pgn": { "type": "string", "description": "Full game PGN (optional)" },
          "time_control": { "type": "string", "description": "Time control (e.g., '10+0', '3+2')" }
        },
        "required": ["white_player_id", "black_player_id", "result"]
      },
      "annotations": {
        "readOnlyHint": false,
        "destructiveHint": false,
        "idempotentHint": false
      },
      "tags": ["rating", "game"]
    }
  ]
}