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

The description adds valuable behavioral context beyond the annotations: the paid cost (500 micro-dollar credits per successful call), prerequisites, authentication requirements, and the billing/recovery semantics tied to requestId reuse. This is especially useful given the tool has a financial side effect and aligns with idempotentHint without contradicting any annotation.

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 compact and efficiently front-loaded: purpose first, then cost, prerequisite, auth, and recovery semantics. Every sentence adds distinct operational information and 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?

Given the tool's complexity as a paid, auth-gated, idempotent operation with an output schema, the description covers purpose, cost, prerequisites, auth, and recovery. The main gap is the lack of explicit guidance on when to choose this over related contract tools, but the structured schema and output schema carry most remaining invocation details.

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 descriptions cover two of three parameters, and the description strengthens their meaning by linking requestId to prepared arguments and billable operations and by clarifying the recovery context behind maxPriceMicroUsd=0. The input.document parameter still lacks explicit schema detail, but the purpose statement partially compensates by specifying OpenAPI 3.0 JSON structure.

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 'Validate OpenAPI 3.0 JSON structure and internal references,' which names a specific action and resource and clearly identifies what the tool operates on. It is distinct enough from related siblings like contracts_openapi_diff and contracts_jsonschema_validate, though it does not explicitly name or contrast those alternatives.

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 description provides clear operational context: call agent_utilities_prepare first, require existing credits and an Authorization header, and reuse prepared arguments for recovery. It does not, however, give explicit exclusions or direct comparisons with sibling tools, so the when-versus-alternatives guidance is incomplete.

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