Skip to main content

Writing great tool schemas for MCP

· 2 min read
Tony Lewis
MCPBundles

Schemas are the contract the model learns. Great schemas make tools discoverable, hard to misuse, and easy to recover from errors.

Principles​

  • Describe intent in natural language: one sentence on when to use the tool
  • Make inputs precise with JSON Schema: required vs optional, enums, formats, ranges
  • Provide examples: a couple of representative input objects aid few‑shot learning
  • Keep outputs compact: stable IDs, small summaries, explicit pagination cursors
  • Be idempotent where possible: retried calls should not duplicate side effects

Inputs: patterns that help models​

  • Use enums for modes instead of free‑text strings
  • Prefer oneOf for mutually exclusive shapes (e.g., search by id or query)
  • Add minLength, maximum, format (email, uri, date‑time) to reduce guessing
  • Use clear, snake_case field names that match domain language

Example (conceptual):

{
  "name": "publish_report",
  "description": "Publish an existing report to the team with an optional note.",
  "input_schema": {
    "type": "object",
    "required": ["report_id", "visibility"],
    "properties": {
      "report_id": {"type": "string", "minLength": 6, "description": "Stable ID"},
      "visibility": {"type": "string", "enum": ["private", "team", "org"]},
      "note": {"type": "string", "maxLength": 500}
    },
    "additionalProperties": false
  }
}

Errors: make recovery straightforward​

  • Validate server‑side and return structured errors with a machine‑readable code
  • Include a short, user‑safe message and optionally hints the model can act on
  • Map validation failures to schema paths so the model can fix a single field

Outputs: predictable and small​

  • Return stable identifiers and next actions (if any)
  • Include next_cursor and has_more for list‑style outputs
  • Avoid embedding large blobs; provide resource URIs for follow‑up reads

Testing schemas​

  • Write golden prompts that exercise valid and invalid shapes
  • Add fuzz tests for boundary values (empty strings, max lengths, enum typos)
  • Track error rates and tighten the schema where failures cluster

References​