Have you ever wondered: how does AI know to use grep versus find? How does it know when to read a file versus when to execute a command?

The answer lies in the tool’s description. But this description isn’t documentation for humans—it’s “instructions” for the model. Today we’ll talk about how to write this “manual for AI.”

Tool Descriptions Like Manuals The diagram: Tool descriptions are manuals for AI, not documentation for humans

Nature of Tool Descriptions: Instructions for the Model

In traditional software, API documentation is for humans—telling developers what the interface does, what parameters mean, what return values look like.

But in AI Agents, tool descriptions are for the model—telling the model what the tool does, when to use it, how to fill in parameters.

This is fundamentally different. Documentation for humans can be detailed and technical; descriptions for the model must be concise and clear about use cases.

For example, GrepTool’s description isn’t:

GrepTool is a text search tool based on ripgrep, supporting regular expressions.
Parameters: pattern (regex pattern), path (search path)...

Instead:

Search file contents when you need to find specific text patterns.
Use cases:
- Find where a function is defined
- Search for all places where a variable is used
- Find files containing specific keywords

Note: If search results are too many, try narrowing the search scope or using a more precise pattern.

See it? The second version doesn’t just say “what this is,” but more importantly “when to use it.”

inputSchema: The “Fill-in-the-Blank” Constraints for Models

If description is the “manual,” inputSchema is the “format requirements for fill-in-the-blank questions.”

Claude Code uses Zod v4 to define inputSchema:

const GrepToolInput = z.object({
  pattern: z.string().describe('The regular expression pattern to search for'),
  path: z.string().optional().describe('The file or directory path to search'),
  caseSensitive: z.boolean().optional().describe('Whether to match case, defaults to false'),
});

This schema does several things:

Type Constraints: pattern must be string, caseSensitive must be boolean.

Required vs Optional: pattern is required, path and caseSensitive are optional.

Field Descriptions: Content in describe() appears in the JSON Schema sent to the model.

Strict Mode: z.object() is strict by default—the model cannot pass undefined parameters.

inputSchema Constraints The diagram: inputSchema is like fill-in-the-blanks, constraining what the model can fill

When the model receives the tool list, it sees this information:

{
  "name": "GrepTool",
  "description": "Search file contents when you need to find specific text patterns...",
  "inputSchema": {
    "type": "object",
    "properties": {
      "pattern": { "type": "string", "description": "The regular expression pattern to search for" },
      "path": { "type": "string", "description": "The file or directory path to search" },
      "caseSensitive": { "type": "boolean", "description": "Whether to match case" }
    },
    "required": ["pattern"]
  }
}

The model decides “whether to use this tool” based on description, and “how to fill in parameters” based on inputSchema.

Dynamic Descriptions: The Same Tool, Different Scenarios

An advanced feature of Claude Code: description can be dynamically generated.

description: async (input, options) => {
  if (options.permissionContext.isToolDenied('BashTool')) {
    return 'Execute shell commands (currently disabled, use other tools instead)';
  }
  return 'Execute shell commands for running programs, managing files, and other operations';
}

What’s this for?

Permission Awareness: When users prohibit certain operations, description proactively tells the model “don’t try.”

Context Awareness: Adjust descriptions based on current project type. For example, emphasize Python-related features in Python projects.

User Preferences: Adjust based on user habits. If the user prefers npm over yarn, the description emphasizes this.

This dynamic description lets tools “adapt” to different scenarios, guiding the model toward more appropriate choices.

Practical Tips for Description Optimization

If you want to design your own tool descriptions, these tips are useful:

Start with Use Cases: Don’t say “what this is” first—say “when to use it.”

Bad: "FileReadTool is used to read file contents"
Good: "Use this when you need to view file contents, such as understanding code logic, checking config files"

Give Concrete Examples: Models learn best from examples.

Use cases:
- Read config files to understand project settings
- View source code to understand function implementation
- Check log files to troubleshoot issues

Explain When NOT to Use: Boundary cases are equally important.

Note:
- Don't use for searching—use GrepTool instead
- Don't use for large files (>1MB)—may timeout

Keep It Concise: Too-long descriptions confuse the model—highlight key points.

Match inputSchema: If description says “for searching specific patterns,” inputSchema must have a pattern parameter.

Real Case: Tool Selection

See how Claude Code handles this request: “Help me find where the processRequest function is.”

The model sees available tools:

GrepTool: “Search file contents when you need to find specific text patterns…” FileReadTool: “Use this when you need to view file contents…” GlobTool: “List files matching patterns…” BashTool: “Execute shell commands…”

Model analysis:

  • Need to find a specific function → GrepTool’s description matches “find specific text patterns”
  • Don’t know the filename → FileReadTool isn’t suitable directly
  • Need to search content → GlobTool only lists files, doesn’t search content
  • Could use BashTool’s grep, but GrepTool is more specialized

Conclusion: Use GrepTool, pattern=“processRequest”.

This is the role of description—guiding the model to make correct choices.

The Art of inputSchema Design

Good inputSchema must not just “work,” but “work well.”

Clear Parameter Names: Use pattern not p, use caseSensitive not cs.

Provide Reasonable Defaults: Let the model skip optional parameters.

limit: z.number().optional().default(100).describe('Maximum number of results, defaults to 100')

Use Enums to Limit Choices: When parameters have only a few fixed values.

order: z.enum(['asc', 'desc']).optional().describe('Sort order')

Complex Objects Need Descriptions: Every field in nested objects needs describe.

filter: z.object({
  type: z.enum(['file', 'directory']).describe('Filter type'),
  pattern: z.string().describe('Match pattern'),
}).optional().describe('Filter conditions')

Implications for Using Claude Code

Understanding tool descriptions helps you:

Understand why AI sometimes “chooses the wrong tool.” The description might not be clear enough, or the use case isn’t explicit enough.

Better design MCP tools. If you write MCP tools, remember description is “instructions for the model.”

Debug tool call issues. If AI always misuses a tool, check if the description accurately describes use cases.

Optimize tool preferences in CLAUDE.md. Stating “I prefer using tool X for task Y” in CLAUDE.md affects the model’s choices.

Summary

Tool descriptions aren’t documentation—they’re instructions. Good descriptions don’t just tell the model “what this is,” but more importantly “when to use it.” inputSchema is the “format requirements” for parameters, constraining how the model fills them.

Claude Code, through dynamic descriptions, carefully designed schemas, and clear use case explanations, enables AI to accurately select and use tools. This is a key part of the “living system”—the model isn’t just a tool user, but a decision-maker determining “what to use, how to use it” based on descriptions.

In the next article, we’ll talk about the 200K context window—AI’s “memory palace” management techniques.