Skip to content

Tighten MCP tool schema conventions - #229

Merged
nathanjcochran merged 5 commits into
mainfrom
nathan/improve-mcp-tool-patterns
Sep 15, 2026
Merged

nathanjcochran merged 5 commits into
mainfrom
nathan/improve-mcp-tool-patterns

Conversation

@nathanjcochran

@nathanjcochran nathanjcochran commented Sep 14, 2026 •

Copy link
Copy Markdown
Member

Cleans up how our MCP tool schemas describe their fields, and documents the conventions in CLAUDE.md. Note that some of these issues were originally noticed when reviewing #228

  • Fields with an Enum no longer also carry Examples. The enum already lists every legal value, so the examples were redundant.
  • Sample values that were written inline in field descriptions now live in the Examples field instead. This covers a few input descriptions that repeated their own examples, and the output types for service_list and service_get, which had example values baked into their struct tags.
  • All field descriptions are now set in the Schema method rather than through jsonschema struct tags. Input types already worked this way, so output types now match, and everything about a field's schema lives in one place.
  • OpenWorldHint is now false on every tool. Our tools only ever touch the Tiger Cloud API and the user's own services, so none of them operate on an open world. Eleven tools had it set to true.
  • The nested output types for service_list and service_get had a Schema method that was never called, so the type enum it declared never reached clients. Those methods are now wired into the tools' output schemas.
  • CLAUDE.md's MCP section now spells out the Examples versus Enum rule, says that descriptions belong in the Schema method, notes that nested output types have to be wired in by hand, notes that the MCP SDK applies schema defaults before a handler sees the input, and describes how tools set their annotations.

@nathanjcochran nathanjcochran self-assigned this Sep 14, 2026
@nathanjcochran
nathanjcochran merged commit be08ba0 into main Sep 15, 2026
2 checks passed
@nathanjcochran
nathanjcochran deleted the nathan/improve-mcp-tool-patterns branch September 15, 2026 15:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants