Skip to content

Tool Engineering

Design, expose, and manage the tools that agents use to act on the world -- from description quality and schema design through MCP servers, skills, hooks, and specialized tool patterns.

Fundamentals

Core principles for designing agent tools that are discoverable, unambiguous, and cost-effective.

  • Tool Engineering — Design agent tools like APIs -- with documentation, examples, edge-case handling, and mistake-proofing -- not as boilerplate wrappers around existing functions
  • Tool Minimalism and High-Level Prompting — Expose fewer, non-overlapping tools and provide goal-oriented instructions rather than step-by-step procedures
  • Tool Description Quality — Tool descriptions -- not just implementations -- determine whether agents select the right tool; treat them as prompt engineering surfaces
  • Write Tool Descriptions Like Onboarding Docs — Write tool descriptions assuming the agent has never seen the system -- include implicit context, query syntax, domain terms, and resource relationships
  • Advanced Tool Use: Scaling Agent Tool Libraries — Three API-level features for managing hundreds of tools without drowning in context or losing selection accuracy

Tool Design

Structural patterns for tool interfaces, schemas, error handling, and output formatting.

  • Designing for Agent Consumers (Agent Experience) — Treat the agent as a first-class consumer of your public SDK, CLI, API, and docs; the AX discipline that routes the surface-design tactics, distinct from harness engineering
  • Agent-Computer Interface (ACI) — Tools are the agent's UI; the same principles that make human interfaces usable make agent tools effective
  • Tool Architecture Moves Consistency, Not Resolve Rate — Holding capabilities constant and changing only how tools are organized shifts run-to-run consistency, while the task resolve rate stays flat
  • Function-Level Debugger Interfaces for Coding Agents — Re-expose interactive debuggers at the function frame instead of the source line so LLM agents pay one turn per call, not one turn per step
  • Semantic Tool Output — Return human-readable, contextually filtered output from agent tools to reduce hallucination and improve downstream call accuracy
  • Typed Schemas at Agent Boundaries — Formal schemas at every agent-to-agent interface establish explicit contracts that prevent state mismanagement and silent failures
  • Poka-Yoke for Agent Tools — Redesign tool interfaces so the wrong call cannot compile -- prevention over documentation
  • Consolidate Agent Tools — Prefer fewer, higher-level tools that match how agents reason about tasks over many narrow tools that mirror API endpoint boundaries
  • Toolset Agentization — Group frequently co-used tools into specialized sub-agents so the top-level planner chooses among fewer, coarser actions at each routing step
  • Machine-Readable Error Responses (RFC 9457) — Request structured errors from HTTP APIs using Accept headers to replace brittle HTML parsing with deterministic control flow
  • Headless-First Services: APIs for Agent Consumers — Expose the full product surface through API, MCP, and CLI so agents acting on behalf of users can complete any flow the GUI supports
  • Tool Necessity Probing — Read tool-call decisions from the pre-generation hidden state with a linear probe — AUROC 0.89–0.96, 48% fewer tool calls at 1.7% accuracy loss
  • Chance-Corrected Shortlist Depth Sizing — Bits-over-Random measures whether retrieval at depth K beats random at depth K; the missing chance-corrected metric for sizing fixed or adaptive tool-retrieval shortlists

MCP (Model Context Protocol)

Architecture and design guidance for MCP servers and clients -- the open protocol for agent-tool communication.

Skills

