Giving Agents Tools

A tool is a function the agent can call. Its name, description, and schema are the only things the model sees — design them like an API for a smart but literal teammate.

Anatomy of a good tool

@mcp.tool()
def rename_symbol(file: str, old_name: str, new_name: str) -> str:
    """Rename a symbol in one file. Returns the number of replacements."""
    ...

• Name — a verb: rename_symbol, not do_thing.
• Description — when to use it, what it returns.
• Parameters — named, typed, with clear meanings.
• Return — a concise, useful result string.

The model reads your docs

If your description is "does stuff", the model will call the tool at the wrong time or with the wrong arguments. Write:

"Rename every occurrence of old_name in file. Returns the count of replacements. Does not create backups."

Now the model knows when, how, and what it gets back.

Common tool categories for coding agents

• Read — search, read_file, list_dir.
• Edit — edit_file, apply_patch, create_file.
• Execute — run_command, run_tests.
• External — github_issue, slack_post, db_query (often via MCP).

Design rules

1. One job per tool. read_or_write_file is a mistake.
2. Narrow parameters. Booleans beat vague strings.
3. Return structured-ish text. The model parses your output.
4. Fail loudly. Return the error message, not an empty string.
5. Make the safe path easy. The default should be read-only.

Testing your tools

Write a tiny script that calls the tool directly and checks the output. If the output is ambiguous to you, the model will struggle too.

A mediocre model with excellent tools beats an excellent model with sloppy tools. The tools are half the system.