An agent tool connects a model request to deterministic software. The model selects the tool and supplies arguments from natural-language context. Application code validates the request, checks permission, runs the operation, and returns a result.
This differs from a conventional function call because the caller is probabilistic. The model may choose the wrong tool, omit a field, confuse two similar operations, or misread the result. Tool design must account for selection and interpretation as well as correct execution.
A technically correct API can still be difficult for an agent to use. Clear tools reduce ambiguity before the model call and provide useful evidence after it.
Define tools around clear operations
A tool definition includes a name, description, and input schema. Depending on the protocol, it may also include a title, icons, output schema, annotations, or execution settings.
The name identifies the operation. The description explains when to use it and how it differs from similar tools. The input schema defines required fields, types, and allowed values. The result tells the model what happened and provides information for the next step.
Tool scope should follow the tasks users ask the agent to complete. Exposing every backend endpoint can force the model to understand an internal service layout that normal clients hide. One large tool with many modes creates a different problem. The model must select the tool and then select an operation inside it.
Use names that state the resource and action. github.search_issues and linear.search_issues identify both the system and operation. Namespaces help when integrations provide similar actions.
Descriptions should include purpose, non-goals, required identifiers, side effects, and common errors. Examples help with formats and edge cases. State when the agent should call a lookup first, when several matches require clarification, and when another tool is more appropriate.
The best scope is empirical. Build a small catalog, test it on representative tasks, and inspect selection errors. Merge operations the agent always needs together. Split tools whose modes create repeated confusion.
Return enough information for the next step
Raw backend objects often contain more fields than the agent needs. Large responses use context space, expose unrelated data, and make the relevant result harder to find.
Search tools can return compact matches with stable identifiers and the fields needed to choose among them. A detail tool can load one selected record. A write tool can return the resulting state, provider operation ID, and whether the effect is final, pending, failed, or unknown.
This staged design supports large datasets and file systems. It also reduces unnecessary access to private fields. It is not required when one small response already contains the complete result.
Structured outputs help the client validate and parse results. The current Model Context Protocol supports an optional outputSchema. A conforming structured result can include structuredContent and may also include text or other content for compatibility.
Errors need a defined form. A protocol error means the client could not make or process the MCP request. A tool execution error means the tool ran but the operation failed. MCP recommends returning tool execution errors as tool results so the model can use the error and correct its next request.
Stable categories such as not_found, ambiguous_match, permission_denied, stale_version, and outcome_unknown support different recovery actions. Include enough detail to correct the request without exposing credentials or internal infrastructure.
Tool results from documents, email, websites, or external servers may contain prompt injection. Present them as untrusted observations with source metadata. Do not combine them with system instructions.
Validate the request and check permission
Schema validation checks form, not authority. A valid request can still target another tenant, exceed an approval limit, or use the wrong user's credential.
Before execution, resolve the acting user, organization, delegated role, task, resource, and policy. Reject unknown fields. Normalize identifiers. Apply range and size limits. Require approval for operations whose consequence needs human review.
Credentials should remain outside model context. A broker can select a short-lived credential scoped to the user, resource, and operation. The agent can request a calendar event without receiving the OAuth token used to create it.
External writes need safe retry behavior. An idempotency key tied to the run and proposed operation lets a service recognize a duplicate request. When a timeout leaves the result unknown, query the provider by operation ID before retrying.
For higher-risk writes, separate proposal from execution. The proposal includes exact arguments and relevant evidence. Approval applies to that proposal. The executor rejects a request if the arguments change or the approval expires.
Validate results before adding them to model context. Enforce output size, content type, and tenant scope. Remove secrets and private fields that the next decision does not require.
MCP standardizes tool discovery and calls
The Model Context Protocol defines how hosts, clients, and servers exchange tools, resources, and prompts. A server can list tools. A client can call a listed tool through a standard request. Servers can also notify clients that the tool list changed.
In the 2025-11-25 specification, tool names are case-sensitive and must be unique within a server. The tool input schema uses JSON Schema, with 2020-12 as the default dialect. Tool definitions can include an optional output schema and annotations about behavior.
Clients must treat tool annotations as untrusted unless they come from a trusted server. An annotation such as read-only or destructive describes intended behavior. It does not enforce policy.
The high-level MCP specification requires hosts to obtain user consent before exposing user data to servers or invoking tools. The tool specification also recommends confirmation for sensitive operations, showing tool inputs to the user, validating results, applying timeouts, and logging use. Product design must preserve the difference between protocol requirements and recommendations.
MCP standardizes communication. It does not enforce access control, approve actions, sanitize every result, or decide which server the product should trust. Hosts and servers still need authorization, input validation, rate limits, output controls, and audit records.
Remote tool definitions can change. Record the server identity and capability set used by a run. Evaluate catalog changes before broad release. Do not assume that a previously reviewed server will always advertise the same tools.
MCP clients discover tools through tools/list, which supports pagination. A server that declares the list-changed capability can send notifications/tools/list_changed. The client can then request the list again. A notification should trigger discovery and policy review, not automatic trust in every new tool.
Large catalogs need selection rules. A host may expose only the tools relevant to the current task, user, and permission set. This reduces context use and prevents the model from requesting operations that the user cannot perform. The execution layer must still enforce permission even when the host filtered the list.
Tool names must be unique within one MCP server, but different servers can advertise similar names. The host should preserve server identity and present names that the model can distinguish. It should also handle a removed or changed tool without continuing a long-running task against an old definition.
Test tools on complete tasks
Tool tests should cover more than valid JSON. Run agents on tasks that require discovery, selection, several calls, and a verifiable outcome.
“Find customer 9182” tests a direct lookup. “Investigate why this customer received three charges, determine whether other accounts were affected, and prepare a remediation” tests tool choice, filtering, evidence, and restraint.
Measure task success, invalid arguments, wrong-tool selection, repeated calls, response size, latency, permission denials, and error recovery. Allow different valid sequences. Require the important constraints and final state.
Include negative cases. Test when the agent should not call a tool, when it should ask for an identifier, and when permission must block an otherwise valid request. Add each confirmed production failure as a regression case under the applicable data rules.
Small changes often improve results. Rename an ambiguous parameter. Require an absolute path. Add a filter to a search tool. Return a compact match list before full records. Separate a read from a consequential write.
Version tool names, descriptions, schemas, server capabilities, and executors with the agent harness and model. A definition that works with one model may produce different selection behavior after a model update.
Assign an owner to each tool. Remove deprecated operations, review overlapping names, and track performance by task. Add tools when they enable a defined outcome, not because another service is available to connect.
Review the tool catalog as one system. A new operation may reduce performance by making an existing choice ambiguous. Run catalog-level evaluations after adding, renaming, or removing tools. Keep the previous capability set available for rollback when a change affects active users.
Document retry behavior and side effects for operators as well as models. An operator needs to know whether a call can be repeated and how to check an unknown result. The documentation should identify which external system holds the final state.
An agent tool gives a model a defined operation and gives the application a point to validate, authorize, execute, and observe that operation. Clear definitions help the model select the right action. Deterministic controls decide whether the action may occur.