--- title: "Naming and Descriptions" description: "Verb-first naming conventions and descriptions written as onboarding prompts" url: "https://agentsurface.dev/docs/tool-design/naming-and-descriptions" lastVerified: 2026-09-07 lastModified: 2026-09-25T05:46:01.000Z --- ## Summary [#summary] Name a tool for a task a person can understand: `read_paint`, `find_palette_ideas`, `add_samples_to_cart`. Agent Surface defaults to lowercase `snake_case` with an imperative verb followed by the thing being read or changed. This is our design convention, not a universal protocol requirement or a proven performance advantage over every other spelling. Use the same public name in registration, descriptions, prompts and dispatch. Keep provider names, caching, transport and connection management inside the implementation unless those are the agent's actual task. ## Naming Conventions [#naming-conventions] ### Describe the task in ordinary language [#describe-the-task-in-ordinary-language] Start with a concrete verb and a familiar object. Extra words should distinguish an operation the agent genuinely needs to choose. | Prefer | Avoid for a shopping assistant | Reason | | --------------------------- | ------------------------------ | -------------------------------------------------------------------- | | `read_paint` | `read_cached_paint` | The shopper needs paint details; the application chooses storage. | | `find_palette_ideas` | `find_palette_precedents` | Use the language of the task rather than specialist terminology. | | `find_paints` | `mg_find_paints` | An internal supplier abbreviation does not help select the action. | | `add_samples_to_cart` | `process_samples` | The name makes the mutation explicit. | | No separate diagnostic tool | `check_catalogue_connection` | The application handles connectivity and reports retrieval failures. | A diagnostic agent may genuinely need `check_connection`; a shopping assistant usually does not. Preserve source identity, freshness and actionable failure information in results without asking the model to manage infrastructure. ### Use a consistent spelling [#use-a-consistent-spelling] Our default is `verb_noun` in lowercase `snake_case`: `search_issues`, `create_invoice`, `list_users`, `read_user`. Use imperative present tense and singular or plural according to what the tool returns. Keep names short enough for every target adapter; a 64-character ceiling is a conservative house limit for shared client tools, not the MCP limit. Do not rename language-native variables or filenames merely to match a public tool name. A TypeScript export can remain `readPaint`, in `read-paint.ts`, while both the tool ID and its registration key are `read_paint`. If a framework distinguishes these identifiers, test their agreement at the model boundary and in its inspector. ### Namespace only when it helps selection [#namespace-only-when-it-helps-selection] A service name can matter when the agent must choose between actual destinations, such as `search_jira_issues` and `search_github_issues`. It does not matter when two backend implementations provide the same product capability. Do not expose both a generic tool and a provider-prefixed duplicate for that reason alone. Anthropic recommends meaningful namespaces for large tool sets and reports that prefix versus suffix placement affects models differently. Evaluate the names against real tasks; do not claim one word order always wins. [Anthropic tool-design research](https://www.anthropic.com/engineering/writing-tools-for-agents#namespacing-your-tools). ### Separate protocol validity from design preference [#separate-protocol-validity-from-design-preference] Verified on 7 September 2026: | Source | What it actually says | Implication | | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | [MCP 2026-07-28: tool names](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#tool-names) | Recommends 1–128 characters, case sensitivity and ASCII letters, digits, underscores, hyphens or dots. Its valid examples include `getUser`. | MCP does not require snake\_case or verb-first names. | | [Claude: define tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools#specifying-client-tools) | User-defined client tool names match `^[a-zA-Z0-9_-]{1,64}$`. | A name valid for MCP may still need adaptation for a model provider. | | [OpenAI: function-calling practices](https://developers.openai.com/api/docs/guides/function-calling#best-practices-for-defining-functions) | Calls for clear, intuitive names and descriptions and moving work into code where possible. | A readable task boundary matters more than mechanical renaming. | | [Gemini: function-calling practices](https://ai.google.dev/gemini-api/docs/function-calling#best-practices) | Recommends descriptive function names and clear parameter descriptions. | Do not mistake a platform's examples for a universal casing mandate. | No comparison reviewed here establishes that snake\_case beats camelCase across models. Adopt one convention for consistency, then assess whether an agent selects the right operation, supplies valid arguments and completes the task. Avoid a cosmetic rename that leaves two tools semantically indistinguishable. ### Change a public name deliberately [#change-a-public-name-deliberately] A tool rename changes a callable contract. Update registrations, IDs, prompt references, allowlists, dispatch, progress labels and fixtures together. Preserve historical call records; add migration or replay handling only where saved calls are executed again. Do not advertise both old and new names to the model by default. Keep human display titles separate when the protocol supports them. ## Descriptions as Prompts [#descriptions-as-prompts] The tool description is a prompt fragment executed in the agent's decision-making loop. It answers four questions: 1. **What does this tool do?** (one sentence, the concrete action) 2. **When should an agent use it?** (triggering conditions) 3. **When should an agent NOT use it?** (disambiguation from sibling tools) 4. **What are prerequisites and edge cases?** (what can go wrong, what to do) ### Example: Good Description [#example-good-description] ``` Search Jira for issues by text, assignee, status, or custom JQL query. Use this when the user wants to find open bugs, search by assignee, or pull all "high-priority" tickets. Do not use for creating new issues (use `jira_create_issue` instead) or updating existing ones (use `jira_update_issue`). Requires JIRA_API_KEY env var. Returns up to 50 results by default; use `limit` and `offset` for pagination. Returns an empty array (not an error) when no issues match the query. ``` This description: * States the concrete action (search Jira) * Clarifies when to use it (specific triggering scenarios) * Explicitly disambiguates from similar tools * Notes prerequisites (env var requirement) * Documents pagination behavior * Explains edge cases (empty results) ### Example: Weak Description [#example-weak-description] ``` Searches for Jira issues. ``` Too terse. The agent cannot reason about when to use this vs other search tools, cannot predict edge cases, and must make guesses about parameter semantics. ### Pattern Library [#pattern-library] **For mutation tools, name the side effect explicitly:** ``` Permanently deletes the invoice. This cannot be undone. The customer will not be charged. Use only when the invoice was created in error. To pause a legitimate invoice instead, use `billing_pause_invoice`. Returns { success: true, invoice_id } or { isError: true, message } if the invoice is already paid or has been archived. ``` **For list/query tools, document pagination:** ``` Returns up to 50 open issues matching the filters, ordered by created_at descending. Use the cursor field from the response to fetch the next page. Returns an empty array (not an error) when no issues match the query. Each page takes ~200ms to fetch. ``` **For tools with ordering dependencies:** ``` Sends the invoice email to the customer. Must be called after `billing_create_invoice` - calling on a draft invoice returns { isError: true, message: "Invoice not finalized" }. Idempotent: calling twice on the same invoice does not send duplicate emails. Subject line and template are configurable in the system settings. ``` **For tools requiring prior state:** ``` Transitions an issue to a new status. Requires a valid issue_id from `search_issues` or `get_issue`. Not all status transitions are valid - for example, cannot transition from "Done" back to "Open". Returns { isError: true, message, valid_transitions: [...] } if the transition is not allowed. Include a comment via the optional `comment` parameter to explain the change. ``` ## Disambiguation Patterns [#disambiguation-patterns] When two tools are siblings or near-overlapping in purpose, explicitly state the choosing criterion in descriptions: ``` search_issues: For querying existing tickets. Use for finding open bugs, filtering by status, listing assigned work. create_issue: For submitting new work. Use when the user describes a new bug or feature request. update_issue: For modifying existing tickets. Use to change status, assignee, or description of a ticket already tracked. ``` Agents that read these descriptions understand exactly which tool to reach for based on the user's intent. Without disambiguation, agents guess - leading to wrong tool selection and failed operations. ## Common Anti-Patterns [#common-anti-patterns] ### Terse Descriptions [#terse-descriptions] ``` Creates a thing. ✗ No context Searches for items. ✗ Vague use case Gets data. ✗ What data? When should I use this? ``` Takes no effort to write. Compounds agent confusion and accuracy loss. ### Missing "Do Not Use For" [#missing-do-not-use-for] ``` Search documents. ``` Leaves the agent guessing whether to use this for full-text search, metadata-only search, or to filter an existing result set. Pair with a sibling and disambiguate: ``` Search documents by full text, title, or metadata. For filtering results from a prior search, use `filter_search_results` instead. ``` ### Implicit Ordering Dependencies [#implicit-ordering-dependencies] ``` Add line items to an order. ``` Does not say whether the order must exist first. Better: ``` Add line items to an order. Requires a valid order_id from `create_order` or `list_orders`. Returns { isError: true } if the order does not exist or is already finalized. ``` ### No Pagination Documentation [#no-pagination-documentation] ``` Returns invoices matching the filter. ``` How many? What if there are thousands? Better: ``` Returns up to 50 invoices matching the filter, ordered by created_at descending. Use the `next_cursor` field in the response to fetch the next page. Total count available via `total_count`. ``` ### Marketing Copy Instead of Prompting [#marketing-copy-instead-of-prompting] ``` Harness the power of advanced issue tracking with our best-in-class Jira integration, delivering seamless workflow automation and enterprise-grade reliability. ``` Not a prompt. Rewrite: ``` Search Jira for issues by text, status, or assignee. Use when finding tickets for a user request. Do not use for creating new issues (use `create_issue`). Returns paginated results. ``` ## Length Guidelines [#length-guidelines] Good descriptions land between 30 and 200 words: say what's needed and stop; cut filler, never the when-to-use guidance. ``` 30 words: Perfect for simple, unambiguous tools (get_user, list_repos) 100 words: Typical for mutation tools with edge cases 200 words: Complex tools with many preconditions or disambiguation needed 300+ words: Red flag - consider splitting the tool or linking to deeper docs ``` ## Research Evidence [#research-evidence] Anthropic's [writing-tools-for-agents](https://www.anthropic.com/engineering/writing-tools-for-agents) article reports that description changes improved tool-use performance in its evaluations. Treat the opening sentence as the main routing hint; put edge cases and secondary context later. ## See also [#see-also] * `/docs/tool-design/schemas` - companion page on schema design * `/docs/tool-design/anti-patterns` - common mistakes with fixes * ([Anthropic tool design guide](https://www.anthropic.com/engineering/writing-tools-for-agents)) * ([MCP 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/)) - current tool naming and description fields