Tool description design

Tools are a “contract between deterministic systems and non-deterministic agents” (Anthropic). Their names, descriptions and outputs all consume context and steer the agent, so they are part of context-engineering.

Anthropic’s guidance (Sept 2025)

• Build a few tools aimed at high-impact workflows rather than wrapping every API endpoint; consolidate (one schedule_event instead of list-users + list-events + create-event).
• Namespace related tools with shared prefixes (asana_search, jira_search).
• Return contextually relevant, human-meaningful fields (names over opaque IDs); offer a response_format of concise or detailed.
• Save tokens: pagination, filtering, truncation with sensible defaults; error messages that say how to fix the call.
• Write the description as you would brief a new teammate: make implicit context explicit, remove ambiguity.
• Iterate with evals on realistic tasks and read the agent’s reasoning; in Anthropic’s multi-agent work a rewritten tool description cut task time by 40% for later agents.

Claude prompting guide

Newer Claude models follow the system prompt more closely: replace “CRITICAL: You MUST use this tool” with plain “Use this tool when…”, or the tool will overtrigger.

MCP specifics (spec 2026-07-28)

• Fields: name (1-128 chars, letters, digits, _ - .), optional title, description, inputSchema, optional outputSchema, annotations. Tool names should be unique per server; aggregators should prefix.
• Return deterministic tool order (helps prompt-caching).
• Execution errors should be returned with isError: true and actionable text so the model can retry.
• Clients must treat annotations as untrusted unless the server is trusted; humans should stay in the loop for invocations.
• Security: a tool description is model-visible text, so it can carry hidden instructions. Invariant Labs disclosed “tool poisoning” on 2025-04-01; see prompt-injection-and-agent-security. Related: model-context-protocol.

Sources

• https://www.anthropic.com/engineering/writing-tools-for-agents (2025-09-11; accessed 2026-09-30)
• https://www.anthropic.com/engineering/multi-agent-research-system (2026-09-30)
• https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices (2026-09-30)
• https://modelcontextprotocol.io/specification/2026-07-28/server/tools (2026-09-30)
• https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks (2026-09-30)