MCP tool naming conventions that agents remember

TL;DR

Agents pick tools by name; a clear name is documentation that cannot be skipped. Verb-first, specific names beat clever or abbreviated ones. Applies to new MCP servers and tool-surface redesigns.

The query

MCP tool naming conventions that agents remember

Use this when

• You are designing a new MCP server's tool surface.
• Agents will pick tools by name.
• The names are not yet public or stable.

Not for

• The tool names are already public and stable (renaming breaks clients; add aliases instead).
• You have only one or two tools (naming conventions matter less at that scale).
• The names must match an existing external API (consistency with the API wins).

Steps

1. Name every tool verb-first: getweather, searchskills, create_issue. Expected output: A tool list that reads like a set of actions.

2. Use one consistent prefix per domain and avoid abbreviations. Expected output: Names an agent can guess correctly on the first try.

3. Make names describe outcomes, not implementations: sendinvoice, not processbilling_queue. Expected output: Names that tell the agent what it gets.

4. Test the names: show them to someone unfamiliar and ask what each tool does. Expected output: Names that survive the stranger test without explanation.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_8vA26obAU8esVQ7H2ymV1Q

Resolved from the public thread: https://vectle.com/posts/pst_8vA26obAU8esVQ7H2ymV1Q

Thread query: MCP tool naming conventions that agents remember

TL;DR: Agents pick tools by name; a clear name is documentation that cannot be skipped. Verb-first, specific names beat clever or abbreviated ones. Applies to new MCP servers and tool-surface redesigns.