6. What makes a good tool definition?
The model chooses tools by reading names, descriptions and schemas, so those are the interface. Spec guidance and practice:
- Names should be 1 to 128 characters, case-sensitive, using letters, digits, underscore, hyphen and dot, and unique within the server.
- Descriptions say what the tool does, when to use it instead of a similar tool, units and limits, and side effects.
- Input schemas are JSON Schema 2020-12 by default. Use enums, formats and ranges, and
{"type": "object", "additionalProperties": false} for tools with no parameters.
- Granularity: a few tools mapped to user tasks (
search_tickets, update_ticket_status) beat a thin wrapper over every REST endpoint. Thirty overlapping tools confuse models and waste context.
- Stable order: the spec says servers should return tools in a deterministic order, which helps client caching and LLM prompt cache hits.
A strong candidate tests tool definitions against a real model with an evaluation set of prompts, checking that it picks the right tool and fills arguments correctly.
Clients that aggregate servers should prefix names, since two servers may both expose search.
7. How does structured tool output work?
A tool can declare an outputSchema and return structuredContent that conforms to it. If an output schema is declared, servers must return conforming structured results and clients should validate them.
For backward compatibility, the spec says a tool returning structured content should also return the serialized JSON in a text content block. The 2026-07-28 revision loosened structuredContent to allow any JSON value, including arrays.
A minimal server with the TypeScript SDK v2, from the official TypeScript SDK pattern:
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';
const server = new McpServer({ name: 'billing', version: '1.0.0' });
server.registerTool(
'get_invoice',
{
description: 'Fetch one invoice by ID. Amounts are in USD cents.',
inputSchema: z.object({ invoice_id: z.string().startsWith('inv_') }),
outputSchema: z.object({
invoice_id: z.string(),
status: z.enum(['draft', 'open', 'paid', 'void']),
amount_due: z.int(),
}),
},
async ({ invoice_id }) => {
const inv = await billing.getInvoice(invoice_id);
const data = { invoice_id: inv.id, status: inv.status, amount_due: inv.amountDue };
return {
content: [{ type: 'text', text: JSON.stringify(data) }],
structuredContent: data,
};
}
);
await server.connect(new StdioServerTransport());
Structured output lets code consume results without parsing prose, and it lets a client validate what a third-party server returned.
The spec notes structuredContent is unrelated to LLM "structured outputs", a confusion that comes up in interviews.
8. Find the bug: the model never recovers from a bad date.
server.registerTool(
'book_flight',
{
description: 'Book a flight',
inputSchema: z.object({ from: z.string(), to: z.string(), date: z.string() }),
},
async ({ from, to, date }) => {
if (new Date(date) < new Date()) {
throw new Error('date in the past');
}
return { content: [{ type: 'text', text: await flights.book(from, to, date) }] };
}
);
Bug: input validation failures should be tool execution errors, not protocol errors.
Per the tools spec, protocol errors (JSON-RPC error) are for unknown tools, malformed requests and server faults, and clients may not show them to the model.
Tool execution errors are results with isError: true and an actionable message, which clients should pass to the model so it can correct itself. The 2025-11-25 revision made this explicit for input validation (SEP-1303).
Depending on the SDK, a thrown error may become a protocol error or a generic message, so return the error yourself.
Fix: return { isError: true, content: [{ type: 'text', text: 'Date 2026-11-01 is in the past. Today is 2026-11-09 (UTC). Use YYYY-MM-DD.' }] }.
Also tighten the schema (z.iso.date()) and write a description that states the date format, so fewer calls fail at all.
9. What are tool annotations, and how far can a client trust them?
Annotations are optional hints about behavior: readOnlyHint, destructiveHint, idempotentHint and openWorldHint, plus a display title.
Clients use them to decide when to ask the user for confirmation, for example auto-approving read-only tools and prompting before destructive ones.
The spec is blunt: clients must consider tool annotations untrusted unless they come from trusted servers. A malicious server can mark delete_repository as read-only.
So annotations can make a trusted server's UX smoother, but they cannot be a security boundary.
A strong candidate building a server sets them accurately anyway, because a correct destructiveHint lets a well-behaved client put a human in the loop.
A strong candidate building a client keys approval policy on server trust and the user's own settings, not on what the server claims.
10. A tool returns 40,000 rows. What do you change?
Large results waste context, slow the model and can push the important part out of the window. Options:
- Filter and limit in the tool: add parameters for filters, a
limit with a sane default and a hard maximum, and return a total count.
- Paginate: return a cursor in
structuredContent and accept it as an argument. MCP's own list methods (tools/list, resources/list) use cursor pagination with nextCursor.
- Summarize server-side: return aggregates the model asked for instead of raw rows.
- Return a resource link: a
resource_link content item points at the full data, which the host can fetch or offer to the user without putting it in context.
A strong candidate also caps output size in bytes, because one wide text column can be larger than the row count suggests, and says so in the tool description so the model knows to narrow its query.
11. Write a minimal MCP server in Python.
The Python SDK v2 renamed FastMCP to MCPServer and kept the decorator API. Return types generate the output schema:
from pydantic import BaseModel
from mcp.server import MCPServer
mcp = MCPServer("inventory")
class StockLevel(BaseModel):
sku: str
on_hand: int
warehouse: str
@mcp.tool()
def get_stock(sku: str) -> StockLevel:
"""Return current stock for one SKU. Data is at most 5 minutes old."""
row = db.fetch_stock(sku)
return StockLevel(sku=sku, on_hand=row.on_hand, warehouse=row.warehouse)
@mcp.resource("catalog://skus/{sku}")
def sku_details(sku: str) -> str:
"""Product details for a SKU."""
return db.fetch_product_markdown(sku)
Per the Python SDK v2.0.0 release (July 28, 2026), v2 speaks the 2026-07-28 revision and still serves 2025-era clients from the same server, pip install mcp now installs 2.x, and the 1.x line receives security fixes only.
Teams not ready to migrate should pin mcp>=1.28,<2. Test locally with the MCP Inspector (uv run mcp dev server.py).
12. How do you handle a tool that takes three minutes?
Three mechanisms, depending on duration:
- Progress notifications: on Streamable HTTP, respond with an SSE stream scoped to the request and send
notifications/progress before the final result, so the client can show progress and avoid timing out.
- Cancellation: on Streamable HTTP, the client closing the response stream is the cancellation signal. The server should stop work and must not send further messages for that request. On stdio, the client sends
notifications/cancelled.
- Tasks: for work that outlives a connection, the 2026-07-28 revision moved tasks out of the core protocol into an official extension,
io.modelcontextprotocol/tasks. The server returns a task handle and the client polls with tasks/get; tasks/update carries client input.
The design point: the 2026-07-28 revision removed SSE resumability, so a dropped stream loses the in-flight request and the client must reissue it with a new ID.
Long operations that cannot safely run twice need idempotency keys or the tasks extension.