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

Beyond readOnlyHint=true, the description discloses real operational context: fixes are locked on the Free plan until the report is unlocked, do_first is often empty, and format=text returns the same brief as plain text. It does not contradict the read-only annotation (apply_all and 'safe to apply' describe report content, not this tool's side effects), though it omits anything about response size or behavior for an invalid scan_id.

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 whole definition is a single run-on sentence densely packed with colon-delimited section labels and parentheticals, so it is hard to scan and not front-loaded with a purpose statement. The content is largely substantive given no output schema exists, but phrases like 'each with what was found, the fix, the new copy and agent_text' repeat information already implied.

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 no output schema, the payload map (teardown / checked / do_first / smaller / also_fix / ask_owner_first) is genuinely needed and mostly complete, including the agentText field. However, the description never explains scan_id, never states an error or empty-result behavior, and never draws the boundary against get_report, so an agent still has unresolved questions about when and how to call it.

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 carries the burden and it only partially does: format=text is explained ('returns the same brief as plain text'), but scan_id receives no explanation and the default json behavior of format is never confirmed. The one enum value that matters is covered, the required identifier is not.

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 first sentence restates the title verbatim ('What to change'), giving no verb and no object; the rest is a taxonomy of the returned sections (teardown, checked, do_first, smaller, also_fix, ask_owner_first). An agent can infer this returns prioritized fix items for a scan, but nothing explicitly separates it from siblings like get_report or get_next_action.

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 versus alternatives such as get_report (full report) or get_next_action (single action), even though both appear in the sibling list. The only usage-adjacent hints are field behaviors ('often empty: nothing measured is urgent') and a plan gate ('on Free the fixes stay locked until the report is unlocked'), which describe content rather than tool selection.

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