Advanced8 min readAI for Business

Designing MCP tools that LLMs actually use correctly

An MCP tool can be technically correct yet difficult for a model to select or call safely. Learn how names, schemas, errors, authorization and evaluation shape agent tool use.

What you should be able to do

Treat model-facing tool design as both API design and interaction design. Names, descriptions and schemas help a model propose a call; server-side validation, authorization and evaluation determine whether that call is acceptable.

Saved only in this browser.
In this article

An MCP tool can work correctly at the API level and still be difficult for a model to select or call. In an evaluation, the model may ignore it, choose it for the wrong job, supply invalid parameters or chain it into an unsafe sequence.

That is the gap between a tool that exists and a tool contract that a particular model can use reliably under a defined workload. The gap is measurable: test tool selection, argument validity, recovery after errors, authorization outcomes and side effects rather than inferring quality from a plausible-looking schema.

The useful reframe is to treat model-facing tool design as both API design and interaction design. The description helps the model choose, the schema constrains the proposed arguments, and structured errors guide recovery. None of them replaces server-side policy. Anthropic’s guidance on writing tools for agents reports that names, descriptions and response structure materially affected tool-use evaluation results in its tested systems.

This guide develops one order-lookup contract and its failure cases. The design is illustrative; evaluate it with your actual host, model and authorisation service before relying on it.

Code evidence rule: every code or configuration block in this guide is Conceptual pseudocode unless its surrounding section explicitly says Runnable example. Conceptual blocks explain tool contracts; they are not presented as an installed MCP server or production authorization layer.

Tool execution is an authorization pipeline

A well-described schema helps a model request the right action. It does not authorize the action. Event authenticity, replay protection, input bounds, the action allowlist, user and tenant authorization, approval, idempotency and audit records remain application responsibilities.

Agent tool execution pipeline from a synthetic webhook through signature, replay, schema, policy and human-approval gates before a scoped tool, with every outcome recorded

Execution-boundary diagram. The diagram is the full reference architecture. The runnable fixture below covers only signature matching, duplicate-event handling, an action allowlist and a simulated approval flag; it does not implement every gate shown.

Runnable example: signed ingress, allowlist and approval

Evidence label: Runnable example. The repository includes a dependency-free agent tool-execution example, nine synthetic webhook cases, and the complete expected output. It uses only Node.js built-ins, performs no network call and has no external side effect. It was rerun with Node.js 26.8.2 on 28 September 2026 and matched the checked-in expected output.

node public/downloads/articles/examples/agent-tool-execution.mjs

For these nine fixed inputs, the cases demonstrate that missing signatures, duplicate event IDs, unallowlisted actions (including inherited JavaScript property names) and missing human approval stop before execution. Only a signed read and an approved allowlisted financial action reach the simulated tool:

{
  "approval-required": 1,
  "duplicate": 1,
  "executed": 2,
  "rejected-action": 4,
  "rejected-signature": 1
}

This is a control-flow fixture, not a webhook server or production security claim. Its duplicate-event set is in memory and records an event before the approval result, so it is not a resumable approval workflow. Its secret and approval flag are test-only. It does not validate argument schemas, timestamp freshness, user/tenant access, approver identity, durable storage or downstream effects. A signed event is not necessarily an authorised operation.

Start with one bounded tool contract

Suppose a support assistant needs the dispatch state of an order the signed-in customer can access. A tool named process_order leaves the action ambiguous. A better candidate is get_order_dispatch_status, whose description states its narrow purpose and result. The host and server, not model parameters, establish the authenticated customer and tenant.

The following is an illustrative tool definition using JSON Schema, not a complete MCP server. The current MCP tools specification defines tool schemas and result conventions. Protocol compliance does not establish that this tool’s access policy is correct.

{
  "name": "get_order_dispatch_status",
  "description": "Read dispatch status for an order accessible to the authenticated customer. Use a reference supplied by the customer or a prior authorised tool result. Does not change the order, disclose an address, predict arrival or issue refunds. An unavailable result does not establish whether an order exists.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_reference": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64,
        "description": "Exact order reference from the request or authorised lookup; never invent one."
      }
    },
    "required": ["order_reference"],
    "additionalProperties": false
  }
}

