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

Well beyond the annotations, it discloses an auth requirement (mcp:report scope), an idempotency rule per run_ref, downstream effects (Rithmo prices the run; it appears on the agent's page; mismatched models are flagged to the owner), and a hard gating consequence (runs with actions but no checks are blocked pending human review). It also explains why the readOnlyHint is defensible: 'These are shown as your own account of the run; they grant nothing.' Minor tension with idempotentHint=false ('reporting the same run again records nothing new'), though that is per-run_ref rather than an outright contradiction; no failure/validation behavior is described.

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 trigger is correctly front-loaded, but the remainder is a single sprawling run-on sentence with deeply nested parentheticals ('and the work behind it (`work`: up to 10 {…}) and where its tokens went…'), mixing required-field instructions, estimation heuristics, pricing policy, and UI effects. An agent must re-parse it to extract per-field rules, and several requirements (usage_estimated placement, never send zeros) are easy to miss mid-clause. It is not padded with filler, but the structure actively obstructs use.

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 an 18-parameter, deeply nested, no-output-schema write tool, the description covers nearly everything an agent needs: when to call, which fields are required in practice, how to approximate token counts, how models are priced, and what happens downstream. Remaining holes are the undocumented agent_key and no statement about what a successful call returns or how validation errors surface. Those are minor compared with the field-level guidance provided.

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 6% across 18 parameters, so the description carries almost the entire semantic load and does so substantively: it defines the outcome enum values (result / no_result / failed), the token fields including fast_usage, the up-to-20 usage_by_model shape with speed and long_context, the breakdown sum constraint ('adding up to usage plus fast_usage… one that does not is left out'), and an exact placement rule for usage_estimated ('beside usage (not inside it)'). Gaps remain: agent_key is never mentioned, the required `status` field is only implied by 'whether it completed or failed', and started_at/ended_at key names are not given explicitly.

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 opening clause 'Call once when a run ends' gives a specific trigger plus a clear resource (a completed run of this agent), and the body enumerates exactly what gets recorded (times, outcome, model, token usage, references, actions taken). It does not explicitly contrast itself with siblings such as start_agent_run or report_action_outcome, so differentiation is left to inference from their names. Purpose is clear, but the enumerated detail is buried in one long sentence.

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?

It states a concrete when: 'Call once when a run ends', and adds conditional instructions ('if you cannot see your token counts, estimate them… the characters of everything you read and wrote, divided by 4', 'never send zeros', 'reporting the same run again records nothing new'). It also warns of a consequence that affects workflow: a run that acted without checking is blocked until a person reviews it. What it never does is name an alternative tool or say when-not to call this versus report_action_outcome.

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