summarize_hq_review_queue

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

With no annotations, the description carries full behavioral burden. It does disclose that the workflow is a scaffold and that the agent should 'review output status and counts to see whether analysis was performed,' plus an exclusion rule about status=not_evaluated, which is useful. However, it remains unclear what side effects or mutations may occur, what triggers analysis, or what 'guarded' means operationally.

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 top-level description is short and front-loaded, but the content is under-specified rather than efficiently informative. The schema description repeats the 'workflow scaffold' phrase and relies on 'Depends on workflow' placeholders instead of structured, helpful details.

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 complex tool with 8 params, nested objects, no output schema, and no annotations, the description is far too minimal to support correct invocation. Missing are a clear output contract in the description, input requirements, workflow semantics, and differentiation from the many QC and export siblings.

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 50%, so the description must compensate, but it adds little parameter-level meaning. It does clarify that rules need variables/condition/expected relationship and that export_path must point to a readable export, yet plan, profile, confirm_plan_id, and questionnaire_identity remain essentially unexplained.

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 'Build or run a guarded QC/support workflow' is vague about what the tool actually produces or does; it does not clearly state that the tool summarizes an HQ review queue. The term 'guarded workflow' is ambiguous and fails to distinguish this from numerous sibling QC tools such as summarize_export_qc or qc_logical_consistency.

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 guidance on when to use this tool versus alternatives; the description only says 'build or run' with no context for selecting a mode. It does not mention any prerequisites, exclusions, or scenarios where another sibling would be more appropriate.

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