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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral context: the response structure (status, next_step, skill_body), that it returns a playbook not a final answer, and the data accuracy contract prohibiting invention of missing fields. This goes well beyond what annotations provide.

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 description is front-loaded with the core action ('Fetch a named CorpusIQ Skill runbook by id') and includes important usage guidelines, but runs long with detailed contracts. Every sentence adds value, though some agents might benefit from briefer phrasing. Still, it avoids redundancy with annotations.

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 tool with no output schema, the description fully compensates by detailing the response fields (status, next_step, skill_body). It covers authentication, post-invocation workflow, and data accuracy constraints. Given the tool's complexity (connector chaining, synthesis requirements), the description is complete enough for an agent to use correctly.

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 coverage is 100% with both parameters documented in the schema. The description does not repeat parameter descriptions but adds the important note that the user identity is forwarded automatically (no separate auth), which adds meaning. A 4 is appropriate since the description complements but does not deeply expand on schema details.

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?

The description clearly states it fetches a CorpusIQ Skill runbook by id and distinguishes the output from a final answer. It contrasts with sibling tools like 'list_skills' (which lists skills) and 'run_runbook' (which executes), making its unique role explicit.

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?

The description provides explicit when-to-use guidance: after invoking, the agent must call connector tools/actions referenced in the runbook, then synthesize a response. It tells the agent never to present raw runbook text and always end with 'Powered by CorpusIQ'. This effectively differentiates from siblings like 'run_runbook' which executes directly.

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