Anthropic CCA-F: Designing Safe MCP Tool Contracts for Claude

An MCP integration depends less on transport than on the precision, validation, and authorization boundary of each tool contract. Claude sees a name, description, input schema, and eventually a result. From that limited interface it must decide whether the tool is appropriate, construct valid arguments, interpret the outcome, and determine the next step. A Claude Engineering tool contract should function like a typed API for an intelligent caller: narrow in authority, precise in validation and clear enough for reliable selection.

Claude supports strict argument generation for supported client tool schemas, while an MCP server separately owns validation and authorization at execution time. The July 2026 MCP specification permits JSON Schema 2020-12 constraints in tool input and output schemas, but not every client or older SDK necessarily implements the same protocol revision. A structurally valid request can still target another user’s resource or violate a business rule. Names, descriptions, enums, stable identifiers, side effects and result semantics therefore belong in the contract alongside server-enforced policy.

Give each tool one clear business purpose

A tool should answer one question or perform one coherent action. Avoid broad tools such as manage_customer that can search, edit, delete, and message depending on optional parameters. Separate capabilities make selection easier and permissions safer because the effect of a call is visible from the tool name itself.

Agent tool reasoning becomes more reliable when the model chooses among semantically distinct operations. The backend can also apply different approval, audit, and rate-limit policies to reads and writes without parsing a generic command object.

Write descriptions that explain when to use the tool and when not to

The description is part of the model’s routing logic. State the capability, important preconditions, and exclusions. If a tool searches only active orders, say so. If a tool sends an external message immediately, say that it has a side effect. If another tool should be used for historical data, mention the distinction.

Descriptions should not become mini prompt documents full of policy that the executor ought to enforce. API security requires server-side checks even when the description tells Claude what is allowed. Documentation guides the caller; enforcement protects the system.

Use the narrowest JSON Schema that represents valid requests

Prefer typed fields, required properties, enums, bounded numbers, and explicit arrays over one free-form string. If an action supports only three deployment environments, use an enum rather than asking Claude to invent a name. If a field is required to execute safely, make it required rather than hoping the model includes it.

Anthropic’s agent security boundary improves when the schema removes impossible or dangerous combinations before execution. Strict tool use can guarantee schema conformance, but the schema itself must encode the right constraints. A permissive schema can be strictly followed and still be unsafe.

Prefer stable identifiers over ambiguous human-readable names

Names collide, change, and can be misspelled. When a tool acts on an existing resource, prefer stable IDs selected from a prior lookup result. The lookup can return both an ID and a display label, allowing Claude to reason with understandable text while the executor receives an unambiguous reference.

This is especially important for consequential actions. Approval boundaries are clearer when the confirmation shows the display name but the transaction is bound to the immutable ID. That prevents a later rename from redirecting an approved action.

Make side effects and idempotency explicit in the contract

A caller should know whether the tool is read-only, creates a resource, updates one, sends something externally, or deletes data. For operations that might be retried, include an idempotency key or request identifier when the backend supports it. The executor should return the original result if the same request is safely replayed.

Agent lifecycle management needs this because retries can come from network failures, orchestration recovery, or model replanning. A tool contract that makes duplicate side effects impossible is more robust than a prompt that merely tells Claude “do not call twice.”

Return structured outputs that distinguish result, status, and evidence

Keep the MCP protocol envelope separate from your domain result. Under MCP 2026-07-28, each response carries a resultType: complete for an ordinary finished result or input_required when a multi-round-trip interaction still needs authorized input. A completed tool result can carry text content, structured data and an isError indication; its application payload should use stable status, resource ID, warnings and evidence fields. Return resource links for large output rather than flooding model context, and test the declared output schema against the structured content.

GenAI observability also benefits from stable result fields because logs can capture operation IDs and error classes without recording sensitive payloads. The result contract should help both the model and the operator understand what happened.

Design errors as part of the normal contract

Do not reduce every failure to “tool failed.” A tool execution error signaled through isError is not interchangeable with a JSON-RPC protocol error or a legitimate input_required response. Distinguish invalid input, unauthorized access, missing resources, conflicts, throttling and transient dependencies with stable diagnostic details. Do not retry a mutating call merely because its response was lost: first reconcile the operation identifier and actual side effect. The server must still reject unauthorized requests even when their JSON Schema is valid.

