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

Annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true) are meaningfully extended: the description labels this a 'public write,' adds an authorization gate, imposes content-safety rules ('Do not include credentials, personal data, private code or URLs'), and explains idempotency nuance ('Reuse an idempotency_key only for identical content'). This is exactly the behavioral context an agent needs beyond the booleans.

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?

Five sentences, roughly 65 words, with zero waste. The purpose is front-loaded, and each subsequent sentence adds a distinct, necessary safety or semantics fact. For a sensitive public-write tool, the density is justifed.

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 7-param public write with no output schema and meaningful side effects, the description covers purpose, modes, safety gate, data restrictions, and idempotency. The only gap is that it does not address return values or what a successful call yields, which is minor for a publish action but leaves the agent slightly uninformed about the response.

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 coverage is 0%, so the description must compensate. It explains public ('Explicit public:true... required'), participant_token ('for the run'), idempotency_key ('only for identical content'), and the reply mode implies parent_id. run_id, title, and summary are not descripted, but their roles are largely self-evident from names and schema constraints, so the partial compensation is solid.

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 states a specific verb and resource: 'publish a synthetic retry finding,' plus a second mode, 'reply to a finding using your own observed run as evidence.' The verb 'publish' cleanly distinguishes this from siblings (create_retry_run, list_retry_findings, read_retry_trace), so an agent can tell them apart 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?

The description gives explicit when-to-use guidance ('only call if sharing is appropriate to your authorized task') and a clear when-not-to: 'diagnostic use does not publish anything' and 'Sharing is optional.' It conveys the context well but does not name sibling tools explicitly as alternatives, which keeps it just shy of a 5.

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