production.physics_review

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

Annotations already declare destructiveHint=false and readOnlyHint=false; the description adds that mutations are confined to isolated secondary candidates and that body/face are preserved, which is genuine extra context. However it does not say what a 'physics review' produces, what the QA/review gates check, or what happens on failure.

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?

Short and front-loaded, but written as telegraphic fragments rather than complete sentences, which hurts clarity ('fixed physics plan and explicit QA/review gates' is not parseable). No wasted words, but the terseness trades away meaning.

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?

The presence of an output schema relieves the description of explaining returns, but with 7 undocumented parameters, a mutation-capable tool, and no explanation of what the review gates or fixed physics plan entail, the description is far too thin for the tool's complexity.

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?

Seven parameters with 0% schema description coverage, and the description explains only 'apply' (defaults false). The semantics of brief, intent, options, physics, object_name, and operation_id are left entirely undocumented in both schema and description.

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 verbs (inspect/propose/execute) and a scope ('isolated secondary candidates'), but the resource is just the tool name restated ('physics_review'), so the agent learns little about what is actually reviewed. 'Body/face preserved' hints at scope limits but is ambiguous. No differentiation from close siblings like physics_compare_before_after or physics_accept.

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?

'apply defaults false' implies a dry-run default and 'explicit QA/review gates' hints at a gated workflow, but there is no statement of when to choose this over physics_refine, physics_accept, physics_compare_before_after, or physics_validate_* tools. The agent must infer the routing.

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