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

Annotations only declare readOnlyHint/openWorldHint; the description adds substantial behavioral context: it is a dry-run that never refuses, the 0.75 pass threshold, that unchecked rules report a reason, the sentToTypeSafe/fromSavedVerdicts counters, and that unchanged records reuse prior verdicts. This is exactly the value-add expected above annotations.

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?

Front-loaded with the core purpose, and each sentence carries information (preservation of drafts, kind constraint, id-override behavior, return shape). It is dense and slightly long, but almost nothing is filler given the absent output schema.

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 no-output-schema tool it thoroughly explains the return values (passed/failed with probability, unchecked with reason, sentToTypeSafe/fromSavedVerdicts) and the key preconditions, so an agent has enough to call and interpret it correctly.

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 coverage is already 100%, so the baseline is 3, but the description adds genuine meaning: passing record.id starts from the saved record and any supplied fields override saved values, plus the kind constraint tied to the step's connection. That override/merge semantics isn't in the schema.

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?

States a precise verb+resource+scope: checking a draft against rulesets on a step of a workflow run, explicitly "without saving it and without refusing." This clearly distinguishes it from the mutation siblings (update_idea, update_work) and from rule-management siblings (create_rule, update_rule).

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?

Gives real preconditions: rules only run inside workflow runs, runId names the run, record.kind must match the kind of write the step's connection checks, and a saved Batch can only be rechecked until one of its Works is done. It doesn't explicitly name an alternative tool for validating-then-saving, but the when-to-use context is strong.

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