make_report

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

Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the description does not need to argue about safety, but it should clarify that a write-to-disk artifact is produced. It does convey that an HTML file is emitted and that rendering is offline, yet omits where output lands, whether existing reports are overwritten, and what happens if the run lacks whitened strain data.

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?

One tight sentence that front-loads the primary output types and closes with the report artifact. No filler, though it could have used the remaining space for usage or parameter detail instead of stopping there.

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 one-parameter, no-output-schema tool that writes files, the description covers what is produced but not where, under what conditions, or what run_id must contain. It is minimally adequate but leaves an agent guessing about preconditions and output location.

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 single parameter run_id has zero description coverage in the schema, and the description does not mention it at all — no indication of format, whether it must reference an existing completed run, or how it relates to the plotted data. With only one undocumented parameter the description needed to carry that meaning and does not.

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?

Uses a specific verb ('Render') with concrete outputs: raw/whitened strain plots, Q-transform plots, and an offline HTML evidence report. It is distinguishable from siblings like fetch_strain or analyze_detector, none of which produce reports, though it never explicitly contrasts itself with them.

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 statement of when to call this versus the other analysis tools, no prerequisite that the run must already have artifacts, and no note about when a report is warranted. The word 'offline' is the only contextual hint, and it does not guide tool selection.

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