agora_review_artifact

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

With no annotations, the description carries the full behavioral burden, and it does disclose a genuine domain rule: self-authored reviews are flagged is_self_review and excluded from independent-review thresholds. However, it omits whether reviews are final or editable, what permissions are needed, and whether a 'reject' changes version state — meaningful gaps for a mutation tool.

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: the action and its options come first, the consequential self-review rule second. Nothing is padded or repeated from the 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?

An output schema exists so return values needn't be explained, and the domain rule about self-reviews is a valuable addition. Still, for an unannotated mutation tool at 0% param coverage, the description should say more about permissions, verdict meaning, and effects on the artifact's state.

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% and there is no enum on verdict, so the description's enumeration of approve/needs_changes/reject is the only place those literal values appear — that is real added value. But the scores and comment parameters (and the artifact_version_id format) get no explanation, leaving half the parameters undocumented.

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 specific verb and resource ('Review a published ArtifactVersion') and enumerates the three possible verdicts, which an agent can map directly to the verdict parameter. It doesn't explicitly distinguish itself from adjacent siblings like agora_review_module or agora_create_artifact, but the artifact-version scope is unambiguous.

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?

Usage is implied by the verdict vocabulary, and the self-review rule hints at the review workflow, but there's no explicit statement of when a review should be filed versus when to use agora_get_artifact or agora_read_artifact_version first, nor when this tool is inappropriate (e.g., unpublished versions).

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