Search tools can return a concise answer
Add a response_format argument with "concise" and "detailed" values (default concise) to search tools, so the model can ask for a short answer and fetch detail only when needed.
Check schema-response-format · Schema and description quality · default severity: advice · rubric 2.1.0
What fails
Search results are often large. A response_format (or fields) argument lets the model ask for less.
The rule
You can enable both by exposing a simple response_format enum parameter in your tool, allowing your agent to control whether tools return “concise” or “detailed” responses
How to fix it
Add "response_format": { "type": "string", "enum": ["concise", "detailed"], "default": "concise" }.
- Add response_format with enum ["concise", "detailed"] and default "concise".
- In concise mode return IDs and one-line summaries only.
- Describe in the tool description what each mode returns.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'search_documents',
{
title: 'Search documents',
description: 'Search documents by text. Use when the user asks to find a document; concise returns titles and IDs, detailed adds excerpts.',
inputSchema: z.strictObject({
query: z.string().describe('Words to search for'),
response_format: z.enum(['concise', 'detailed']).default('concise').describe('concise: titles and IDs; detailed: adds excerpts'),
limit: z.number().int().min(1).max(50).default(10).describe('Results, 1 to 50'),
}),
annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
},
async ({ query, response_format, limit }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated, Literal
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
server = MCPServer("issues")
@server.tool(
title="Search documents",
annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def search_documents(
query: Annotated[str, Field(description="Words to search for")],
response_format: Annotated[Literal["concise", "detailed"], Field(description="concise: titles and IDs; detailed: adds excerpts")] = "concise",
limit: Annotated[int, Field(description="Results, 1 to 50", ge=1, le=50)] = 10,
) -> str:
"""Search documents by text. Use when the user asks to find a document; concise returns titles and IDs, detailed adds excerpts."""
return "Done"Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
Is response_format an MCP standard?
No, it is a design pattern from Anthropic’s guide to writing tools for agents. Any argument that lets the model choose less output (fields, include_body) serves the same purpose.
How much does it save?
It depends on the data: a concise answer that returns IDs and one-line summaries is usually a fraction of a detailed one. Anthropic’s guide shows the pattern with a concise and a detailed response side by side.
Related checks
- List and search tools take a limit or cursor
- Read tools declare an outputSchema
- Description says when to use the tool
- All checks in MCP tool descriptions
How this check is graded
It counts toward: Schema and description quality. See the rubric.
Last verified against Anthropic: Writing effective tools for agents on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere