draft_report

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

With no annotations, the description carries full burden and does reasonably well: the leading 'WRITE.' signals a side-effecting mutation, it states the concrete output artifact (report.md), it discloses the human-approval gate (an auth-like requirement), and it notes each finding cites its OCDS record. It omits overwrite/error behavior and permissions details, keeping it from a 5.

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?

Front-loads the operation type ('WRITE.'), then purpose, then prerequisites in three short lines with no filler. The fragmentary line breaks cost it a little readability, but nothing is wasted.

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?

An output schema exists, so return-value explanation is unnecessary, and the write/approval prerequisites are covered. However, for a mutation tool with zero annotations and 0% parameter documentation, the description should say more about what happens on write (overwrite, failures) and what the remaining parameters mean.

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%, so the description must compensate, and it only partially does: 'approved flags in a case' loosely implies case_id and 'needs a named human approver' maps to approved_by. The title and summary parameters are undocumented in both schema and description, and approved_by is optional in the schema despite being framed as a requirement.

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?

Specific verb+resource: 'Build the committee report (report.md) from the approved flags in a case' names both the artifact and its input source. This is clearly distinct from siblings like file_flag or check_red_flags, 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?

States two concrete preconditions for use: flags must already be approved and a named human approver is required. It gives no explicit when-not guidance or alternative (e.g. what to do if flags are not yet approved), so it stops short of a 5.

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