documenting-tools

Auto-invocation: Your coding assistant will automatically invoke this skill when it detects a matching trigger.

Use when writing MCP tools, API endpoints, CLI commands, or any function that an LLM will invoke. Also use when LLMs misuse tools due to poor descriptions. Triggers: 'document this tool', 'write tool docs', 'MCP tool', 'tool description quality', 'model keeps calling this wrong', 'improve tool description'. For human-facing API docs, standard documentation practices apply instead.

Workflow Diagram

Workflow for producing LLM-quality tool documentation. Ensures every tool has purpose, parameters, error cases, and examples documented to prevent model misuse.

flowchart TD
    Start([Start]) --> IdentifyType{Tool Type?}
    IdentifyType -->|MCP Tool| MCPSchema[Use MCP Schema Format]
    IdentifyType -->|REST API| APISchema[Use API Doc Format]
    IdentifyType -->|CLI Command| CLISchema[Use CLI Doc Format]
    IdentifyType -->|Function| FuncSchema[Use Function Doc Format]
    MCPSchema --> WritePurpose[Write Purpose: One Sentence]
    APISchema --> WritePurpose
    CLISchema --> WritePurpose
    FuncSchema --> WritePurpose
    WritePurpose --> WriteWhenToUse[Write When To Use]
    WriteWhenToUse --> WriteWhenNot[Write When NOT To Use]
    WriteWhenNot --> DocParams[Document All Parameters]
    DocParams --> ParamComplete{Each Param Has Type + Constraints + Example?}
    ParamComplete -->|No| FixParams[Add Missing Param Details]
    FixParams --> ParamComplete
    ParamComplete -->|Yes| DocReturn[Document Return Value]
    DocReturn --> DocErrors[Document Error Cases]
    DocErrors --> ErrorComplete{All Error Cases Covered?}
    ErrorComplete -->|No| AddErrors[Add Missing Error Cases]
    AddErrors --> ErrorComplete
    ErrorComplete -->|Yes| HasSideEffects{Has Side Effects?}
    HasSideEffects -->|Yes| DocSideEffects[Document Side Effects]
    HasSideEffects -->|No| WriteExamples[Write Usage Examples]
    DocSideEffects --> WriteExamples
    WriteExamples --> ConsistencyCheck{Terminology Consistent?}
    ConsistencyCheck -->|No| FixTerminology[Unify Terminology]
    FixTerminology --> ConsistencyCheck
    ConsistencyCheck -->|Yes| SelfCheck{Self-Check Passed?}
    SelfCheck -->|Yes| End([End])
    SelfCheck -->|No| ImproveDoc[Improve Documentation]
    ImproveDoc --> SelfCheck

    style Start fill:#4CAF50,color:#fff
    style End fill:#4CAF50,color:#fff
    style MCPSchema fill:#2196F3,color:#fff
    style APISchema fill:#2196F3,color:#fff
    style CLISchema fill:#2196F3,color:#fff
    style FuncSchema fill:#2196F3,color:#fff
    style WritePurpose fill:#2196F3,color:#fff
    style WriteWhenToUse fill:#2196F3,color:#fff
    style WriteWhenNot fill:#2196F3,color:#fff
    style DocParams fill:#2196F3,color:#fff
    style FixParams fill:#2196F3,color:#fff
    style DocReturn fill:#2196F3,color:#fff
    style DocErrors fill:#2196F3,color:#fff
    style AddErrors fill:#2196F3,color:#fff
    style DocSideEffects fill:#2196F3,color:#fff
    style WriteExamples fill:#2196F3,color:#fff
    style FixTerminology fill:#2196F3,color:#fff
    style ImproveDoc fill:#2196F3,color:#fff
    style IdentifyType fill:#FF9800,color:#fff
    style ParamComplete fill:#FF9800,color:#fff
    style ErrorComplete fill:#FF9800,color:#fff
    style HasSideEffects fill:#FF9800,color:#fff
    style ConsistencyCheck fill:#FF9800,color:#fff
    style SelfCheck fill:#f44336,color:#fff

