{"schemaVersion":"1.0.0","id":"the-interface-is-a-contract","slug":"the-interface-is-a-contract","title":"The interface is a contract","description":"Why a small tool schema can be the most useful part of an agent system.","category":"Field notes","tags":["MCP","Agents","Design"],"date":"2026-09-29","updated":"2026-09-29","author":"PlainNerd editorial","readTime":3,"illustrationKind":"workflow","status":"published","evidenceStatus":"reference-guide","locale":"en","originalLocale":"en","content":{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Reference guide. This article draws on primary documentation and editorial recommendations; no production measurements are reported."}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Make the action understandable"}]},{"type":"paragraph","content":[{"type":"text","text":"A tool name should describe what it does. Its parameters should make required choices explicit, and its result should tell the caller what happened. Ambiguous interfaces shift work into prompts and make failures harder to inspect."}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Describe a useful boundary"}]},{"type":"paragraph","content":[{"type":"text","text":"Prefer a tool that represents one coherent operation. Give inputs clear types, reject unsupported values, and document effects that extend beyond the current task. Separate reading information from changing it when those operations need different permissions."}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Return evidence"}]},{"type":"paragraph","content":[{"type":"text","text":"A useful result includes the outcome and enough context to verify it: a resource identifier, a version, or a structured error. Avoid treating a successfully sent request as proof that a downstream operation completed. Design the failure path as deliberately as the happy path."}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"text","text":"Read the architecture first"}]},{"type":"paragraph","content":[{"type":"text","text":"MCP describes a host-client-server architecture for connecting applications to capabilities and context. Use its primary documentation to understand the transport and lifecycle before inventing application conventions. The interface advice here is an editorial design approach, not a measured comparison."}]},{"type":"paragraph","content":[{"type":"text","text":"MCP: architecture overview","marks":[{"type":"link","attrs":{"href":"https://modelcontextprotocol.io/docs/learn/architecture"}}]}]}]}}