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

Beyond the annotations, the description discloses important behavioral traits: persistent tracking, invalidation rules based on zone/format fingerprints, required implementation fields for missing-animation or missing-component issues, sourceUrl behavior for attaching older pages, componentSelection reuse scope, and the 2000-point/1 MB issue batch limit. These are substantive operational details that an agent could not infer from the annotations alone.

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 front-loaded with the core purpose and then packs in constraints efficiently. It is dense but mostly earns its length for a complex recording tool. The semicolon-heavy structure and the inaccurate '16 contrôles' count slightly reduce clarity.

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 10-parameter mutation tool with nested objects and no output schema, the description covers purpose and several important behavioral rules. However, it does not explain the required version parameters or session-control flags, and its check enumeration does not match the schema. These gaps matter for correct invocation.

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%, so the description must carry parameter meaning. It explains checks, issues, sourceUrl, and componentSelection in useful detail, but leaves required parameters pageId, expectedVersion, and reviewVersion unexplained, along with nextAction, startSession, and restartSession. It also says there are 16 controls while the schema enum contains 19 check keys, creating a mismatch.

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 opens with a specific verb and resource: saving actually performed checks, their evidence, and anomalies into persistent tracking. It also clarifies that this is not a client validation tool, which helps distinguish it from validation-oriented siblings. However, it does not explicitly name the closest sibling tools such as get_clone_review or apply_clone_repairs.

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?

It gives clear usage context and exclusions: only modified zone/format fingerprints invalidate checks, unchanged zones should not be rechecked, missing components or animations require implementation before validation, and issues should not be arbitrarily split. It does not explicitly route the agent to named alternative tools, but the when/when-not guidance is strong.

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