Agent skill

documenting-tools

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.

View SKILL.md on GitHub Repository
Stars 5
Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/axiomantic/spellbook/tree/main/skills/documenting-tools

SKILL.md

Documenting Tools

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

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

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

  • 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>

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

axiomantic/spellbook

spellbook-auditing

Meta-audit skill for spellbook development. Spawns parallel subagents to factcheck docs, optimize instructions, find token savings, and identify MCP candidates. Produces actionable report.

5 2
Explore
axiomantic/spellbook

documentation-updates

Use after modifying library skills, library commands, or agents to ensure CHANGELOG, README, and docs are updated

5 2
Explore
axiomantic/spellbook

project-encyclopedia

[DEPRECATED] Use project-level AGENTS.md files instead. Previously used for first-session codebase onboarding and persistent glossary creation.

5 2
Explore
axiomantic/spellbook

reviewing-impl-plans

Use when reviewing implementation plans before execution. Triggers: 'is this plan solid', 'review the plan', 'check before I start building', 'anything missing from this plan', 'will this plan work', 'audit the implementation plan'. NOT for: reviewing design documents (use reviewing-design-docs) or creating plans (use writing-plans).

5 2
Explore
axiomantic/spellbook

session-resume

Session resume protocol and session repairs handling. Loaded when spellbook_session_init returns resume_available: true, or when session_init returns a repairs array. Triggers: 'resume', 'continue', 'where were we', session resume, session repairs.

5 2
Explore
axiomantic/spellbook

brainstorming

Use when exploring design approaches, generating ideas, or making architectural decisions. Triggers: 'explore options', 'what are the tradeoffs', 'how should I approach', 'let's think through', 'sketch out an approach', 'I need ideas for', 'how would you structure', 'what are my options'. Also invoked by develop when design decisions are needed.

5 2
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results