did_report

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

Annotations already provide readOnlyHint=true and openWorldHint=false, so the safety posture is known. The description adds the useful behavioral fact that the tool writes report artifacts, which is more than the annotations alone convey. It does not mention server-side caching or other side effects, though these are hinted at in the schema; there is no clear contradiction with the 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?

The description is a single efficient sentence with no filler: it states both what the tool fits and what it writes. Every clause carries information, and the structure is front-loaded with the key purpose.

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?

The input schema and output schema carry most of the burden, documenting 18 parameters and return structure. Yet for a complex reporting tool with many sibling tools, the description omits the relationship to did_summary, what a report bundle contains, and the intended workflow. It is minimally viable but not richly contextual.

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 baseline is 3 even if the tool description adds no parameter detail. The description only gestures at 'selected methods,' which weakly maps to the methods parameter. Many parameter descriptions defer to did_summary, which is not self-contained, but they still exist and cover the fields.

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 names a concrete action ('fits selected methods') and a concrete output ('writes report artifacts'), so it is not a mere tautology of the tool name. It conveys that this is a report-producing wrapper rather than a simple estimation or plot tool. However, it does not explicitly differentiate from close siblings like did_summary or did_plot, leaving the exact contents of the 'bundle' somewhat vague.

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?

There is no explicit guidance about when to choose did_report over did_summary, did_plot, or other report-oriented siblings. The phrase 'report bundle' implies a use case, and the schema references did_summary several times, but the description itself provides no when-to-use/when-not-to-use direction.

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