character_edit_readiness

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world access. The description contributes real extra context by stating it allocates no snapshots or history (i.e. does not consume recovery capacity) and reports 'exact native' semantics, which matters for a preflight check. It stops short of saying what happens if blockers exist or what the response shape looks like.

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 front-loaded sentence with no filler; the key capability and the no-side-effects guarantee are both stated up front. It is dense with jargon ('native semantic edit blockers'), which slightly hurts first-read 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?

There is no output schema, and the description partially compensates by naming the three returned categories (blockers, geometry, recovery capacity). But with four undocumented parameters and no indication of how readiness is judged per operation type, an agent lacks key details needed to call it 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 0% and the description never explains any of the four parameters. It does not say what 'frames' or 'roles' select, how 'character' identifies a target, or how 'operation' changes the evaluation — leaving the required 'frames' and 'operation' opaque beyond their enum values.

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 uses a specific verb ('Read') plus a clear set of resources ('edit blockers, geometry and remaining recovery capacity'), and 'readiness' frames it as a preflight diagnostic rather than an edit. It does not name or contrast any sibling (e.g. character_pose, semantic_pose_read), so the differentiation must be inferred from the resource nouns.

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?

'Readiness' and 'blockers' strongly imply it is called before a semantic edit operation, and the 'without allocating snapshots or history' clause hints at a safe probing use-case. However, no explicit when-to-use, when-not-to-use, or alternative tool is named, so the agent must infer the preflight role.

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