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

Beyond the destructiveHint/not-idempotent annotations, it discloses the AI question check and its daily quota, that a failed verdict creates nothing and returns the verdict plus what is missing, that confirm_question skips a second check, that unavailability still creates the review, and that question_version staleness causes refusal. These are real behaviors an agent could not infer from the 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 'Use this when' trigger and no filler sentences; every clause earns its place. The flow is dense and some sentences are long run-ons (the create/verdict sentence), which costs a point against crispness but not against usefulness.

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?

There is no output schema, and the description compensates by describing what comes back (the verdict, what is missing, revisia's own wording, or a statement that no wording could be proposed). For a two-action, destructive, quota-limited tool this covers everything needed to call 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 88%, so the baseline is 3; the description earns more by explaining why confirm_question should only be set after the researcher saw the check of that exact wording, why question_type is echoed back to preserve the framework, and what question_version guards against. Syntax details like lang default and the sha256 pattern remain schema-only, which is fine.

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 opens with a specific verb+resource pair ('a new review or to reword its question') and then separates the two actions ('action create' vs 'action update_question'), so an agent knows exactly which capability it is invoking. It does not name or contrast the closely related siblings (revisia_question, revisia_question_act), leaving that differentiation to inference.

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?

Explicit trigger ('Use this when the researcher wants a new review or to reword its question'), explicit sequencing (show original vs revisia's wording, ask the researcher, then re-call create with confirm_question: true), and explicit exclusions ('Never write a wording of your own', concepts locked once stage 1 is approved). It also names the fallback branch when the AI check is unavailable (quota used up, AI down, email not confirmed) creates anyway and must say so.

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