---
title: "Tool Design"
description: "Principles for defining tools that agents select correctly and execute reliably"
url: "https://agentsurface.dev/docs/tool-design"
lastVerified: 2026-09-24
lastModified: 2026-09-25T09:21:34.000Z
---



## Summary [#summary]

Tool Design is the behavior contract for model-callable actions across frameworks. Use it when defining how an agent chooses, validates, executes, and interprets a tool, whether the tool is backed by an API, CLI, database, MCP server, or local function.

* **Owns:** names, descriptions, input/output schemas, safety annotations, token budget, curation, and portability.
* **Does not own:** HTTP/OpenAPI contracts; see [API Surface](/docs/api-surface). MCP server lifecycle and transports; see [MCP Servers](/docs/mcp-servers).
* **Agent-ready means:** the model can pick the right tool, pass valid parameters, understand the result, and recover from failure without hidden product knowledge.

## Start Here [#start-here]

* [Naming and Descriptions](/docs/tool-design/naming-and-descriptions) - Write tool names and descriptions that disambiguate intent.
* [Schemas](/docs/tool-design/schemas) - Keep inputs and outputs typed, constrained, and model-legible.
* [Idempotency and Safety](/docs/tool-design/idempotency-and-safety) - Separate read, write, and destructive operations; annotation presets and the draft-then-confirm pattern.
* [Human Approval](/docs/tool-design/human-approval) - The approval contract a tool exposes so an agent can request, wait for, and confirm human sign-off.
* [Tool Curation](/docs/tool-design/tool-curation) - Expose the smallest useful tool set per task or agent; sprawl prevention and dynamic selection.
* [Cross-Framework Portability](/docs/tool-design/cross-framework-portability) - Define once and adapt to MCP, AI SDK, OpenAI, and other runtimes.
* [Token Budget](/docs/tool-design/token-budget) - Keep tool output useful without flooding context.
* [Anti-Patterns](/docs/tool-design/anti-patterns) - Spot vague, unsafe, or expensive tool definitions.

## Related [#related]

* [API Surface: Tool Definitions](/docs/api-surface/tool-definitions) - Generated tools from HTTP APIs.
* [MCP Server Tool Best Practices](/docs/mcp-servers/tool-best-practices) - MCP-specific tool implementation guidance.
* [MCP Server Annotations](/docs/mcp-servers/annotations) - Canonical semantics of the four MCP behavioral hints.
* [Error Handling: Idempotency](/docs/error-handling/idempotency) - Retry-safe writes and idempotency keys.