aiworkhub_eval_artifact_gate

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

Consistent with readOnlyHint=true and adds real context beyond the annotation: a PASS on zero eligible rows is treated as failing/blocking evidence, and the tool explicitly never rewrites an artifact. That subtle "empty result is not a pass" behavior is exactly the kind of thing annotations cannot express. It stops short of naming the recompute mechanism or error conditions.

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?

Two tight sentences, with the READ-ONLY qualifier and the core action front-loaded. Minor waste from hard line breaks inside sentences and the somewhat redundant restatement that it never rewrites an artifact, but overall efficient.

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?

An output schema exists, so return values need not be explained. However, for a gate tool whose only input is undocumented, the description omits what "changed paths" does to the evaluation scope and what "retained rows" covers — enough gaps that an agent must guess at invocation semantics.

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?

The single parameter changed_paths has 0% schema description coverage, so the description carries the full burden — yet it never mentions the parameter at all. An agent cannot tell whether it is required (it's optional), what form paths take, or how null differs from a list.

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?

"Recompute registered eval verdicts from retained rows" gives a specific verb (recompute) and resource (eval verdicts), but the scope words ("registered", "retained rows") are internal jargon an agent cannot map to anything concrete. Nothing distinguishes it from nearby verification tools such as aiworkhub_source_graph_retrieval_eval or aiworkhub_quality_gate_ratchet.

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 never says when to call this tool versus the numerous other quality/eval siblings, nor what prerequisite state must exist (registered verdicts, retained rows). Only the post-condition of the call (blocking evidence on divergence) is implied, not the trigger for invoking it.

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