Legend

Color	Meaning
Green (#4CAF50)	Skill invocation
Blue (#2196F3)	Command/action
Orange (#FF9800)	Decision point
Red (#f44336)	Quality gate

Cross-Reference

Node	Source Reference
Tool Type?	Inputs: tool_type (MCP, REST API, CLI, function)
Use MCP Schema Format	MCP Tool Schema section
Write Purpose: One Sentence	Documentation Checklist: Purpose
Write When To Use	Documentation Checklist: When to use
Write When NOT To Use	Documentation Checklist: When NOT to use
Document All Parameters	Documentation Checklist: Parameters
Each Param Has Type + Constraints + Example?	Parameter Documentation Format
Document Return Value	Documentation Checklist: Return value
Document Error Cases	Error Documentation section
All Error Cases Covered?	Error Documentation table (7 error categories)
Has Side Effects?	Documentation Checklist: Side effects
Write Usage Examples	Documentation Checklist: Examples
Terminology Consistent?	Anti-Patterns: Inconsistent terminology
Self-Check Passed?	Self-Check checklist

Skill Content

# Documenting Tools

<ROLE>
Tool Documentation Specialist. Your reputation depends on documentation that enables LLMs to use tools correctly without guessing. Ambiguous tool docs cause runtime errors, incorrect parameter values, and wasted tokens on retries.
</ROLE>

<CRITICAL>
Anthropic's "Building Effective Agents" guide: "Spend as much effort on tool definitions as you do on prompts." Tool documentation is a first-class engineering artifact.
</CRITICAL>

## Invariant Principles

1. **Ambiguity causes errors**: If a parameter could mean two things, the model will guess wrong
2. **Edge cases must be documented**: Undocumented error states cause unrecoverable failures
3. **Examples prevent misuse**: One good example is worth ten paragraphs of description

## Reasoning Schema

<analysis>
Before documenting a tool, identify:
- What type of tool is this? (MCP, API, CLI, function)
- What does it do in one sentence?
- What are all the parameters?
- What errors can occur?
- If source code lacks error handling, document the failure modes you can infer.
</analysis>

<reflection>
After documenting, verify:
- Can someone who's never seen this tool understand when to use it?
- Are ALL parameters documented with types?
- Are ALL error cases documented?
- Is there at least one example?
</reflection>

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| `tool_type` | Yes | MCP tool, REST API, CLI command, function |
| `tool_code` | Yes | Implementation or signature to document |
| `existing_docs` | No | Current documentation to improve |

## Outputs

| Output | Type | Description |
|--------|------|-------------|
| `tool_documentation` | Inline/JSON | Complete tool documentation |
| `quality_assessment` | Inline | Checklist verification |

---

## Documentation Checklist

For every tool, document ALL of these:

| Element | Required | Description |
|---------|----------|-------------|
| **Purpose** | Yes | What the tool does in one sentence |
| **When to use** | Yes | Conditions that make this tool appropriate |
| **When NOT to use** | Recommended | Common misuse cases, similar tools to use instead |
| **Parameters** | Yes | Each parameter with type, constraints, examples |
| **Return value** | Yes | What the tool returns on success |
| **Error cases** | Yes | What errors can occur and what they mean |
| **Side effects** | If any | What state changes the tool causes |
| **Examples** | Recommended | 1-2 usage examples |

---

## Parameter Documentation Format

```
name (type, required/optional): Description.
  - Constraints: [valid ranges, formats, patterns]
  - Default: [if optional]
  - Example: [concrete value]
```

**Good:**
```
path (string, required): Path to the file to read.
  - Can be absolute (/Users/...) or relative to cwd (./src/...)
  - Must not contain null bytes
  - Example: "/Users/alice/project/README.md"
```

**Bad:**
```
path: The file path
```

---

## Error Documentation

| Error Case | Document |
|-----------|----------|
| Empty/null input | What happens if required field is empty? |
| Invalid type | What if wrong type passed? |
| Out of bounds | What if index exceeds array length? |
| Missing resource | What if file/URL/ID doesn't exist? |
| Permission denied | What if access is restricted? |
| Timeout | What if operation takes too long? |
| Rate limit | What if quota exceeded? |

```
errors: [
  "ERROR_CODE: Human-readable explanation of when this occurs"
]
```

---

## MCP Tool Schema

```json
{
  "name": "tool_name",
  "description": "What the tool does. When to use it. When NOT to use it (use X instead).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "param_name": {
        "type": "string",
        "description": "What this parameter controls. Constraints. Example value."
      }
    },
    "required": ["param_name"]
  }
}
```

---

## Anti-Patterns

<FORBIDDEN>
- One-word descriptions ("Reads file", "Makes request")
- Missing parameter types or constraints
- No error documentation
- No examples
- Assuming the model knows your conventions
- Documenting only the happy path
- "See code for details" (the model can't see your code)
- Inconsistent terminology (file/path/filepath used interchangeably)
</FORBIDDEN>

---

## Good vs Bad Examples

### File Reading Tool

**Bad:**
```json
{
  "name": "read_file",
  "description": "Reads a file"
}
```

**Good:**
```json
{
  "name": "read_file",
  "description": "Reads file contents as UTF-8 string. Use for text files. Fails on binary files (use read_file_binary). Fails if file doesn't exist.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "File path. Absolute (/Users/...) or relative to cwd (./src/...). Example: '/Users/alice/README.md'"
      }
    },
    "required": ["path"]
  },
  "errors": [
    "FILE_NOT_FOUND: Path does not exist",
    "PERMISSION_DENIED: Cannot read file",
    "BINARY_FILE: File is binary, use read_file_binary"
  ]
}
```

### API Request Tool

**Bad:**
```json
{
  "name": "api_request",
  "description": "Makes an API request"
}
```

**Good:**
```json
{
  "name": "api_request",
  "description": "HTTP request to external API. Use for REST APIs. NOT for internal services (use internal_rpc). Auto-retries 5xx errors 3x.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "method": {
        "type": "string",
        "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"],
        "description": "HTTP method"
      },
      "url": {
        "type": "string",
        "description": "Full URL with protocol. Must be HTTPS for external APIs. Example: 'https://api.github.com/repos/owner/repo'"
      },
      "body": {
        "type": "object",
        "description": "Request body for POST/PUT/PATCH. Auto-serialized to JSON."
      },
      "timeout_ms": {
        "type": "number",
        "description": "Timeout in milliseconds. Default: 30000"
      }
    },
    "required": ["method", "url"]
  },
  "errors": [
    "TIMEOUT: Exceeded timeout_ms",
    "NETWORK_ERROR: Could not connect",
    "INVALID_URL: Malformed URL or disallowed protocol",
    "AUTH_REQUIRED: 401 returned, check credentials"
  ],
  "sideEffects": "POST/PUT/DELETE/PATCH may modify remote state"
}
```

---

## Self-Check

<CRITICAL>
Before completing tool documentation, ALL items must be checked. If ANY unchecked: improve documentation before shipping.
</CRITICAL>

- [ ] Purpose is one clear sentence (not "does stuff")
- [ ] "When to use" conditions specified
- [ ] "When NOT to use" specified for commonly confused tools
- [ ] ALL parameters have type, description, constraints
- [ ] At least one example value per parameter
- [ ] ALL error cases documented with codes and explanations
- [ ] Side effects stated if any
- [ ] At least one usage example
- [ ] Terminology is consistent throughout

<FINAL_EMPHASIS>
Tool documentation is the interface contract between you and every LLM that will use your tool. Ambiguity in that contract means the LLM will guess. Guessing means errors. Clear documentation means correct tool usage on the first try. Write for the model that has never seen your codebase.
</FINAL_EMPHASIS>