# 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. Last verified against Anthropic: Writing effective tools for agents on 2026-11-18.

## 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](https://www.anthropic.com/engineering/writing-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

```ts
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"
```

## 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](https://isokron.ai/mcp-check/checks/schema-pagination)
- [Read tools declare an outputSchema](https://isokron.ai/mcp-check/checks/schema-output-schema)
- [Description says when to use the tool](https://isokron.ai/mcp-check/checks/design-use-when)
- [MCP tool descriptions](https://isokron.ai/mcp-check/checks/descriptions)

Counts toward: Schema and description quality.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