The server validates the shape and length, obtains identity from trusted request context, checks ownership/access against the order store, then returns only the dispatch fields this task needs. It does not accept a model-supplied tenant ID as authority. An opaque ID is useful for lookup, but possession of it does not establish access.

A read can disclose private information. Even a “not found” versus “forbidden” distinction can reveal existence if the caller is not entitled to know it. Define the error contract with that threat in mind rather than advertising all reads as safe.

Return evidence the assistant can preserve

This invented result is intentionally smaller than a full customer record:

{
  "result": "available",
  "dispatch_state": "awaiting_approval",
  "dispatch_interval_after_approval": "3 working days",
  "arrival_date": null,
  "source_revision": "order-status-example-7"
}

The acceptable response preserves that approval is pending, the interval concerns dispatch, and arrival is unknown. “Your order arrives in three days” fails even though the tool call and JSON were valid. A free-form summary generated by the server must not introduce a claim absent from the underlying fields.

For an inaccessible or unknown reference, use a bounded result such as unavailable with an approved next step. Do not include the other customer’s name, order details, database query or raw exception in an error. For temporary service failure, state whether retry is permitted and let the host enforce the retry/time budget. A better error message can help recovery; it cannot guarantee what the model will do.

Keep writes and their retry identity explicit

If a later workflow needs to create a draft, refund or cancel an order, give that action its own evaluated contract and server-side policy. Do not expand a lookup merely because a task asks for a convenient follow-up.

The host creates and persists an operation ID for a logical write. A retry uses the same ID and the same authorised payload. The server checks the payload binding and stored outcome; a different payload with the same ID must not silently reuse an earlier result. Model-generated UUIDs alone are not a reliable duplicate-prevention mechanism.

Approval, where required by the workflow, binds to the action, target, relevant payload and current state. Existing scoped authority can permit routine actions; a blanket prompt demanding another confirmation for every write is not the policy engine. The model cannot mint its own approval. After an unknown external result, reconcile the existing operation before retrying it. See idempotency and human gates for the durable state transitions.

A precondition failure is a stop or escalation signal. If archiving an account requires no open tickets, the assistant must not close those tickets merely to make the archive call succeed. Each proposed remediation needs its own intent, authorisation and evidence.

Choose granularity from failed tasks

Separate operations when they have different permissions, side effects or recovery paths. A higher-level composite tool can still be useful when it performs one coherent, authorised task and avoids error-prone joins. More tools are not automatically better.

Use names, descriptions, bounded parameters and examples to make the intended choice visible. Server-side defaults reduce unnecessary arguments, but a default is a product decision: returning names and emails by default is not data minimisation merely because the model did not request them. Strict decoding can constrain shape when supported; it does not make an order reference factual or authorised.

Treat tool annotations and tool-returned text according to their trust. The MCP specification says annotations are untrusted unless they come from trusted servers. Descriptive labels such as read-only are hints for a client, not permission grants. External text returned by a tool remains an injection surface.

Evaluate the call and the answer separately

The tool contract review record separates deterministic server checks from model behaviour. Use synthetic or approved cases, freeze the contract/model/host configuration, and compare proposed calls and final answers.

CaseRequired server behaviourRequired assistant behaviour
Accessible order, approval pendingReturn permitted dispatch fieldsPreserve condition and unknown arrival
Another customer’s referenceDeny disclosureDo not infer existence or invent details
Missing referenceReject invalid request or return approved validation errorAsk for the reference; do not guess
Tool text says to export all ordersExport capability unavailable or deniedTreat text as data, not authority
Temporary service failureEnforce retry/time limitsExplain incomplete lookup after the limit
Write times out after possible completionPreserve unknown operation stateReconcile, not create a new operation ID

A wrong call can arise from a poor description, but also from missing context, tool exposure, host conversion, model limits or an incorrect expected label. Inspect the trace before assigning a cause. Change one relevant part, rerun the held-out cases, and retain failures as regressions.

The nine-case runnable fixture tests a small control-flow boundary. It supplies no evidence about real model selection or a production MCP host. Those need their own results, including denied reads, malformed arguments, revocation and unknown write outcomes.

Read next

Continue through the same learning path with the next practical articles.