teamstorm_get_task_pages

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile well. The description adds value beyond annotations with 'The result may include partial-loading warnings,' which prepares the agent for a possible edge case. No contradiction with annotations.

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?

Three sentences, all earning their place: purpose first, then usage timing, then a behavioral caveat. No filler, front-loaded with the core action.

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 read-only retrieval tool with strong annotation coverage, the description covers purpose, when to call it, and a behavioral caveat. The main gap is not explaining the effect of include_content and max_items on results, but those parameters are reasonably self-explanatory, so this is a minor omission rather than a fatal one.

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 0% and the description provides zero parameter explanations. With 0% coverage the description must compensate, but it doesn't describe task_key, max_items, or include_content. The parameters are partially self-evident (especially task_key), but the description adds no meaning about what include_content toggles or how max_items limits results.

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 specific verb (retrieve) + resource (documentation pages linked to a TeamStorm task) with scope ('across accessible workspaces'). 'Documentation pages' cleanly distinguishes it from sibling tools like teamstorm_get_comments, teamstorm_get_attachments, and teamstorm_get_links, so an agent can pick it correctly without opening the schema.

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 an explicit trigger condition: 'Call this tool only when the user explicitly asks for related pages or documentation.' The 'only when' phrasing provides a clear exclusion rule. However, it doesn't name alternative sibling tools for other content types, which is a minor gap in routing guidance.

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