generate_api_docs

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden well: it discloses that files are written under specific paths, that output is idempotent and deterministic, that the Postman collection is merged without touching other folders, and that it must read source rather than recall. It omits failure modes (e.g. what happens with no controllers) and any return value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The mandatory outputs are front-loaded, which is good, but the body is a dense run-on with nested parentheticals and file paths that make it hard to scan. Sentences are long and mix purpose, policy and artifacts together; restructuring into bullets would earn the space better.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multi-file generator with no annotations and no output schema, the description covers what gets produced, where, the default module scope, and idempotency. What's missing is edge-case behavior (no controllers found, existing conflicting docs) and confirmation of what the tool returns to the caller.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents modules, postman, projectRoot and architecture. The description mostly restates that same policy (postman opt-in, architecture always on), adding little new meaning beyond the schema text. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource ('Genera la documentacion de la API') plus its defining constraint: it reads the real code (controllers, DTOs, error catalogs) rather than memory. It also enumerates the exact outputs (per-module contract, Mermaid sequence diagram, docs/api/README.md, ARCHITECTURE.md), which separates it cleanly from siblings like verify_standards or generate_from_spec.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit interaction policy: the agent MUST ask the user before enabling postman, while the architecture doc is generated unconditionally ('siempre, no se pregunta'). It also names the siblings that invoke it implicitly ('add_use_case y record_architecture la refrescan solos'), clarifying it need not be called manually after those. No explicit when-not-to-use case, though.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.