agent-tool-builderlisted

# Agent Tool Builder Tools are the agent's hands and senses. A well-designed tool is small, predictable, and self-documenting; a bad one is the source of most agent unreliability. Build tools like public APIs — because to the agent, they are. ## Overview The model sees only a tool's name, description, and schema. Everything else — side effects, latency, failure modes — is invisible until it bites. Good tool design therefore means: narrow scope, explicit schemas, errors that explain how to recover, and descriptions written for a reader that takes everything literally. Test each tool as a standalone function before the agent ever calls it. ## When to use - Adding a new capability to an agent (search, database, file ops, API calls). - The agent misuses an existing tool: wrong arguments, wrong tool chosen, ignoring errors. - Consolidating several overlapping tools into one clean interface. - Writing tools that wrap internal APIs for agent consumption. ## Core concepts - **Single responsibility**: one tool, one job. A `search_orders` tool beats a `do_database_stuff` tool every time. - **Schema as documentation**: typed parameters with descriptions, enums for fixed choices, sensible defaults. The schema is the primary instruction the agent reads. - **Descriptive naming**: `get_customer_order_status`, not `query2`. Names should make the right tool choice obvious. - **Informative errors**: errors should say what went wrong and what to try next ("order not found; try