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.

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