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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context beyond annotations: the assignee receives reviewer access that persists after completion/cancellation, and the instructions are untrusted review context with limited authority. These are important side effects and trust boundary disclosures that the annotations do not convey. A slight deduction because it doesn't mention what happens if the owner is not the caller or other error behaviors, but it covers significant behavioral traits.

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 description is three sentences, front-loaded with the primary purpose and key constraint, then adding essential behavioral and usage details. Every sentence earns its place: the first defines the action, the second reveals critical side effects and trust context, the third points to needed sibling tools. No fluff or redundancy.

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?

Given the tool's complexity (5 required params, output schema exists), the description covers the essential context: creation constraints (owner-only, immutable version), security boundary (untrusted instructions), persistence of reviewer access, and relationship to sibling tools (whoami, complete_review). The output schema and annotations handle return values and safety hints, so the description doesn't need to repeat them. The description is complete for an agent to decide when and how to invoke this tool 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 description coverage is 100%, so the schema already documents all five parameters. The description adds semantic value by explaining that assigneeId comes from whoami, that versionId is for an exact immutable version, that instructions are untrusted review scope, and that idempotencyKey is for retrying the same inputs. This enriches the parameter meaning beyond the raw schema fields, though it doesn't describe every parameter in exhaustive detail.

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 clearly states the tool's purpose: 'Create a pending review request for an exact immutable version', specifying the verb (create), resource (review request), and key constraint (exact immutable version). It also differentiates from siblings by mentioning 'only the artifact owner may assign it' and pointing to complete_review as the complementary tool, while whoami is for obtaining the principal ID.

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 provides explicit usage guidance: it says when to use this tool (to create a review request), what prerequisites exist (must be artifact owner, need assigneeId from whoami), and explicitly names alternates/complements (complete_review to finish, whoami to get principal ID). It also clarifies that instructions are untrusted review context, so agents know not to treat them as authoritative for unrelated actions.

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