Tool-Confusability Recovery Loop

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

No annotations are provided, so the description carries the full burden, and it discloses nothing: no statement of whether this mutates state (the name 'apply_fix' strongly implies it does), what permissions or loop states are required, what happens on failure, or whether the change is reversible. A single opaque sentence is inadequate for an unannotated tool whose name implies a write.

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 single sentence is front-loaded and free of padding, so there is no verbosity problem. However, brevity here reflects under-specification rather than disciplined conciseness — the space saved is not replaced by the information an agent needs.

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?

With no annotations, no output schema, 0% parameter coverage, and an implied mutation, the description should explain input meaning, preconditions, and effects. It provides only a domain-flavored fragment, leaving the agent unable to call this confidently or interpret the result.

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 coverage is 0% and neither parameter is documented in the schema. The description only obliquely hints that 'item' is a worklist item and 'loop_id' identifies the run; it never states the expected format of loop_id, whether item is an index or ID, or what valid values exist.

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 verb 'serve' does not convey what apply_fix actually does, and the description's framing ('serve the revised catalog') does not align with the tool name's implication of applying a fix. It gestures at domain nouns (worklist item, open loop run, revised catalog) but an agent cannot tell what action occurs or how it differs from register_catalog or verify_recovery.

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?

The phrase 'of an open loop run' weakly implies a precondition (a loop must already be open, likely via start_loop), but there is no explicit when-to-use, when-not-to-use, or named alternative. Nothing tells the agent how to choose between this and register_catalog or verify_recovery.

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

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

No annotations are provided, so the description carries full behavioral burden. It implies a read-only fetch and mentions returning a receipt, but does not disclose permissions, error behavior, status value meanings, or receipt format.

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 a single front-loaded sentence with no wasted words. It is appropriately sized, though very sparse.

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?

With no annotations, no output schema, and an undocumented required parameter, the description is too thin to fully prepare an agent. It does not explain status values, receipt structure, or failure modes.

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?

The single required parameter loop_id is undocumented in both schema and description, with 0% schema description coverage. The description does not explain what loop_id refers to, its format, or where to obtain it.

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 a specific verb ("Fetch") and resource ("a loop run's status and receipt"), making the tool's job clear. It does not explicitly differentiate itself from siblings like start_loop or verify_recovery, but the fetch/read framing is distinct enough.

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 explicit guidance on when to use this tool versus alternatives such as start_loop or verify_recovery. Usage is only implied by the name and description.

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

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

With no annotations, the description carries the full burden and does not meet it. It implies a mutation ('Register', 'stores') but says nothing about permissions, whether re-registration overwrites prior state, what 'green state' means, 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?

A single compact sentence with the action front-loaded, which is fine structurally. The cost note 'Free' and the opaque 'green state' phrase consume space without adding usable 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?

No output schema, no annotations, and 0% parameter coverage leave the description as the only source of truth, and it is too thin. An agent could not confidently construct the array payloads or predict the effect of calling this from what is written.

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 coverage is 0% and both parameters are bare arrays with no item type, so the description must compensate and largely does not. It maps 'catalog' and 'probes' to the two parameters, but adds no information on element shape, whether probes reference catalog entries, or ordering constraints.

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 verb 'Register' plus the resources 'tool catalog + probe suite' gives a workable sense of the action, but the trailing clause 'stores the green state' is undefined jargon and there is no differentiation from siblings like start_loop or verify_recovery, which appear to sit in the same workflow.

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 this should be called, what must exist beforehand, or which sibling to use instead. The only usage-adjacent note is 'Free,' which hints at a billing distinction but does not tell the agent anything about selection.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses pricing ($0.05 / plan / first run free), but it does not say whether starting a loop mutates state, what side effects occur, whether it is idempotent, what permissions are needed, or what the agent should expect after invocation.

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 a single front-loaded sentence with no wasted wording, and the pricing detail is useful for cost-aware agents. It could be slightly more structured, but it is appropriately concise.

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 three-parameter tool with no annotations and no output schema, the description is missing too much: parameter semantics, usage context against siblings, mutation/side-effect behavior, and post-invocation expectations. The pricing note is helpful but insufficient to make the definition complete.

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% for all three parameters (catalog_id, catalog, selector_class). The description mentions 'current live catalog' but does not explain the distinction between catalog_id and catalog, nor what selector_class controls. It leaves every parameter undocumented.

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 states a specific verb and resource: start a recovery loop run against the current live catalog. It is clear enough to distinguish from status-checking siblings like loop_status, but it does not explicitly contrast with apply_fix or verify_recovery.

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 explicit guidance on when to use this tool versus the sibling tools apply_fix, loop_status, register_catalog, or verify_recovery. The phrase 'recovery loop run' implies a workflow, but no conditions, prerequisites, or exclusions are stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does add that a signed receipt is returned, but it does not say whether re-probing mutates state, whether it is idempotent, what permissions are required, or what happens if no fix was served — significant gaps for an operation that may trigger a probe.

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 compact sentence with the action front-loaded and no filler. It is efficient, though its terseness contributes to the gaps elsewhere rather than being fully earned brevity.

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 tool with no annotations, no output schema, and an undocumented required parameter, the description is too thin. An agent knows the broad intent but lacks the mutation/safety profile, the precondition failure behavior, and any detail on the identifier it must supply.

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?

There is one required parameter, loop_id, with 0% schema description coverage and no mention of it in the description. The phrase 'a loop run' loosely implies the identifier refers to a loop, but nothing states format, source, or how to obtain the ID.

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 does name a specific verb ('re-probe') and resource ('a loop run whose fix was served') plus a return artifact ('signed recovery receipt'). However, 'loop run' and 'signed recovery receipt' are domain jargon with no elaboration, and it never distinguishes this from the sibling tools loop_status or apply_fix, so an agent must infer how it differs.

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?

The clause 'whose fix was served' implies the precondition (a fix has already been applied), giving implicit usage guidance. But it never explicitly says when to use this instead of loop_status for checking run state, nor does it name any alternative or exclusion.

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