Claude can then choose a better next step: ask the user for missing information, select another resource, wait and retry, or stop. Reliable AI systems are built from predictable failure behavior, not only successful calls.

Keep secrets and privileged context out of schemas and result payloads

A tool schema is visible to the model and may be cached or logged by supporting infrastructure. Do not put secrets, protected health information, private tokens, or sensitive constants into property names, enum values, examples, or descriptions. Pass sensitive values through the executor’s credential system rather than asking Claude to supply them.

Identity architecture should decide which credential the executor uses for the action. The tool call should express intent and resource scope, not carry raw authority. This separation is especially important for remote MCP servers shared by multiple users or agents.

Version contracts through additive change before breaking change

Tool contracts evolve. Add optional fields before making them required, preserve output fields where possible, and introduce a distinct tool for materially different side effects rather than silently changing behavior. Contract tests should cover representative arguments, server-side permission denials, complete and input_required result handling, and the protocol revisions actually supported by the connected SDKs. Schema compatibility does not by itself prove wire-protocol compatibility.

Anthropic and MCP give models a standardized way to call tools, but reliability comes from disciplined contracts. Clear purpose, precise descriptions, constrained schemas, stable identifiers, explicit side effects, structured results, typed errors, and secure credential handling make the agent easier to trust. The best tool contract is one where both Claude and a human reviewer can predict what a valid call means before it runs.

Optional parameters deserve careful review because they are a common source of ambiguity. A field should be optional only when the server has a safe, deterministic default. If omitting a destination, environment, or scope could cause the backend to guess, make the field required or split the operation into separate tools. Hidden defaults are convenient for human SDK users but can be dangerous for model-driven execution.

Units and formats should be explicit. Use ISO timestamps, currency codes, normalized time zones, bounded integers, and documented enum values rather than strings such as “tomorrow morning” or “about five hundred.” If the application accepts natural language, normalize it in a separate interpretation step and show the resolved value before a consequential call. Tool contracts are strongest when execution parameters are unambiguous at the boundary.

Schema changes should be tested against real model behavior, not only conventional clients. A new optional field or renamed description can alter which tool Claude selects even when every old request remains valid. Keep representative agent conversations in regression tests and compare tool-selection accuracy before deploying contract changes. Model-facing APIs have a semantic compatibility surface in addition to a syntactic one.

Use examples carefully. A concise example can clarify a complex field, but examples can also bias the model toward one value or pattern. Prefer descriptions and enums that encode the real domain. When examples are necessary, vary them across tests so the agent learns the contract rather than merely copying a sample. The contract should remain understandable when the example is removed.

Authorization-relevant fields should be independently validated even when strict schema validation passes. A schema can prove that account_id is a string; it cannot prove that the caller may act on that account. The executor should derive allowed scope from identity and compare the requested resource against it. This keeps the tool contract expressive without turning model-supplied parameters into authorization claims.

Result schemas should be stable enough for multi-step reasoning. If one tool returns customerId and another expects customer_id, Claude may bridge the difference, but every translation is another opportunity for error. Shared identifier conventions, timestamp formats, and status enums reduce cognitive load across the toolset. A coherent contract family often improves agent reliability more than adding another paragraph to individual tool descriptions.

Finally, measure contract quality in production. Track validation failures, tool-selection corrections, retries caused by ambiguous errors, and calls that users later undo. Those signals reveal where the schema or description is confusing the model. Contract design should improve from observed failures just like any other API: the goal is not a theoretically elegant schema, but one that produces safe and predictable behavior across real conversations.

Small contracts are easier to secure.

Leave a Reply

How It Works

img
Step 1. Choose Exam
on ExamLabs
Download IT Exams Questions & Answers
img
Step 2. Open Exam with
Avanset Exam Simulator
Press here to download VCE Exam Simulator that simulates real exam environment
img
Step 3. Study
& Pass
IT Exams Anywhere, Anytime!