production.retopology_validate_weights

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

Annotations declare readOnlyHint=false and idempotentHint=false, so this 'validate' tool apparently mutates or leaves state behind, yet the description says nothing about what it changes, whether QA is non-destructive in practice, or what 'stress QA' does to the scene. It adds the useful facts that limits are configurable and side pairs must be explicit, but the non-read-only profile is left entirely unexplained — the most important thing an agent needs to know before calling it.

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?

A single tight sentence with the differentiating qualifier ('Bounded') front-loaded, and the optional mode flagged last. It is efficiently sized, though the density of unexplained jargon costs a little readability.

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 need not be described, but for a non-read-only tool with a free-form options bag at 0% schema coverage the description is far too thin. An agent cannot construct a valid invocation or judge the safety implications from what is written here.

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 the 'options' parameter is an untyped open object with additionalProperties, so the schema gives an agent no key names at all. The description gestures at what belongs in options ('influence/normalization limits', 'explicit side pairs') but never names a field, format, or default, leaving the single required 'relationship' parameter entirely undefined.

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 names the resource (weights) and the activity (QA/validation) and adds two distinguishing qualifiers: 'bounded' and 'explicit side pairs'. But 'QA' is a noun rather than a concrete verb, the jargon ('bounded', 'side pairs') is unexplained, and nothing says how this differs from siblings like retopology_validate or deformation_qa, which an agent would plausibly confuse it with.

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?

There is no statement of when to call this versus retopology_validate, retopology_transfer_weights, or retopology_analyze_deformation_regions, and no prerequisites such as requiring a relationship/rig pairing first. The only usage-adjacent hint is the trailing 'optional stress QA', which implies a deeper mode without saying when to enable it.

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