December v0.4.19
· 5 min read

Building Tools for AI Agents

A field guide to tool names, tool scope, schemas, and error messages your agent can act on.

Teams building agents spend weeks tuning prompts and temperature (the setting that controls how random the output is). Then they ship, and the agent falls over on tool calls. A tool call is the agent asking your code to do something: read a file, run a command, call an API.

Composio studied agent traces (logs of every step an agent takes) in How to build great tools for AI agents. Their finding: most tool failures are API design failures. The model is usually not the problem. Your tool is. Here are the rules that fix it.

1. Predictable Naming Conventions

Models pick tools by matching names to patterns. Mixed casing and vague verbs make the model second-guess which tool to call:

  • Avoid: fetch_user_profile, getProjectDetails, User_Settings_Update
  • Use: get_user_profile, get_project_details, update_user_settings

Pick lowercase snake_case and a <verb>_<noun> shape, then use it for every tool. The model learns one pattern and applies it everywhere. fetch versus get looks trivial to you. The model has to settle it on every single call.

2. Atomic Tool Scope

A “Swiss Army knife” tool does many jobs behind one name. That makes its parameters ambiguous:

  • Avoid: One manage_files(action="read"|"edit"|"delete", path, ...) tool for everything.
  • Use: One tool per job, like view_file(path, start_line, end_line), write_to_file(path, content), and replace_file_content(path, target, replacement).

A tool that does one job has fewer parameters. Fewer parameters means fewer ways to pass two arguments that conflict. (Does content matter when action="delete"? Nobody knows, including the model.)

3. Constraint-First Descriptions

Write the tool description as a contract, not marketing copy. Put three things in it:

  1. Action: What the tool reads or changes, exactly.
  2. Trigger: When the agent should pick this tool over the others.
  3. Constraints: Preconditions, line limits, and format rules.

Put the hard constraints first. The model reads each tool’s schema (the JSON definition of its name, description, and parameters) to decide what to call. Text at the start of the description gets more of the model’s attention.

4. Strict Typing and Enums

  • Use enums: An enum is a fixed list of allowed values. If you know the valid options, list them ("mode": ["fast", "precise"]). Do not accept any string.
  • Cap top-level arguments: Tools with more than 4-5 top-level arguments fail more often. Move optional settings into a nested object.
  • Specify formats: Use schema formats like "format": "uri", and type line numbers as integers.

5. Actionable Error Returns

A generic error code tells the agent nothing. So the agent retries the same call, often forever:

  • Avoid: {"error": "500 Internal Server Error"}
  • Use: {"success": false, "error": "Target content not found in lines 40-55. Found partial match on line 48. Re-read the file before retrying."}

The second error says what went wrong and what to do next. The agent can fix its own call on the next step, with no human in the loop.

Tool Execution & Verification Loop

Reliable agents run tool calls in a closed loop: the result of each call feeds the next decision. Every call returns something the agent can act on, whether it passed or failed:

01

Structured tool call

Strict Zod schema, targeted arguments, finite enums.

Atomic invocation
02

Isolated execution

view_file, replace_file_content, and run_command run in a sandbox.

Check the output
03a / on failure

Actionable diagnostic

Line numbers, compiler hints, and partial matches go back to the agent.

03b / on success

Git checkpoint

Exit code 0. The diff is recorded and the state is locked before the next instruction.

How December Implements Tooling

December builds its tool harness (the code that defines the agent’s tools and runs them) on these rules:

  • Targeted edits: To change a file, the agent must give the exact StartLine, EndLine, and the TargetContent it expects to find there. No match, no edit.
  • Isolated execution: Shell commands run in a MicroVM sandbox (a small, isolated virtual machine). The exit code and raw stderr go straight back to the agent.
  • Immediate lint feedback: December sends syntax and compiler errors back after every step. The agent fixes them before it builds on top of a broken file.

Reference: Composio Field Guide.