Structure for Writing Tool Prompts
An agentic system is not just about calling an LLM API and getting your job done. In an agentic system, you give your LLM agent access to a lot of helpful tools.
As Anthropic notes: “Agents are only as effective as the tools we give them.”
In this post, I will share my understanding of how to write prompts for your tools.
The core principle of writing good prompts for an agentic system is to be as descriptive as possible. LLMs need detailed, explicit instructions to execute a task correctly.
In my experience, you can provide tool definitions at two places:
- When defining your tool function.
- Inside the prompt of your agent.
The Structure of a Tool Definition
Just like the agent prompts I discussed in my last post, the tool definition is incredibly important for performance. Here is the structure I follow to write an extremely detailed tool description:
1. Provide a Detailed Description
In this section, I explicitly explain:
- What the tool does.
- When it should be used.
- When it should NOT be used.
- What each input parameter means and how it affects the tool’s behavior.
- Any limitations (for example, what the tool does not return if a request is unclear).
2. Provide Input Examples
You likely already know how successful the few-shot prompting technique is. I use the same technique here by providing exact examples of what the inputs should look like.
3. Quality over Quantity
Fewer, highly descriptive tools are better than having too many tools. I always try to consolidate related operations into a single tool. For example, instead of creating a separate tool for create_pr, review_pr, and merge_pr, you can create one tool and play with well-defined action parameters.
4. Meaningful Tool Names
Tools are simply functions for your agents. Just like good, descriptive names are helpful in non-agentic software systems, they are just as essential in an agentic system to help the LLM pick the right tool.
5. Tool Responses
The response that the tool returns to the LLM should be descriptive, but I do not include deeply nested objects. Nested data can overwhelm the LLM with unimportant information and waste tokens.
Let’s look at an example of a good tool prompt:
To keep things consistent with my last post, here is an example of a tool definition for a Job Search Agent. Notice how I combined applying, withdrawing, and checking statuses into one tool using an action parameter.
@tool
"""
Tool Name: manage_job_application
Description:
Use this tool to apply for a job, withdraw an existing application, or check the status of a specific application.
Limitation: This tool does not search for new jobs. It only acts on jobs the user has already identified.
When to use:
- The user explicitly says "Apply for the backend role".
- The user asks "What is the status of my application at Acme Corp?".
- The user wants to cancel or withdraw an application.
When NOT to use:
- Do NOT use if the user is looking for new jobs.
- Do NOT use if the user has not specified which job they want to act on.
Input Scheme:
{
"parameters": {
"action": {
"type": "string",
"description": "The specific operation to perform. Must be exactly one of: 'apply', 'withdraw', or 'check_status'."
},
"job_id": {
"type": "string",
"description": "The unique system identifier for the job."
},
"cover_letter_text": {
"type": "string",
"description": "Optional short message to include with the application. Only use when action is 'apply'."
}
},
"required": ["action", "job_id]
}
Input Examples:
1. Applying for a job:
{"action": "apply", "job_id": "j_9872", "cover_letter_text": "I have 5 years of Python experience."}
2. Checking application status:
{"action": "check_status", "job_id": "j_1122"}
Response Description:
Returns a flat JSON object containing:
- success (boolean)
- message (string explaining the result to the user)
- current_status (string, e.g., 'applied', 'interviewing', 'withdrawn')
"""
Tool Definition Inside the Agent Prompt
A tool can be used by many different agents. Because of this, the tool definition you write in the code (like the example above) is often generic.
However, every agent has its own specific context for calling that tool. That exact context must be described inside the Agent prompt itself. I covered this in detail in my previous blog under the “Available Tools” section of the Specialist Node template.
That is it for now. See you in the next blog!