Packaging domain knowledge and reusable capabilities as agent skills with reliable invocation and lifecycle governance.

  • Skill as Knowledge Pattern — Design skills as pure knowledge containers -- domain rules, heuristics, and reference material -- not executable behavior, so they remain portable across agents
  • CLI-First Skill Design — Design agent skills as CLI tools so the same interface serves both humans debugging locally and agents automating through shell tool calls
  • Skill Authoring Patterns — Practical patterns for building, testing, and troubleshooting agent skills -- categories, description craft, implementation patterns, and debugging
  • Skill Authoring as Software Engineering: What Transfers — Which software-engineering principles survive contact with measurement when authoring skills, and the two questions that decide skill versus hook
  • SKILL.md Frontmatter Reference — All SKILL.md frontmatter fields: invocation control, subagent delegation, tool restriction, hooks, and argument handling
  • Listener-State Naming for User-Invoked Agent Skills — Name a user-invoked skill after the reader's failure state rather than the output shape, so the agent adds the missing premise instead of deleting words
  • Skill Context Isolation — Run a skill in an isolated subagent context so its auxiliary tokens never enter the main chat; the parent receives only the distilled result
  • Skill Library Evolution — How agent skill libraries grow, get pruned, and evolve through versioning, quality gates, and lifecycle governance
  • Skill Reuse as Vendored Forking — Reusing a SKILL.md is a one-time near-verbatim copy that silently forks from its source; bind project specifics at adoption and track upstream only where the contract is coupled to a moving source
  • Skill Tool Runtime Enforcement — Use the Skill tool to load command prompts at invocation time rather than telling agents to read the file -- eliminates stale instructions and path drift
  • Google ADK Skills — How Google ADK implements the Agent Skills standard via SkillToolset, inline models.Skill, and three auto-generated tools mapped to L1/L2/L3 progressive disclosure
  • Interpreter Skills — Ship a SKILL.md plus an importable module so the model decides when the behavior fires while the runtime executes a reviewed, testable function — the named, versionable unit on top of an embedded code interpreter
  • Generated Procedure Drivers: Skills That Emit a Program — A skill whose output is an executable script that walks a person through a manual procedure, useful only where automation genuinely stops
  • Per-Surface Verification of Agent Plugin Packages — An Agent Plugins package is portable at skills/ and mcp.json and nowhere else; GitHub's own three clients differ on enablement, install trust, and namespaced components
  • The Merge-Conflict Resolution Skill: What to Encode — Encode two steps and no more: trace each side to its primary source before touching the diff, then run the repo's own checks before the commit

Hooks & Lifecycle

Deterministic interception points that enforce policy, automate side effects, and audit agent behavior without relying on model compliance.

Specialized Tools

Purpose-built tool patterns for file operations, web research, CLI integration, and editor-level assistance.

  • Batch File Operations via Bash Scripts — Consolidate multiple file writes into a single bash script execution to reduce per-call overhead, token consumption, and sequential latency
  • Browser Automation for Research — When an agent's HTTP client is blocked by CDN bot detection, switch to browser automation tools like Playwright to fetch content
  • CLI Scripts as Agent Tools — Write thin wrapper scripts that pre-filter system output so agents receive a decision-ready summary rather than raw command output
  • Cross-Repo Agent Search — Expose a GitHub-API-backed text-search tool to reach code outside the workspace, and compose it with local indexed search under remote-index trade-offs
  • Filesystem-Based Tool Discovery — Structure MCP tools as files in a directory tree and let the agent load only the definitions it needs, reducing token overhead by up to 98%
  • Indexed Regex Search for Agent Tools — Back an agent's regex search with a trigram or suffix-array index so query latency stays bounded on large repositories, at the cost of freshness machinery
  • Next Edit Suggestions — A proactive editing paradigm where the AI predicts both where and what to edit next, between reactive autocomplete and autonomous agent mode
  • Override Interactive Commands — Suppress interactive prompts with a one-line instruction override so the same command definition serves both human-in-the-loop and automated execution
  • Self-Healing Tool Routing — Route agent tool calls through a cost-weighted graph; recompute paths on failure and escalate to the LLM only when no feasible path exists
  • Terminal Tools for Agents: send_to_terminal and Background Interaction — Use VS Code's send_to_terminal tool and backgroundNotifications setting to give agents bidirectional control over background terminal processes
  • Unix CLI as Native Tool Interface — A single run(command) tool backed by Unix CLI can replace large function catalogs, leveraging pretraining on shell usage and built-in discovery primitives
  • Terminal-First Agent Interfaces with Browser Escalation — Default an enterprise agent to a terminal calling platform APIs and escalate to a browser only for session-bound, render-bound, and UI-authored tasks
  • Restricting a Coding Agent to a Single execute_code Tool — When narrowing an agent to one execute_code tool is cheaper than bash or native edit, and when edit-heavy modification work makes it costlier — a regime-by-agent decision
  • Choosing an Agent Tool Interface: Shell or Typed Catalog — Where execution can be isolated a shell outscores a typed catalog on enterprise work by 6 to 25 pp, and layering the catalog back on top recovers nothing
  • Web Search Agent Loop — Instead of firing a single query, wrap retrieval in a cycle of search, evaluate, refine, and synthesize -- giving the agent autonomy to decide when evidence is sufficient
  • Lexical-First Retrieval for Agentic Search — A tuned BM25 index paired with a frontier LLM and deep retrieval can match or beat dense retrieval on deep-research benchmarks -- when the agent loop is strong enough to filter the ranking noise
Last reviewed: 2026-05-27