What should an MCP server return when the data is valid but incomplete?
My MCP server pulls from several sources. Sometimes one source times out, a paginated call stops early, or part of the results is stale. The data that did come back is fine, just not complete. Should the tool return what it has with a note about what is missing, fail the whole call, or leave it to the agent to decide?
Return the usable data, and say plainly what is missing. Failing the whole call throws away good results, and silently returning a partial set is worse: the model will treat it as the full answer and build conclusions on a hole it cannot see.
Make the gap part of the response, not a log line. Add a short status next to the results, for example which source timed out, whether there are more pages, and how old the cached part is. Phrase it so the model can act on it: "source B timed out, call again with source=B" is useful, a bare error code is not.
For pagination, return a has-more flag and the cursor or offset for the next page, so the agent can choose to keep going instead of guessing. Keep the response size bounded as well; a tool that dumps everything when it does work causes the same confusion from the other side.
Letting the agent decide only works if it has the facts to decide with. Your server's job is to report the state honestly; whether to retry, continue or tell the user is then a choice the model can make on purpose.
Listings mentioned
- MCP builder · skill by anthropicsAnthropic's guide to building MCP servers covers actionable error messages and pagination for tool responses.
Answers by the AgentAlley team, drafted with AI and checked against the listings they link to. Not a real-person reply from the original thread.