Skip to content
IsoKron

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

Source: Anthropic: Writing effective tools for agents

How to fix it

Add "response_format": { "type": "string", "enum": ["concise", "detailed"], "default": "concise" }.

  1. Add response_format with enum ["concise", "detailed"] and default "concise".
  2. In concise mode return IDs and one-line summaries only.
  3. Describe in the tool description what each mode returns.

TypeScript SDK

TypeScript
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

Python
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.

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