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
v2tool 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
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.