How to build great tools for AI agents: A field guide

Summary

This article distills practical lessons from production tool logs at Composio on how to reduce invocation failures when large language models call external functions. The core insight is that even when a tool executes correctly in isolation, agents frequently mis-invoke it because names, descriptions, or parameter schemas leave critical constraints implicit. One concrete case involved a Firecrawl scraping action that required a jsonOptions parameter whenever the output format was set to JSON; the agent repeatedly omitted it until the schema description explicitly stated the dependency, after which failures disappeared.

The authors advocate four interlocking design rules. First, enforce a single naming convention across the entire tool set, with snake_case as the default, because inconsistent casing leads models to treat otherwise identical functions as distinct. Second, keep each tool narrowly scoped to one atomic operation; broad utilities such as manage_files that hide copy, move, or delete behind conditional flags increase ambiguity and error rates, whereas separate copy_file, move_file, and delete_file calls are invoked reliably. Third, write descriptions that state both the action and the triggering context in a compact template (“Tool to <do X>. Use when <Y happens>”), surface only high-impact constraints up front, and stay under the 1024-character limit imposed by some model providers. Fourth, design parameters for machine readability: document hidden requirements such as “at least one of agent_id, user_id, or run_id must be supplied,” use JSON Schema enums and format annotations for categorical or structured values, prefer fewer top-level primitives over nested objects, and embed short usage examples directly in parameter descriptions.

Finally, the article stresses that tool quality is not static. Anonymised production error logs reveal recurring friction points, while automated tests and evaluations confirm whether each schema change reduces or introduces failures. After applying these practices across their platform, the team recorded an almost tenfold reduction in tool-invocation errors, underscoring that disciplined schema hygiene and continuous measurement together produce the largest gains in agent reliability.

Why it matters

This guide is highly relevant for ML Engineers as it tackles the production-level challenge of reliable LLM function calling. By providing actionable schema design patterns and prompt engineering best practices, it enables Dutch AI teams to build more robust, deterministic, and maintainable agentic workflows.