Tool design

Tools are where agents interact with the real world. A well-designed tool is easy for the LLM to use correctly, hard to misuse, and returns results the LLM can reason about. Bad tool design is the most common reason agents underperform.

The principles

One tool, one job

Don't build a do-everything tool with 15 optional parameters. Split it into focused tools. An LLM chooses better from specific options than generic ones.

Name tools like a beginner would

Tool names should be obviously-related to their function. search_internal_docs is better than query_kb_v2.

Descriptions are prompts

The tool description is what the LLM reads to decide whether to call it. Write descriptions like you're briefing a new hire on when to use each tool. See tool descriptions matter.

Keep parameter count low

2-4 parameters per tool is the sweet spot. 6+ parameters means the LLM will sometimes miss required ones or hallucinate values. Split or default.

Sensible defaults

Every optional parameter should have a sensible default. Makes it easier for the LLM to call the tool correctly on first try.

Types matter

Constrained types (enums for fixed choices, integers for counts) reduce hallucination. Free-form strings invite mistakes.

Tool granularity

Too coarse: do_everything_with_database(action, params)

Too fine: separate tools for start_transaction, insert_row, commit

Right: high-level intents like save_customer, find_orders_for_customer

Response shape

Tool responses should be:

• Text or simple structured data (JSON)
• Meaningful to the LLM (context, not just raw data)
• Bounded in size (truncate long results)
• Error-rich (specific errors so the LLM can recover)

Common mistakes

• Tool name that tells you nothing ("run_function")
• Description that doesn't specify when to use the tool
• Optional params without defaults
• Tools that return huge unstructured blobs
• Tools that succeed silently when they actually failed
• Too many overlapping tools ("which one do I use?")