Tools: Discovery, Schemas, Invocation, and Results

Why tools exist

Tools are model-controlled capabilities that perform queries, calculations, or actions. The client discovers tool definitions through tools/list and invokes a selected tool through tools/call.

A good tool contract

• A specific, stable name: orders.lookup.
• A clear description of its purpose and limitations.
• A strict input schema with meaningful field descriptions.
• An output schema when machine-readable results are useful.
• Narrow permissions and predictable errors.
• A clear separation between read and write operations.

{
  "name": "orders.lookup",
  "description": "Look up one order visible to the authenticated user",
  "inputSchema": {
    "type": "object",
    "properties": {
      "orderId": { "type": "string", "pattern": "^ORD-[0-9]+$" }
    },
    "required": ["orderId"],
    "additionalProperties": false
  }
}

Result design

Human-readable content provides the host with displayable content or a fallback. structuredContent provides predictable fields. If an output schema is declared, the server should conform to it, and the client should validate the output.

Do

• Reuse domain services.
• Define timeouts, pagination, and rate limits.
• Provide confirmation flows for sensitive writes.

Do not

• Expose a single, all-powerful run_any_sql tool.
• Put secrets or internal credentials in tool descriptions.
• Rely on the model prompt for authorization.