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

The description reveals the async nature of the operation ('async generation pipeline'), which is a behavioral trait not captured in the annotations (openWorldHint=false, destructiveHint=false). However, it does not disclose other important behaviors such as required permissions, whether existing documents are replaced, or how results are delivered. With minimal annotations, the description only partially fulfills the transparency burden.

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 short and front-loaded, but the sentence includes the redundant term 'GenerateCapTableDocs' which repeats the tool name. While concise, it sacrifices substance for brevity, resulting in a marginally acceptable one-liner.

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?

Despite having an output schema, the description is incomplete for a tool with two parameters, async behavior, and multiple sibling tools. It does not explain what 'cap table docs' are, what triggers the pipeline, or how the output is returned. The description leaves too much ambiguity for the agent to confidently invoke and interpret the result.

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?

The input schema descriptions ('UUID value wrapper') are unhelpful and schema coverage is at 50%. The tool description does not explain the meaning or purpose of companyId or stakeholderIds, nor does it describe how they affect the generation. This leaves the agent with no semantic understanding of the parameters.

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 states the action ('kicks off the async generation pipeline') and the resource ('Cap Table Docs') but is vague about what specific documents are generated or how this differs from sibling tools like cap_table_generate_cap_table_agreement_pdf or cap_table_generate_cap_table_summary_pdf. It is more than a pure tautology but lacks clear differentiation.

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 no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, expected use cases, or exclusions. The presence of many similar generate/download tools in the sibling list makes this lack of guidance particularly problematic.

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