Pick a depth. Each prompt opens in your AI pre-loaded with the lesson. Click a row to preview the prompt.
Tool descriptions are prompts. The model decides whether to call a tool based on its description, picks input values based on the schema's descriptions, and interprets results based on what the tool returns. Bad tool docs = the agent picks wrong tools, passes wrong arguments, misinterprets results. Good tool design is half the agent's behavior. Treat your tool surface like the API your model is consuming — because it is.
Rules: (1) Tool name should be a verb_noun ('search_docs', not 'docs'). (2) Description starts with WHEN to use it, not what it does. (3) Input parameters have descriptions, not just types. (4) Return values are structured (JSON), not free-form text. (5) Errors are explicit ('city not found' vs raising an exception). (6) ≤ 5-7 tools at once — more confuses the model. Apply these and your agent's tool-picking accuracy jumps significantly.
# BAD tool design
{
"name": "lookup",
"description": "looks up info",
"input_schema": {"type": "object", "properties": {"q": {"type": "string"}}, "required": ["q"]},
}
# Issues: vague name, no when-to-use, no input description
# GOOD tool design
{
"name": "search_internal_docs",
"description": (
"Search the company's internal documentation. Use this when the user asks about "
"company policies, internal procedures, or product features specific to CapstokApp. "
"Do NOT use for general programming questions (the model knows those). "
"Returns up to 5 relevant document excerpts."
),
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "A focused search phrase, 3-10 words. Prefer the vocabulary used in the user's question.",
},
"filter_section": {
"type": "string",
"enum": ["engineering", "policy", "support"],
"description": "Optional: narrow to a section if the question clearly belongs to one.",
}
},
"required": ["query"],
},
}
# Return structured JSON, not prose
def search_internal_docs(query, filter_section=None):
hits = retrieve(query, filter_section)
return {
"hits": [
{
"title": h.title,
"section": h.section,
"snippet": h.text[:400],
"url": h.url,
}
for h in hits[:5]
],
"n_total": len(hits),
}python3 main.py