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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the bar is lower. The description still adds two things an agent would otherwise have to infer: a global value-envelope convention {value, evidence, source} with the bare-number fallback to self_reported, and the shape of the response (health, signals, item verdicts, actions) — valuable since there is no output schema. It stops short of describing duplicate/merge behavior on repeat calls.

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?

Cadence is front-loaded in one short sentence, then a dense checklist of what to report, then the format rule and return summary. Every sentence carries weight for a 16-parameter tool, though the middle enumeration is a long comma-run that could be easier to scan as a list.

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 nested, 16-parameter, non-idempotent write tool with no output schema, the description covers the reporting surface and the return payload adequately. The material omission is default merge semantics on repeated same-day check-ins and the optional api_key auth path — both only discoverable in the schema.

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?

With 16 parameters and only 31% schema description coverage, the description must compensate, and it largely does: it maps the top-level reporting categories and disambiguates subtle pairs like releases 'shipped vs verified live' and 'build vs distribution actions'. Gaps remain for mode (auto/merge/new), tasks, notes, owner_feedback, and the information the caller must supply, but coverage is well above baseline.

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 gives a specific verb ('Report') and an enumerated resource set — north-star, KPIs, releases, build/distribution actions, blockers, corrections, timeouts, claims, incidents, deliverable progress, item usage. That is concrete enough to distinguish this daily write-in from read-side siblings like get_report and get_digest, though it never names an alternative explicitly.

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?

'Use this once a day' is a real cadence directive, so usage is more than implied. But it offers no guidance on when not to call it, how it relates to set_goals/update_items/get_digest, or what to do on a second same-day submission — that merge behavior only surfaces in the schema.

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