Custom Tools Best Practices

Ten practices for designing internal tools that agents call safely and correctly.

Use this list when reviewing a new tool PR, an MCP server exposure, or a post-incident hardening pass.

How to Use This Checklist

Work top to bottom; safety and contracts before clever orchestration.
Tick items true in production configs, not only in demos.
Re-run after schema changes, new write powers, or multi-tenant launches.
Assign an owner for every unchecked item.

A - Contract Design

1. One tool, one job. Names and descriptions state a single clear action; split search vs mutate and avoid mega-tools (http_request, free SQL RW, raw shell).
2. Strict schemas. Types, enums, bounds, additionalProperties: false, and host-side Pydantic (or equivalent) validation that returns field-level errors.
3. Descriptions models can follow. When to call, when not to call, prerequisites (ids from list tools), and side effects in plain language.

B - Safety and Power

4. Least-privilege credentials. Each tool uses a scoped token/role; read tools cannot write; sandboxes hold no prod cloud keys.
5. Idempotent writes. Client keys or natural keys on creates; no blind retries on non-idempotent POSTs.
6. Ranked side effects. Auto-allow reads and low-risk writes; require human approval for irreversible, bulk, financial, or auth-changing actions.

C - Runtime Hardening

7. Timeouts, size caps, and rate limits. Per-call deadlines, max payload bytes, max rows, and per-run tool budgets so loops cannot melt APIs.
8. Structured errors. Stable error_code, retryable, and short messages; logs hold stacks and secrets stay out of model context.

D - Evolution and Proof

9. Version without silent breaks. Additive changes in place; new names for breaking changes; dual-serve and eval before deprecation removal.
10. Tests and telemetry. Handler unit tests, agent task evals, and logs for tool name, latency, success, and redacted args keyed by run id.

Applying the Habits in Order

Stage	Habits	Exit criterion
Design	1-3	Tool map + schemas + descriptions reviewed
Secure	4-6	Roles, idempotency, approval matrix documented
Ship	7-8	Caps and error contract implemented
Operate	9-10	Version policy + evals + dashboards live

Quick Anti-Patterns

General-purpose shell or SQL write tools in multi-tenant prod.
Superuser API keys shared across all tools.
Returning entire DB rows or HTML error pages to the model.
Renaming required fields without a v2 tool or dual-run.
Zero timeouts and unlimited max_results.
Tool descriptions that duplicate each other so the model guesses.
Skipping evals because "it worked in the playground."

Minimal Reference Snippet

# Pattern: validate → scoped I/O → compact result / structured error
def tool_entry(name: str, arguments_json: str) -> str:
    args = validate(name, arguments_json)  # raises → INVALID_ARG
    try:
        data = HANDLERS[name](args)  # uses scoped client, timeout, caps
        return ok(data)
    except RateLimitError:
        return err("RATE_LIMIT", retryable=True)
    except PermissionError:
        return err("AUTH", retryable=False)
    except UpstreamError:
        return err("UPSTREAM", retryable=True)

FAQs

Which three habits are non-negotiable for production?

Least privilege (4), timeouts/caps (7), and structured errors (8). Without them, good descriptions will not save you from incidents.

How many tools should one agent see?

As few as the task needs. Large catalogs increase wrong-tool choice; use tool search or staging of tools when the set grows.

Should every internal REST endpoint become a tool?

No. Curate domain actions. Facades beat 1:1 OpenAPI dumps for agent success and safety.

When is a code-execution tool justified?

When specialized tools cannot cover open-ended computation and you can sandbox with no egress and hard resource limits.

How do custom tools relate to MCP?

MCP is a transport and discovery layer. These practices still apply to every tool the server exposes.

Do read-only tools need approval gates?

Rarely for normal reads. Gate bulk export of sensitive PII and high-cost warehouse scans.

What metrics prove tools are healthy?

Success rate, p95 latency, retryable error rate, arg validation failures, and eval pass rate per tool - not just "agent finished."

How often should we review the tool catalog?

At least each release that touches schemas, and quarterly for deprecations, privilege creep, and unused tools.

Related: What Makes an Internal API a Good Agent Tool

Related: Custom Tools Basics

Related: Wrapping a REST API as an Agent Tool

Related: Versioning and Deprecating Agent Tools Without Breaking Agents

Related: Database Query Tools: Read-Only vs Read-Write Access

Related: Code Execution Tools: Sandboxed Python and Shell Access

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Custom Tools Best Practices

