list_reports

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds nothing beyond that: it does not define what window "recent" covers, whether results are capped or paginated, or whether the list is filtered by environment. For a read tool with annotations, the bar is lower, but zero added context still lands below the midpoint.

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?

It is a single short fragment with no padding, so nothing is wasted. However, brevity here comes at the cost of under-specification rather than efficiency; the one clause carries very little information.

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?

With two parameters, one undocumented, no output schema, and no explanation of "recent" or result volume, the definition leaves real decisions to guesswork. A read-only listing tool needs at minimum a default window and the meaning of size to be called 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 description coverage is only 50%: env carries a description pointing at list_environments and has a single-value enum, but size is an undocumented integer. The description does not mention either parameter, so it fails to compensate for the coverage gap or explain what size controls (page size vs. number of reports).

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?

"List of recent daily triage reports" names the resource and implies a collection-returning operation, and the qualifiers "recent" and "daily" add some scoping beyond the bare name. It never states that it returns multiple items versus a single report, nor how it differs from get_report, so the verb+resource pairing is only mildly clarifying.

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 rather than get_report or audit_report, and no prerequisites or exclusions. The agent must infer that this is the browse/index entry point from the word "List" alone.

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