Writing Effective Tool Names & Descriptions
Structure
The name follows a simple pattern:
[Action Verb] + [Object] + [Optional: System/Scope]
The description answers three questions:
- What does this tool do?
- When should it be used?
- What inputs does it need (if any)?
Best Practices
For names:
| Do | Don't |
|---|---|
| Start with an action verb (Fetch, Create, Update, Send) | Start with the system name ("ServiceNow…") |
| Name the specific object or outcome | Use generic nouns ("Data", "Helper", "Tool") |
| Keep it short—ideally 3–6 words | Pack the full description into the name |
| Make it unique across your tool set | Reuse near-identical names that confuse routing |
| Match the user's vocabulary | Use internal jargon or acronyms users won't say |
| For descriptions: | |
| Do | Don't |
| ------------------------------ | ------------------------------------------- |
| Be specific about the action | Use vague terms like "handles" or "manages" |
| Mention the system/data source | Assume context is obvious |
| Specify required inputs | Leave input requirements unclear |
Examples
Good
Tool: Fetch Employee Leave Balance
Retrieves remaining leave balance for an employee from Workday.Use when employee asks about PTO, vacation days, sick leave,or remaining holidays. Requires employee ID.
Tool: Create IT Support Ticket
Creates a new incident ticket in ServiceNow for IT issues.Use for hardware problems, software access, VPN issues, orpassword resets. Requires issue description and urgency level.
Tool: Send Manager Notification
Sends an email notification to the employee's direct manager.Use within approval workflows to alert managers of pendingactions. Requires employee ID and notification message.
Poor
Names
| Name | Problem |
|---|---|
| "Password Tool" | No action verb; "Tool" adds nothing |
| "Workday Integration" | Names a connection, not an action |
| "Ticket Stuff" | Vague—no clear object or outcome |
| Descriptions | |
| Description | Problem |
| ------------------------ | --------------------------------------- |
| "Handles leave requests" | Too vague—fetch, submit, or approve? |
| "ServiceNow integration" | Doesn't explain what action it performs |
| "Employee data tool" | No indication of when to use it |
Tips
- Use action verbs: Fetch, Create, Update, Send, Calculate, Validate—in both the name and description.
- Keep the name and description in agreement: The name is the headline, the description is the detail—they should describe the same thing.
- Be distinct: If two tools could match the same query (e.g. Fetch Leave Balance vs. Submit Leave Request), make the difference obvious in the name.
- Include synonyms in the description: "PTO, vacation, leave, time-off" helps match varied queries.
- Keep descriptions under 50 words: Concise descriptions perform better.
- Stay scannable: A human (and the AI) should grasp the purpose at a glance.