Ten practices for designing internal tools that agents call safely and correctly.

Use this list when reviewing a new tool PR, an MCP server exposure, or a post-incident hardening pass.

How to Use This Checklist

Work top to bottom; safety and contracts before clever orchestration.
Tick items true in production configs, not only in demos.
Re-run after schema changes, new write powers, or multi-tenant launches.
Assign an owner for every unchecked item.

A - Contract Design

1. One tool, one job. Names and descriptions state a single clear action; split search vs mutate and avoid mega-tools (http_request, free SQL RW, raw shell).
2. Strict schemas. Types, enums, bounds, additionalProperties: false, and host-side Pydantic (or equivalent) validation that returns field-level errors.
3. Descriptions models can follow. When to call, when not to call, prerequisites (ids from list tools), and side effects in plain language.

B - Safety and Power

4. Least-privilege credentials. Each tool uses a scoped token/role; read tools cannot write; sandboxes hold no prod cloud keys.
5. Idempotent writes. Client keys or natural keys on creates; no blind retries on non-idempotent POSTs.
6. Ranked side effects. Auto-allow reads and low-risk writes; require human approval for irreversible, bulk, financial, or auth-changing actions.

C - Runtime Hardening

7. Timeouts, size caps, and rate limits. Per-call deadlines, max payload bytes, max rows, and per-run tool budgets so loops cannot melt APIs.
8. Structured errors. Stable error_code, retryable, and short messages; logs hold stacks and secrets stay out of model context.

D - Evolution and Proof

9. Version without silent breaks. Additive changes in place; new names for breaking changes; dual-serve and eval before deprecation removal.
10. Tests and telemetry. Handler unit tests, agent task evals, and logs for tool name, latency, success, and redacted args keyed by run id.

Applying the Habits in Order

Stage	Habits	Exit criterion
Design	1-3	Tool map + schemas + descriptions reviewed
Secure	4-6	Roles, idempotency, approval matrix documented
Ship	7-8	Caps and error contract implemented
Operate	9-10	Version policy + evals + dashboards live

Quick Anti-Patterns

General-purpose shell or SQL write tools in multi-tenant prod.
Superuser API keys shared across all tools.
Returning entire DB rows or HTML error pages to the model.
Renaming required fields without a v2 tool or dual-run.
Zero timeouts and unlimited max_results.
Tool descriptions that duplicate each other so the model guesses.
Skipping evals because "it worked in the playground."

Minimal Reference Snippet

# Pattern: validate → scoped I/O → compact result / structured error
def tool_entry(name: str, arguments_json: str) -> str:
    args = validate(name, arguments_json)  # raises → INVALID_ARG
    try:
        data = HANDLERS[name](args)  # uses scoped client, timeout, caps
        return ok(data)
    except RateLimitError:
        return err("RATE_LIMIT", retryable=True)
    except PermissionError:
        return err("AUTH", retryable=False)
    except UpstreamError:
        return err("UPSTREAM", retryable=True)

FAQs

Which three habits are non-negotiable for production?

Least privilege (4), timeouts/caps (7), and structured errors (8). Without them, good descriptions will not save you from incidents.

How many tools should one agent see?

As few as the task needs. Large catalogs increase wrong-tool choice; use tool search or staging of tools when the set grows.

Should every internal REST endpoint become a tool?

No. Curate domain actions. Facades beat 1:1 OpenAPI dumps for agent success and safety.

When is a code-execution tool justified?

When specialized tools cannot cover open-ended computation and you can sandbox with no egress and hard resource limits.

How do custom tools relate to MCP?

MCP is a transport and discovery layer. These practices still apply to every tool the server exposes.

Do read-only tools need approval gates?

Rarely for normal reads. Gate bulk export of sensitive PII and high-cost warehouse scans.

What metrics prove tools are healthy?

Success rate, p95 latency, retryable error rate, arg validation failures, and eval pass rate per tool - not just "agent finished."

How often should we review the tool catalog?

At least each release that touches schemas, and quarterly for deprecations, privilege creep, and unused tools.

Related: What Makes an Internal API a Good Agent Tool

Related: Custom Tools Basics

Related: Wrapping a REST API as an Agent Tool

Related: Versioning and Deprecating Agent Tools Without Breaking Agents

Related: Database Query Tools: Read-Only vs Read-Write Access

Related: Code Execution Tools: Sandboxed Python and Shell Access

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Custom Tools Best Practices

Search Documentation

Custom Tools Best Practices