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

The description goes well beyond the readOnlyHint and destructiveHint annotations by explaining that a failing leg is 'noted, not fatal,' that category inference occurs, and that the tool is an 'INFORMATIONAL public-record read' with explicit disclaimers. This gives an agent accurate expectations about partial results and non-authoritative status.

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 long but information-dense, front-loading the core purpose before enumerating data fields and caveats. It could be slightly tightened, but each sentence contributes operational or behavioral detail that an agent needs for a complex multi-source lookup.

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 compensates by detailing what fields the agent can expect across facility types, including star ratings, measure-group highlights, ownership, fines, and NPI identity data. It also covers fallback behavior, provider-type inference, and what the tool is not. This is complete enough for an agent to select and invoke the tool effectively.

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 100%, but the description adds meaningful usage semantics: the 'type' parameter pins the CMS dataset, the 'state' parameter disambiguates facilities, and the 'facility' parameter is shown with concrete examples. It also explains auto-detection behavior when 'type' is absent, which the schema alone does not convey.

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 specific verb and resource: 'One-call care-quality + provider-identity read for a named US healthcare FACILITY.' It enumerates the exact CMS datasets and the NPPES source, so an agent understands both what the tool does and what data it combines. This clearly distinguishes it from narrower CMS-only search siblings.

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 gives clear operational context: provide a facility name, optionally add a state or type, and explains what happens when type is omitted ('infers the provider category from the NPPES taxonomy and probes the CMS datasets in order'). It does not explicitly name sibling alternatives or state when to prefer them, but the guidance is strong enough for correct invocation.

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