Tool Schema

A tool schema is the machine-readable definition of a tool that an AI model is allowed to call. It gives the tool a name, describes in plain language what the tool does and when to use it, and specifies the arguments it accepts as a JSON Schema 4. The model reads these schemas to decide whether a tool fits the user's request and to produce a call with correctly structured arguments. The application, not the model, then runs the tool. Tool schemas are the foundation of tool use and function calling and of tools exposed through the Model Context Protocol.

The parts of a tool schema

The field names differ slightly between platforms, but every tool schema carries the same core information. In the MCP specification a tool definition includes 1:

• name: a unique identifier, such as get_weather
• title (optional): a human-readable display name
• description: what the tool does, in words the model uses to choose it
• inputSchema: a JSON Schema describing the expected parameters, their types and which are required
• outputSchema (optional): a JSON Schema for structured results; when present, servers must return results that conform to it
• annotations (optional): hints about behavior, which clients must treat as untrusted unless the server is trusted

A minimal MCP tool definition, taken from the specification, looks like this 1:

{
  "name": "get_weather",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or zip code"
      }
    },
    "required": ["location"]
  }
}

How major platforms define tools

• Model Context Protocol: servers list their tools in response to a tools/list request, and clients invoke them with tools/call, passing arguments that match inputSchema. If no $schema is given, the schema defaults to JSON Schema 2020-12, and tool names should be 1 to 128 characters of letters, digits, underscores, hyphens and dots 1.
• OpenAI function calling: a function tool has type: "function", a name, a description, a parameters JSON Schema and a strict flag. With strict mode on, every object must set additionalProperties: false and every field in properties must be listed as required 2.
• Anthropic tool use: a tool has a name matching ^[a-zA-Z0-9_-]{1,128}$, a description and an input_schema, with optional input_examples. Claude returns a tool_use block that the application executes before sending back a tool_result 3.

How a tool call uses the schema

1. The application sends the user's message together with the available tool schemas.
2. The model decides whether a tool is needed and returns a call naming the tool, with arguments shaped by its schema.
3. The application validates the arguments and runs the tool.
4. The result goes back to the model, which answers or calls another tool 2.

Tool schemas are sent with every request, so they use up part of the model's context window and are billed as input tokens 2. Large tool sets therefore have a real cost.

Writing tool schemas that models use well

• Write detailed descriptions. Anthropic calls this "by far the most important factor in tool performance" and suggests at least 3 to 4 sentences covering what the tool does, when to use it and what it does not return 3.
• Use unambiguous parameter names, for example user_id instead of user 5.
• Namespace related tools with a service prefix so the model can tell similar tools apart as the list grows 3 5.
• Keep the set small and non-overlapping, and return concise, meaningful results rather than raw internal IDs 5.
• Validate on the server anyway. The MCP specification requires servers to validate all tool inputs and recommends that clients ask for user confirmation on sensitive operations 1.

Tool schema is not schema markup

The term is sometimes confused with Schema.org structured data, the JSON-LD markup websites add for search engines. A tool schema describes an action an AI agent can take; Schema.org markup describes a web page. Tool schemas use JSON Schema 4. Tool schemas are also distinct from structured outputs, which constrain the model's own reply to a schema rather than describing a callable tool.

Tool schemas in social media publishing

An MCP server for a publishing product is essentially a set of tool schemas. Publora, a social media scheduler and publishing API, exposes an MCP server with 18 tools across 10 platforms, for example a post-creation tool whose schema asks for the post content, the target platform IDs and an optional scheduled time 6. Clear descriptions and required fields let an agent schedule a post correctly instead of guessing.