0001: M0 core API¶
Status: accepted for M0, open for revision in M1.
Problem¶
Developers need a way to write MCP tools that are lean by default without learning a new framework from scratch, and the framework needs to measure what it costs.
Proposal¶
server = OunceServer("inventory", budget=Budget(result_tokens=2_000), output_schemas=True)
@server.tool(name="inventory.search", effect=Effect.READ, deadline_ms=5_000, result_tokens=None)
async def search(args: SearchInput, ctx: ToolContext) -> SearchResult:
"""One-line description the model reads."""
Rules enforced at registration:
effectis required (Effect.READ,Effect.WRITE,Effect.DESTRUCTIVE).- Tool names match
^[A-Za-z0-9_.-]{1,128}$and must be unique. A description (docstring or argument) is required. - The return type must be a Pydantic model.
- Inputs are either one Pydantic model, whose fields are flattened into the tool schema, or plain typed parameters.
- Credential and identity parameters (
api_key,token,password,tenant, and similar) are rejected. Identity comes from the transport, not the model. response_format(conciseordetailed) is added to the schema only when the output model hasDetailfields.
Result shaping:
- Concise results drop
Detailfields and unset optional fields. - Results that exceed the budget are trimmed: the largest lists first (never to zero items), then the longest strings, then, as a last resort, the serialized text.
- A note is appended to the text content:
[ouncemcp] Result truncated to fit N tokens: kept X of Y items in 'path'. .... If the result also carries a cursor, the note warns that the cursor skips removed items. - Shaping metadata goes in
_meta.ouncemcp(result_tokens,budget,format,truncated,truncation).
Alternatives considered¶
- A
fieldsparameter instead ofDetail. This is more flexible, but it costs schema tokens on every tool and the model has to guess field names. It may come later as an opt-in. - Raising an error on oversize results. This is safer for structured clients but worse for agents, which usually do better with a partial result plus a note. It stays the planned fix only for the text-only fallback case.
- Counting the in-process tool object. This was rejected because field order differs from the wire and the counts drifted.
Impact¶
On the inventory example: definitions are 488 tokens (versus 195 for plain FastMCP), and a four-task session uses 1,510 tokens versus 32,280. Added server time is 0.14 to 0.44 ms at p50, and 1.44 ms when truncating. See docs/m0-report.md.
Open questions for M1¶
- Should output schemas default to off for hosts that do not use them?
- Budget-aware pagination (
ctx.fit()), so handlers can set cursors after shaping. - Behavior of the text-only fallback when an output schema is advertised.