How skills use tools

You write a skill that tells the agent to find all the TypeScript files in a project. The agent has both a file search tool and a grep tool available. Instead of searching by filename, it opens grep and scans file contents for the word “TypeScript.” It finds nothing and reports back confidently. The skill was fine. The tool descriptions were not. This happens constantly, and understanding why requires knowing how the boundary between skills and tools actually works.

Skills are not tools

A skill is a markdown file that tells an agent what to do, step by step, in human-readable terms. It encodes judgment: when to act, what order to do things in, what tradeoffs to make, when to stop.

A tool is a function the agent can call. Search files, run a shell command, make an HTTP request, query a database. Tools do one thing. They have no opinion about when or why you should use them.

Skills use tools. A single skill might call five different tools across its steps. The skill decides which tools to call and why. The tool just executes.

When you’re writing a skill, you need to understand how the agent selects and invokes tools, because your skill’s effectiveness depends on the agent picking the right tool at each step.

How tool selection works

When your skill tells the agent to “find all test files in the project,” the agent doesn’t just know which tool to use. It reads the available tool descriptions and tries to match them against what the skill is asking for.

The process looks like this:

1. Your skill gives the agent an instruction (e.g., “search for files matching this pattern”)
2. The agent reasons about what capability it needs
3. It scans available tool descriptions for a match
4. It picks the best match and constructs input parameters
5. The tool executes and returns a result
6. The agent folds the result into its next step

Steps 3 and 4 are where things go wrong. The agent’s tool selection is only as good as the descriptions it’s reading. Your skill can give perfect instructions, but if the tool descriptions are ambiguous or incomplete, the agent will pick the wrong tool or pass the wrong parameters.

Write tool descriptions for the agent, not for humans

If you’re building tools that skills will use, the most important thing to get right is the description. A common mistake is writing descriptions like API docs for human developers. But the consumer is an LLM, and it has different needs.

Bad description:

Search files using glob patterns. Supports * and ** wildcards.

Good description:

Search for files by name pattern in the project directory.
Use this when you need to find files matching a specific
name or extension (e.g., find all TypeScript files, locate
a config file by name). Returns matching file paths sorted
by modification time.

Do NOT use this for searching file contents: use the
grep tool instead.

The good description tells the agent four things:

• When to use it (finding files by name or extension)
• When NOT to use it (searching file contents belongs to grep)
• What it returns (file paths, sorted by modification time)
• Concrete examples (TypeScript files, config files)

That negative instruction (“Do NOT use this for searching file contents”) is often more valuable than the positive ones. Without it, an agent following your skill might reasonably try to use this tool for content search. With it, the boundary is clear.

Your skill can nudge tool selection

Sometimes you can’t fix the tool descriptions. Maybe you’re using a standard set of tools someone else defined. In that case, your skill instructions can compensate by being explicit about which tool to use:

## Find the relevant files

Use the **file search** tool (not grep) to find all files
matching `**/*.test.ts` in the project root.

This is a normal part of writing good skill instructions. You’re not just saying what to do, you’re saying how to do it, down to which tool to reach for. Look at the PR review skill or the test writer skill for examples of skills that explicitly direct tool usage at each step.

Parameter design

Parameters are how the agent communicates intent to a tool. When your skill says “search for test files,” the agent has to translate that into a structured tool call with specific parameter values. Well-designed parameters make that translation reliable. Poorly designed ones cause errors and retries.

Principles

1. Use descriptive names. search_query beats q. The agent is reading these names to understand what to pass.
2. Include parameter descriptions that explain what each parameter accepts and what formats are valid.
3. Set sensible defaults. Don’t require parameters that have obvious default values. If your skill doesn’t specify a search path, the tool should default to the project root.
4. Use enums for constrained choices. If a parameter can only be one of several values, enumerate them. The agent will pick from the list instead of guessing.
5. Keep parameters flat. Deeply nested objects are harder for agents to construct correctly.

Example: good parameter schema

{
  name: "search_files",
  parameters: {
    type: "object",
    properties: {
      pattern: {
        type: "string",
        description: "Glob pattern to match files (e.g., '**/*.ts', 'src/components/*.tsx')"
      },
      path: {
        type: "string",
        description: "Directory to search in. Defaults to the project root if not specified."
      }
    },
    required: ["pattern"]
  }
}

Example: poor parameter schema

{
  name: "search",
  parameters: {
    q: { type: "string" },  // What kind of search? What format?
    opts: {
      type: "object",       // Nested object: harder for agents
      properties: {
        d: { type: "string" },  // Cryptic name
        r: { type: "boolean" }  // What does this do?
      }
    }
  }
}

The difference matters because your skill doesn’t construct tool calls directly. The agent does, based on its interpretation of the skill’s instructions and the tool’s schema. Every ambiguity in the schema is a chance for the agent to guess wrong.

Handling tool results

When a tool returns data, the agent needs to interpret it and decide what to do next based on your skill’s instructions. The shape of that return data determines how effectively the agent can continue.

Return structured data when possible

// Better: structured result
{
  matches: [
    { path: "src/index.ts", modified: "2026-03-25" },
    { path: "src/utils.ts", modified: "2026-03-20" }
  ],
  totalMatches: 2,
  searchPath: "/project"
}

// Worse: unstructured string
"Found 2 files:\nsrc/index.ts\nsrc/utils.ts"

Structured data lets the agent reason about individual results, filter them, or pass specific values to the next tool call in your skill’s workflow.

Include context for decision-making

Help the agent understand not just what happened, but what it means for the next step:

{
  results: [...],
  truncated: true,
  totalAvailable: 1500,
  message: "Showing first 100 results. Use a more specific pattern to narrow results."
}

Your skill might say “if results are truncated, narrow the search pattern.” But the agent can only follow that instruction if the tool’s return value includes the truncation flag.

Error handling

Tools fail. Network requests time out, files don’t exist, permissions get denied. How tools report errors determines whether the agent can recover and continue following your skill, or whether it gets stuck.

Return errors, don’t throw them

When possible, return error information as part of the result rather than throwing exceptions. This gives the agent a chance to reason about the failure and try an alternative approach your skill describes.

// Good: error as data
{
  success: false,
  error: "File not found: /path/to/missing.ts",
  suggestion: "Check if the file path is correct. Use search_files to find the file."
}

Provide actionable error messages

Tell the agent what went wrong and what it can do about it:

• “Permission denied: /etc/shadow. This file requires root access and cannot be read.” (agent knows to skip it)
• “Rate limited. Try again in 30 seconds.” (agent knows to wait and retry)
• “Invalid pattern syntax: ’[’. Did you mean to escape this character?” (agent knows to fix the input)

A skill can include fallback instructions for common errors (“if the file isn’t found, search for it by name instead”), but the tool’s error message is what triggers that reasoning. Vague errors like “operation failed” leave the agent with nothing to work with.

The skill is the brain, tools are the hands

The thing that surprises most people about this relationship is how much of the work happens before any tool runs. The skill file encodes the judgment: what to do, in what order, and what tradeoffs to make. The tool descriptions, parameter schemas, and error messages form the interface that lets the agent translate that judgment into action. Get that interface right and the agent follows your skill reliably. Get it wrong and you’ll debug tool selection failures that no amount of skill refinement can fix.

For the protocol layer that connects tools to agents at a system level, see Building Skills with MCP. For a real example of a skill that coordinates multiple tool calls across a workflow, look at the PR review skill or the test writer skill. For the broader taxonomy that places tools alongside skills, plugins, and integrations, see What’s the difference between an AI skill, tool, plugin, and integration?.