FacilityProof

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

Beyond the readOnly/idempotent annotations, the description discloses that this is a $15.00 paid operation, that facility identity and state availability are resolved before payment, and that invalid or unresolved requests are not charged. It also previews output behavior such as freshness, source gaps, and unresolved conflicts. This is substantive behavioral context the annotations do not provide.

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 definition is compact and information-dense: cost, preconditions, output domains, and no-charge behavior all earn their place. The main action is delayed behind the opening price/availability clause, and the first sentence is slightly awkward as a fragment, but overall there is no filler or redundancy.

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 that an output schema exists and annotations cover safety and idempotency, the description supplies the additional operational details an agent needs: payment, resolution-before-payment behavior, and failure/no-charge semantics. The main missing piece is practical parameter guidance for facility resolution, but the schema and output schema together make the tool usable.

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 only 43%: name, frsId, and programId have descriptions, while zip, city, state, and address are undocumented. The description says to 'resolve one U.S. physical facility' but does not explain how the optional location fields disambiguate, how the anyOf alternatives relate, or what precedence to use among name, frsId, and programId. The description does not compensate for the schema coverage gap.

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 action ('Resolve one U.S. physical facility, then return source-backed environmental regulatory evidence') and a precise scope: core air, water, hazardous-waste, and drinking-water programs. It also enumerates the kinds of evidence returned, so an agent can tell exactly what this tool is for. No sibling tools are listed to differentiate against.

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 provides clear context for invocation: it is a paid specialist operation available only 'when commerce is active in a production-ready state,' and it states that ambiguous, unresolved, or unreleased-state requests are not processed or charged. It does not name alternatives, but there are no sibling tools, so the absence of explicit comparison is not a significant gap.

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