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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: the probe is unpaid and bounded (~2.2s cap), the return splits into LIVE and HISTORICAL parts, the verdict is ADVISORY and not a warranty, UNKNOWN is a legitimate answer with specific conditions, and being charged nothing when the target is unreachable and unobserved. It also states the cost and payment rail ($0.002 USDC via x402 on Base). This goes far beyond annotation hints.

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?

Though the description is long, it is structured with clear headings ('WHEN THIS PAYS FOR ITSELF', 'WHEN IT DOES NOT', 'Returns two halves') and densely packed with actionable information. Every sentence contributes to understanding the tool's purpose, cost, limits, and return value. The front-loaded purpose sentence immediately clarifies the tool's role.

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, so the description carries the burden of explaining return values. It does so thoroughly by detailing the LIVE half (reachability, HTTP status, latency, MCP initialize probe, price/payTo) and the HISTORICAL half (reliability, payTo changes, price changes, tool-schema changes, first-seen date, credit grade). It also covers edge cases (UNKNOWN semantics, freshness via max_age_seconds, and charging nothing when unobserved and unreachable). For a tool with this complexity, the description is 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?

The input schema has 100% coverage, properly describing each parameter. The description adds functional meaning on top: expected_price, expected_payto, and expected_schema_hash are compared 'old to new' with a date of first observed change, and probe_method is restricted to side-effect-free methods. While the schema already documents the parameters, the description clarifies how they are used together in the comparison logic.

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 a clear verb and resource: 'Check that an endpoint is live and that its terms have changed, BEFORE you send it an expensive request.' It distinguishes this tool from sibling tools focused on credit scores, revenue estimates, drift, etc., by emphasizing preflight liveness and terms verification before a consequential call.

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 explicitly states when to use it ('Buy it before a consequential call — expensive inference, a purchase, a state-changing action') and when not ('not before a cheap one'), even providing a quantitative cost-benefit example. It also contrasts with sibling tools by focusing on preflight checks rather than ongoing monitoring or credit evaluation.

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