Tool design and Model Context Protocol

Episode Three turns safe orchestration into safe capability design. By the end, you should be able to design narrow tool contracts, distinguish schema validity from business validity, choose between tools and resources, and place Model Context Protocol inside a least-privilege boundary. Now focus on the contracts those agents can invoke. A tool is not merely an A P I endpoint copied into a schema. It is a deliberately designed model-facing contract with a name, purpose, input structure, output structure, permissions, and failure behaviour. What makes a good tool name? It should express one clear operation in language the model can distinguish from neighbouring operations. Therefore, get case and search cases should not share an ambiguous description suggesting they are interchangeable.

Text description

• One “manage case” tool: Bundles reading, updating, closing, deleting, paying, and escalating behind one vague action field.
• Narrow read tool: Returns a case summary and can be made broadly available where read access is appropriate.
• Narrow change workflow: Creates a pending status-change proposal; a separate authenticated human-controlled service performs approval.

A good description states when to use the tool, when not to use it, important preconditions, and what the result means. Descriptions are part of the reasoning interface, while backend validation remains the enforcement interface. Harbour Resolution currently exposes one tool called manage case. It accepts an action string that can read, update, close, delete, pay, or escalate. What is wrong with that design? It bundles unrelated risk levels, creates a vague schema, complicates authorisation, and gives the agent excessive capability. Therefore, separate read operations from write operations and split materially different actions into narrow contracts. A read case summary tool can be available broadly.

Text description

• Schema validation: Constrains types, required fields, enumerations, ranges, and nested structure.
• Business validation: Checks domain facts, such as whether a supplied date can validly occur in the case timeline.
• Authorisation: Uses trusted caller identity and tenant state; it never trusts a customer identifier supplied by the model.

A propose status change tool can create a pending request without changing the case. An approve status change service can require an authenticated human role outside the model's control. A narrow tool also produces cleaner telemetry and easier evaluation. What should the input schema accomplish? It should constrain types, required fields, enumerations, ranges, and nested structure as far as the interface supports. However, structural validation cannot express every business rule. A valid date string may still precede the complaint's creation date. A valid customer identifier may belong to a tenant the caller cannot access. The service therefore repeats validation and authorisation using trusted identity and domain state.

Never infer authorisation from a customer identifier supplied by Claude. How should output be shaped? Return only what the next reasoning step needs, in stable fields with identifiers, provenance, and explicit absence or uncertainty. Distinguish no result from service failed. An empty matches array means the search completed with no matches. A status of temporarily unavailable means the search did not establish whether matches exist. Collapsing both into nothing found can produce false conclusions. A structured error might include code, safe message, retryable, and corrective fields. For example, missing required evidence is not retryable until new evidence is supplied. Rate limited may be retryable after a stated delay.

Permission denied should not invite the agent to rephrase the same prohibited request. Should raw backend exceptions be sent to Claude for better debugging? No. The adapter should log restricted diagnostic detail separately and return a safe normalised error contract. Raw errors can expose secrets, internals, or untrusted text. Now consider tool selection. Automatic selection is useful when Claude should decide whether and how to call among permitted tools. A forced tool is useful when the application requires a particular structured operation, such as extracting a known schema. Disabling tools is useful for a pure drafting or explanation phase. The choice belongs to the orchestrator and should reflect the workflow state.

Text description

• Tools: Perform operations or controlled queries and may have side effects.
• Resources: Expose addressable context such as documents, schemas, logs, or records.
• Prompts or workflows: Provide reusable interaction templates when supported by the client.

Do not rely on a system prompt saying avoid payment tools while leaving them available in a read-only phase. Remove or deny the capability in that phase. This leads to Model Context Protocol, or M C P. M C P standardises how an artificial intelligence application discovers and uses external context and capabilities. At an exam level, distinguish tools, resources, and reusable prompts or workflows. Tools perform operations and may have side effects. Resources expose addressable context such as documents, schemas, logs, or records. Prompts expose reusable interaction templates where the client supports them. Why not turn every document into a tool call? A resource better represents retrievable context, while tools are clearer for operations and controlled queries.

Text description

• Model-facing description: Explains when a capability is useful; it is not an access-control list.
• Client and token scope: Authenticate the client, allow only required tools, scope tokens, and protect secrets.
• Server enforcement: Authorise every operation, validate inputs, limit outputs, and reject model-generated claims of identity.
• Security records: Log security-relevant events while keeping restricted diagnostics and raw backend errors away from the model.

However, an M C P server may still expose a search tool that returns references to resources. The important point is semantic fit rather than forcing every integration into one primitive. An M C P server sits across a trust boundary and needs the same architectural discipline as any service integration. Authenticate the client, authorise every operation, scope tokens, protect secrets, validate inputs, limit outputs, and log security-relevant events. Tool descriptions are not access-control lists. Environment variables can provide configuration to a local server, but secrets should be managed through the platform's approved secret mechanism. For remote M C P, transport security and token handling matter, and the server must not trust model-generated claims of identity.

Text description

• Monolithic context: Loads hundreds of definitions and schemas into each request, increasing context cost and selection confusion.
• Progressive discovery: Starts with a small capability surface, then finds the relevant subset through a directory or secure search capability.

The current Claude platform can also connect directly to remote M C P servers through an M C P connector with per-server and per-tool configuration. That convenience does not remove the need to allowlist only required tools. What is progressive discovery? Expose a manageable capability surface first, then let the system discover more detail or specialised tools when the task requires them. Dumping hundreds of tool definitions and schemas into every request increases context cost and selection confusion. A directory or search capability can reveal a relevant subset, provided discovery itself is secure and observable. The Professional exam treats progressive discovery versus monolithic context as an explicit integration trade-off.

For Foundations, understand the practical effect on tool selection and context quality. Claude Code includes built-in tools such as reading, writing, editing, shell execution, text search, and file matching. The exam guide names Read, Write, Edit, Bash, Grep, and Glob as capabilities whose scope should match the task. A code-explanation agent may only need reading and search. A remediation agent may need edit and test execution but should still operate inside a constrained repository and permission policy. Why is shell access especially sensitive? Because one general command interface can reach files, networks, processes, package managers, credentials, and destructive operations. Therefore, sandboxing, command policy, approvals, and environment isolation matter more than friendly instructions.

Episode Three is complete when every capability has a clear purpose, narrow permission, validated contract, safe failure mode, and accountable owner. For source navigation, use the tool-definition and strict-tool-use references beside the Model Context Protocol tools specification, client guidance, and security material. In the next episode we will configure Claude Code so teams receive useful context without mistaking instructions for enforcement.