An agent asks a tool to create a work item. The destination creates it, but the response never reaches the agent. The agent retries and creates another. The problem began with a missing answer to a basic interface question: what should the caller do when it cannot tell whether the action happened?
Describe what each action changes
For an illustrative task-management tool, distinguish creating a draft from committing a work item. Specify the required fields, allowed project scope and result. State whether the operation can be repeated safely and how duplicate requests are recognized.
A tool named process_request hides too many choices. A more explicit operation lets the caller understand whether it is reading, preparing or changing something. The service must enforce the permitted action and validate its inputs; a descriptive tool name alone is not a control.
Identify work across retries
Attach a request or operation identifier according to the destination’s supported design. Return it with the accepted state and provide a way to query the result. If the first response is lost, the workflow can establish whether the action completed before deciding what to do next.
Where the destination cannot provide duplicate protection or reliable status, document that limitation. A human review step may be necessary for an uncertain write. Repeating a consequential action until a success message appears is an unsafe default.
Distinguish errors from uncertain results
OWASP’s MCP security guidance covers tool integrity, schema validation, restricted authority and human review for sensitive operations. Applying those principles here means giving the caller precise states and keeping consequential decisions in enforceable service logic.
An invalid field can be corrected. A permission denial requires an authorized decision. An unknown outcome requires reconciliation with the destination. Returning the same generic error for all three encourages the workflow to use the wrong recovery action.
Source: OWASP · MCP Security Cheat Sheet.
Test a missing response
Use a synthetic destination and disposable records. Exercise a normal creation, a repeated request, invalid input and a denied project. Then deliberately lose the response after a successful write. Inspect both the tool trace and the destination state.
- The normal request creates the intended item once.
- The duplicate follows the documented policy.
- The denied request changes nothing in the restricted project.
- The missing response can be reconciled without a blind second write.
Define a verifiable result
The agent’s final message should reflect the established result. “Created” belongs to a confirmed write. An unresolved operation deserves an explicit uncertain state and a useful next step. This small distinction prevents fluent language from covering a gap in the system’s knowledge.