Tool Definition

The unique identifier for the tool within the server's namespace. It must be a clear, alphanumeric string (often using snake_case) that the AI model uses to reference the tool in its reasoning.

• Example: get_current_weather or create_calendar_event
• Purpose: Provides a stable API for the model to call. Changing a tool's name is a breaking change for any client or prompt that references it.

A natural language explanation of the tool's purpose, behavior, and any critical constraints. This text is injected into the AI model's context to guide its decision on when and how to use the tool.

• Key Elements: Should state the tool's goal, the meaning of its inputs/outputs, and side effects (e.g., 'This tool charges the user's credit card').
• Best Practice: Write for the AI, not just humans. Be explicit about preconditions and outcomes to prevent misuse.

A JSON Schema object that rigorously defines the structure, data types, validation rules, and optional descriptions for all parameters the tool accepts.

• Core Function: Enforces type safety and validates arguments before the handler executes.
• Common Properties: type (e.g., object), properties, required array, and nested schemas for complex parameters.
• Example Schema: Defines that a city parameter is a required string and a unit parameter is an optional string that must be either 'celsius' or 'fahrenheit'.

The server-side implementation function (business logic) that executes when the tool is invoked. It receives the validated input arguments, interacts with the external system (API, database, script), and returns a result.

• Separation of Concerns: The definition is the interface; the handler is the implementation.
• Execution Flow: MCP Client → JSON-RPC Request → Schema Validation → Handler Execution → JSON-RPC Response.
• Responsibility: Contains all authentication, networking, error handling, and data transformation logic specific to the integrated service.

While not always explicitly defined in a separate schema, the tool's return value is a structured JSON object. Consistent output structure is crucial for the AI client to parse and reason about the result.

• Implicit Contract: The handler's return type forms an output schema.
• Best Practice: Document the output shape in the tool's description. For complex returns, some frameworks allow defining an output JSON Schema.
• Example: A weather tool should always return an object with { "temperature": number, "conditions": string }.

A Tool Definition does not exist in isolation. It integrates with several key MCP and API execution concepts:

• Schema Validation: The runtime process that checks tool inputs against the Input Schema.
• Tool Invocation: The JSON-RPC call from client to server that triggers the handler.
• API Schema Integration: The practice of automatically generating Tool Definitions from existing OpenAPI/Swagger specifications.
• Orchestration Layer: The system that manages the sequencing, error handling, and caching of multiple tool calls within an agent's workflow.

An MCP Tool is the executable function exposed by a server that a client can invoke. It is the runtime instantiation of a Tool Definition. The Tool Definition provides the contract (name, description, input schema), while the MCP Tool is the capability made available over the protocol.

• Invocation: A client calls the tool by sending a JSON-RPC request with arguments matching the input schema.
• Execution: The server's Tool Handler processes the request and returns a result.
• Example: A Tool Definition for search_database becomes an MCP Tool when the server advertises it during capability negotiation.

A Tool Handler is the server-side implementation function that contains the business logic executed when an MCP client invokes a tool. It is the backend code that fulfills the promise of the Tool Definition.

• Input Processing: Receives and validates the client-provided arguments against the Tool Definition's JSON Schema.
• External Integration: Typically contains code to call an internal API, query a database, run a script, or interact with an external service.
• Result Formatting: Returns a structured result (often a string or JSON object) that the client can inject into the model's context.
• Critical Role: The handler is where security, error handling, and idempotency are implemented for the tool.

JSON Schema is a declarative language for validating the structure and content of JSON data. In an MCP Tool Definition, the inputSchema property must be a valid JSON Schema object.

• Type Enforcement: Defines the required data types (string, number, object, array) for each input parameter.
• Validation Rules: Specifies constraints like required fields, enum values, minimum/maximum, and regex pattern matching for strings.
• Structured Output Guarantees: Ensures the AI agent generates correctly formatted arguments before the tool is invoked, preventing runtime errors.
• Example: A create_ticket tool's schema would define required fields for title (string), priority (enum: ["low", "medium", "high"]), and description (string).

Tool Invocation is the act of an MCP client sending a tools/call request to a server to execute a defined tool. It is the runtime execution of a Tool Definition.

• Request Flow: The client sends a JSON-RPC request containing the tool name and an arguments object.
• Schema Validation: The server validates the arguments against the tool's input schema before passing them to the handler.
• Result Flow: The server executes the handler and returns a response containing the content (result) of the tool call.
• Orchestration: Complex agent workflows involve sequential or conditional tool invocations based on prior results.

Capability Negotiation is the initial handshake process in MCP where a client and server exchange their supported protocol versions and the features they provide. This is how a client discovers the available Tool Definitions.

• Initialization: During connection setup, the server sends an initialize request to the client.
• Server Announcement: The server's response includes a capabilities object listing the tools it provides. Each listed tool corresponds to a Tool Definition.
• Client Subscription: The client indicates which capabilities (like tools) it wishes to use.
• Dynamic Tooling: This process allows tools to be added or removed from a server without client reconfiguration, as they are advertised dynamically.

Schema Validation is the process of verifying that the structure and data types of a tool's input arguments conform to its declared JSON Schema definition. It is a critical safety and correctness layer in MCP.

• Server-Side Enforcement: Occurs on the MCP server immediately upon receiving a tools/call request, before the Tool Handler is executed.
• Error Prevention: Rejects malformed requests with a clear error, preventing undefined behavior in the handler.
• Client-Side Guidance: The schema also guides the LLM in the client to generate valid arguments, acting as a form of structured output guarantee.
• Two-Phase Safety: Combined with client-side parsing, it creates a robust defense against malformed or malicious tool calls.