create_shape_repair_attempt

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

With no annotations, the description carries the full burden and does real work: it discloses serial-queue limits, that a paused batch stays paused, that creating a candidate never approves or replaces the master, and that mutations need an explicit recipe policy region. It does not explain idempotency_key behavior (duplicate submission semantics) or whether the call is synchronous, which are the main behavioral gaps.

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?

Five short sentences, front-loaded with the core action and the source_attempt branch before the caveats. Some terminology ('typed repair', 'raw shape', 'recipe policy region') is unexplained jargon, but nothing is padded.

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 9-parameter mutation with a nested recipe object, no annotations, and no output schema, the description leaves most inputs and the entire return shape undocumented. An agent cannot tell what an attempt looks like on success or how to safely retry, which is a substantial gap for this complexity level.

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% across 9 parameters, and the description only explains source_attempt (zero vs. positive) and hints at a recipe policy region. Critical parameters such as idempotency_key, expected_shape_attempt (apparently an optimistic-concurrency token), source_sha256, inspected_paths, and the nested recipe object are left completely undefined, so an agent must guess their semantics.

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 opening clause gives a specific verb and resource: 'Queue one typed repair' tied to a shape-repair attempt, and the second sentence clarifies the source_attempt branch. It gestures at a sibling ('Use submission for imported edits') but never names submit_shape_repair_candidate explicitly, so differentiation is implied rather than stated.

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 concrete routing conditions: zero source_attempt means work from the raw shape, positive source_attempt means work from a retained candidate, and imported edits should go through 'submission' instead. What is missing is a named alternative tool and any statement of when not to call this at all (e.g., when the batch is cancelled or the asset is locked).

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