Submit design review

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'asynchronous, metered,' which is not in the annotations, and reinforces the idempotency via 'Reuse client_request_id on retries.' It also states 'never edits code,' a behavioral guarantee. These add value beyond the annotations. It could mention what happens on failure, but the polling instruction implies a retry pattern. No contradiction with 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?

The description is two sentences with no wasted words. The first sentence states purpose and a key behavioral fact (never edits code). The second gives actionable retry and polling guidance. Everything earns its place, and the most important information is front-loaded.

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 submission tool with an output schema (which presumably contains poll_after_ms and review ID), the description covers the essential workflow: submit, retry with same ID, and poll with a specific tool. It doesn't explain how to cancel or recheck, but those are separate tools. The description is complete enough for an agent to successfully initiate a review without missing critical steps.

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 71% (5 of 7 parameters have descriptions). The description itself mentions only client_request_id and references poll_after_ms (an output field). It adds a usage note for client_request_id (reuse on retries), which is already in the schema's description, so the marginal value is low. The other parameters (depth, response_mode, etc.) are adequately described in the schema, so the baseline 3 applies.

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 action ('Submit an asynchronous, metered design review') and specifies the resource (tenant-authorized HTTPS preview). It also explicitly says 'This tool never edits code,' which distinguishes it from any code-modifying sibling. The verb 'submit' is unique among the sibling tools (get, recheck, cancel, panel_action), so an agent can unambiguously select it.

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 gives concrete usage guidance: 'Reuse client_request_id on retries, then poll design_review_get no faster than poll_after_ms.' This tells the agent how to handle retries and which tool to use for polling. It doesn't explicitly exclude other siblings (e.g., design_recheck, cancel), but for the core submit action the guidance is sufficient. Slightly stronger would be an explicit 'use this to start a review, use design_review_get to retrieve results.'

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