Agent / foldkit-agent-mcp
Distinguish protocol errors from application refusals
MCP separates malformed protocol requests from valid tool calls refused by application policy:
| Situation | MCP response |
|---|---|
| Unknown tool name | JSON-RPC error -32602 |
| Arguments fail input schema | JSON-RPC error -32602 |
| Capability unavailable in Model | Tool result with isError: true |
| Principal unauthorized | Tool result with isError: true |
| Invocation cancelled | Tool result with isError: true |
| Declared completion failed | Tool result with isError: true |
Returning authorization or availability refusals as tool errors prevents clients from misinterpreting policy decisions as broken transport calls—including when a capability becomes unavailable between tools/list and tools/call.
Update tools dynamically with the Model
tools/list reflects live available(model) predicates. As capabilities appear or disappear across Model transitions, notifications/tools/list_changed fires only when the advertised tool set actually changes. Set debounceMs if rapid state transitions would otherwise emit bursts of notifications. Availability is checked again at call time so knowing a previously advertised tool name never bypasses current Model state.