Tools and Schemas
Understand how tool descriptors, machine-readable schemas, and example payloads should work together in the MCP section.
This page explains the contract layer, human explanation, machine-readable schemas, and stable examples should cooperate without collapsing into one noisy surface.
Before you continue
Read these first if you want the current page to make more sense in the wider handbook.
Keep tools, schemas, and examples separate enough that machines can parse them reliably and humans can still understand why they exist.
The three layers
The MCP section works best when it separates three different things:
1. Human explanation
This is the prose that tells a reader or agent what the surface is for.
2. Machine-readable schema
This is the strict contract used for validation and tooling.
3. Worked examples
This is the practical bridge between concept and contract.
Each layer has a different job.
Why collapse is bad
If explanation, schema, and examples all merge into one noisy payload:
- machines parse less reliably
- humans understand less clearly
- maintenance becomes harder
The surface gets “richer”, but worse.
What good tool descriptors should emphasize
- explicit naming
- stable field contracts
- narrow descriptions
- predictable response shapes
- obvious links to schema and examples
What good schemas should emphasize
- strict field shape
- predictable validation rules
- minimal ambiguity
- no decorative prose
What good examples should emphasize
- real flow
- correct sequencing
- realistic payloads
- easy comparison with schema
Recommended next pages
- Continue with Schemas and Descriptors.
- Continue with Examples.
- Continue with MCP Overview.
Related pages
Open these pages when you want adjacent concepts, neighboring entities, or connected implementation context.
Schemas and Descriptors
Use this page when you need the strict machine-readable contract layer that tooling and validation can rely on.
Examples
Examples make the MCP section usable, they turn abstract descriptions into a sequence an agent or implementer can actually follow.
Discovery
This page explains the first machine-facing handshake, what an agent needs to learn before deeper integration and why discovery should stay boring.