Tools

Tools are the actions and information sources an agent can use while solving a task. They matter because they determine what the agent can actually do: read files, run tests, browse a site, inspect a PR, query GitHub, or call an external service.

The right toolset makes an agent useful. The wrong toolset makes it either powerless or unsafe.

Best practices

Give agents the smallest toolset that can complete the job
Prefer tools that return concrete evidence, not just summaries
Expose standard local tools for search, testing, typechecking, and screenshots
Keep tool names and usage patterns predictable
Document which tools are safe to use autonomously
Distinguish between read tools and write tools
Pair powerful tools with explicit verification expectations
Review tool access any time a new integration is added

What not to do

Do not give every agent every tool by default
Do not let the tool list grow without clear ownership
Do not hide critical verification behind tools only one person understands
Do not assume more tools always means better output
Do not expose destructive tools casually
Do not leave agents guessing which tool to use for which job

Examples

This is good tool design because the available actions match the real workflow. The agent can search, edit, test, and verify changes without being given broad unnecessary power.

Repo paths:

/AGENTS.md
/package.json
/docs/verification.md

## Tools

- Use fast search tools for discovery.
- Run the standard repo verification commands before claiming success.
- Use screenshot or browser tools for UI changes.
- Ask before destructive or high-risk actions.

{
  "scripts": {
    "lint": "eslint .",
    "test": "vitest run",
    "typecheck": "tsc --noEmit"
  }
}

This is bad tool design because the repo expects the agent to verify changes but does not expose a clear or safe tool contract. The agent has to improvise, and unsafe actions are not clearly bounded.

Repo paths:

/AGENTS.md
/package.json

## Tools

- Use whatever tools seem appropriate.
- Use your judgment on whether to run tests.

{
  "scripts": {
    "check": "echo \"figure it out\""
  }
}

Agent Prompt

Use this prompt to have an agent improve the repo’s tool contract.

Audit and improve the tool contract for this repository.

Requirements:
- Identify the tools and commands an agent should rely on for normal work.
- Recommend the smallest useful set of tools for search, editing, verification, and UI checks.
- Add or update guidance so the agent knows when each tool should be used.
- Distinguish between safe autonomous tools and risky tools that need confirmation.
- Prefer exact repo commands over vague instructions.

Output:
- Recommended tool guidance for `/AGENTS.md`
- Recommended script or command improvements if the current repo contract is weak
- A short note on risk boundaries

Tools

Best practices

What not to do

Examples

Agent Prompt

References