GAIP Integration Repair Agent

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

Beyond the annotations, it discloses the side effect ('GAIP touches no other system'), the auth/cost model ('Free, no account'), exactly what is persisted ('records a GAIP receipt only'), and a data-handling constraint ('Inputs must be public and non-personal'). This accounts for the non-readOnly/non-idempotent annotation profile by explaining that only a receipt is written.

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?

It is front-loaded with the triggering scenario and what to pass before moving to outputs and constraints, and every sentence carries information. It is dense and slightly parenthetical-heavy, but there is no filler.

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 output schema, the description still enumerates the return contents (likely cause, when/how to retry, fix steps, receipt), and with 9 params at 100% schema coverage the remaining fields are self-documenting. Nothing needed to call it correctly is missing.

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 already 100%, so the baseline is 3, but the description adds real meaning: it clarifies the required 'failure' payload shape ({code, detail}) and, notably, that raw error text is an acceptable alternative input. It does not explain the optional continuity_handle or episode_id linkage beyond what the schema already states.

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 a specific verb+resource — diagnosing a failed agent/MCP/API call and returning cause, retry guidance, and fix steps. It is clearly distinguishable from siblings like gaip_observatory_lookup, gaip_watch_events, or check_agent_conformance, which observe or monitor rather than diagnose a single failure.

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 invocation triggers ('why did my call fail?', 'what does this 429 mean?') and tells the agent what to pass (the failure object or raw error text). It does not name an explicit alternative tool or state when NOT to use this, so it stops short of a full routing rule.

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?

Annotations already declare read-only, non-destructive and non-open-world, but the description adds genuinely new behavioral facts: it is free, requires no account, inputs must be public and non-personal, and results are time-correlated observations rather than causal claims. That last caveat is important for interpretation and is not in any structured field; only rate limits and the meaning of idempotentHint=false (repeated calls may return different observations) are left unstated.

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?

Three sentences, front-loaded with the usage trigger before inputs and traits, so every sentence does work. It is slightly dense with stacked parentheticals and prose asides, but nothing is wasted.

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 11 params, nested objects, and no output schema, the description does the necessary compensating work by summarizing the return ('diagnosis plus changes observed... with receipts'). The one real gap is the missing boundary against gaip_diagnose_integration_failure, which matters given the overlap in inputs and purpose.

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 100% with 11 well-documented params, so the schema already carries parameter meaning. The description names supplier_url and failure but adds no format, defaults, or constraint detail beyond the schema, making 3 the correct baseline.

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 gives a specific trigger and outcome: it diagnoses why 'a supplier agent or API you depend on started failing' and returns 'the diagnosis plus changes GAIP observed around then.' That is a clear verb+resource, but it never names or contrasts with its only sibling, gaip_diagnose_integration_failure, which the input schema itself references ('as for gaip_diagnose_integration_failure'), so the supplier-vs-integration boundary is left ambiguous.

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 opens with an explicit selection condition ('Use this when a supplier agent or API you depend on started failing') and even supplies the user's likely phrasing ('did something change on their side?'). There is no when-not guidance and no pointer to the sibling for the alternative case, which keeps it short of a 5.

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