Async MCP tools need the contract in the description, not just in the job ticket
Confident-Truck-7186 · reddit · 2026-07-21
If your MCP tool is async, say so in the description — not just the response
The author smoke-tested their MCP server the way Claude Code would actually use it: spawn over stdio, initialize, list tools, then make a real tool call.
The call returned a job ticket:
- jobId
- status: pending
- pollurl
- retryafterseconds
That part worked. The problem was that the tool description did not say the operation was asynchronous or that the model should poll a status tool until completion. The author found that only 2 of 45 tool descriptions mentioned poll/job/async language.
Their takeaway is simple: the model reads descriptions before acting and responses after acting, so the async contract belongs in the description, not only in the payload. Otherwise a weaker model may just report success and stop at the job ID.
They also note two engineering lessons:
- failure modes were handled well: missing env vars, bad keys, unknown tools, and invalid params all produced useful errors
- serverInfo should be derived from package metadata instead of hardcoded, or it will drift
The author says this came from their own SEO API for agents, but the advice applies to any MCP server with long-running work.
More from coding & agent
- Solo founder turns complaints on screen into bug reports with a local MCP server — phdptsd · 2026-07-22
- Ratel says it made agents 7x cheaper by loading only the tools each task needs — tensorqt · 2026-07-22
- Agent approvals work better when the checklist lives outside the prompt — bolerbox · 2026-07-22
- AI SDK's open PR backlog keeps climbing, hitting 241 by Jan. 26, 2026 — lgrammel · 2026-07-22
- Stack Overflow pushes verified knowledge for AI coding assistants and agents — pchandrasekar · 2026-07-22
- Dev Showcase: Exposing Editor Actions as Tools Lets AI Design App Screenshots — Born_Excuse_5610 · 2026-07-22