Design Robust LLM Agent Tools

This skill covers agent tool design end to end, built on the insight that tool descriptions matter more than tool implementations - the LLM never sees your code, only the schema and description. Core principles: keep tool count under ~20 (more causes confusion), give every tool explicit error handling since silent failures poison agents, return strings rather than objects, gate execution with validation, and test tools with the LLM itself, not just unit tests.

It covers detailed JSON Schema description-writing (contrasting a vague "gets stock price" description against a comprehensive one specifying format, valid inputs, and what the tool does NOT do), parameter descriptions with format/examples/edge cases, using enums to constrain valid values, explicit required-vs-optional fields, Anthropic's input_examples feature (cited as improving accuracy from 72% to 90% on complex operations), structured error handling (informative error objects with error_type, message, and suggestions rather than a bare {"error": "Failed"}), building tools as MCP servers for cross-platform reuse, using SDK tool runners to handle the tool-call loop automatically, and parallel tool execution (batching multiple tool_result blocks into a single message rather than sending them separately).

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. Returns the latest trade price in USD. Use when the user asks about current or recent stock prices. Does NOT provide historical data, company info, or predictions.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Use this whenever defining a new tool, function-calling schema, or MCP tool for an agent, or when debugging why an agent misuses a tool, hallucinates parameters, or fails silently.

Delegates out for adjacent needs: coordinating multiple tools across agents goes to a multi-agent-orchestration skill, persistent state between tool calls goes to agent-memory-systems, voice-specific tool requirements go to a voice-agents skill, desktop automation goes to computer-use-agents, and tool testing/evaluation goes to agent-evaluation.

Inputs: the tool's purpose, parameters, and expected inputs/outputs.

Outputs: a well-formed JSON Schema tool definition (name, comprehensive description, typed parameters with descriptions and enums where applicable, required fields, optional input examples), an MCP server implementation if cross-platform reuse is needed, and structured error-handling code with informative error types and suggestions. Includes validation checks flagging issues like too-short tool descriptions, missing parameter descriptions, missing required arrays, tool functions without error handling, error results missing an is_error flag, tools returning objects instead of strings, unparameterized SQL queries, and external calls without timeouts.

JSON Schema (universal tool schema format), MCP (Model Context Protocol, Anthropic's open standard), Anthropic SDK (beta tool runner), OpenAI Functions (strict mode), Vercel AI SDK, LangChain Tools.

Developers building agent tools or MCP servers who need the schema, description, error-handling, and parallel-execution patterns that make tools reliable for an LLM to call correctly.