va_facilities

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

Annotations already declare readOnlyHint: true, so the tool's safety is known. The description adds value by specifying the output fields (facility names, addresses, phone numbers, services) and explaining facility type enum values. However, it does not disclose pagination behavior or that all parameters are optional, which could affect usage.

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 concise: three sentences plus an example. It front-loads the tool's purpose, then adds return details and type explanations, with a final usage example. Every sentence contributes either to understanding the tool's scope or its usage, with no redundant 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?

The tool has no required parameters (per schema) and no output schema, but the description does not clarify that state and type are optional or that page/limit have defaults. It implies searching 'by state and type' without noting that omitting them is allowed. Given the schema explains parameter details, the description is adequate but misses the optionality nuance, so it is not fully 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?

Schema description coverage is 100%, and the description adds meaning beyond the schema by explaining each facility type in plain language and providing a concrete example that clarifies how to use state, type, and limit together. This helps the agent map user intent to parameter values.

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 clearly states the tool searches VA facilities, lists the specific facility types (hospitals, clinics, cemeteries, benefits offices, vet centers), and notes what it returns (names, addresses, phone numbers, services). This distinguishes it from sibling tools by focusing specifically on the VA facility domain.

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 a clear context for the tool (VA facility search) and includes an example invocation with state, type, and limit. However, it does not explicitly mention alternative tools or when not to use this tool, relying on the domain name to imply exclusivity to VA facilities.

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