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

With no annotations, the description carries the full burden and does disclose the most important behavioral trait: results are capped at up to 50 rows and the complete set (plus CSV) lives at the state page url, which tells the agent about truncation and how to get exhaustive data. It omits permission/auth requirements and how the state page url is obtained, so it is strong but not exhaustive.

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?

Three tight sentences with the selection condition front-loaded, followed by scope and output behavior. Every sentence adds information; nothing restates the tool name or title.

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?

For a 4-parameter, read-style listing tool with no output schema and no annotations, it covers purpose, scope, result cap and where the full dataset lives. What's missing is minor but real: the default value of limit and any indication of data source/freshness or the shape of a row beyond 'page urls'.

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 only 25% (only state is documented), so the description must compensate, and it does: it maps kind values to real-world facility types including the FQHC/health-center equivalence, notes city is optional ('optionally one city'), and implies the limit ceiling via 'up to 50 rows'. It does not state a default limit or that state is the required two-letter code, leaving some schema-documented gaps for the caller.

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?

States a concrete verb-resource pair (lists facilities) scoped by kind and state/city, and explicitly contrasts it with 'one named provider' lookups. It even expands the kind enum into plain language (home health agencies, hospices, hospitals, nursing homes, FQHCs), so the agent knows exactly what population this returns.

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?

'Use when the question is about facilities of a kind in a state or city rather than one named provider' gives a clear selection condition and sets a boundary against provider-lookup siblings. It stops short of naming search_providers or nearby_providers, so the agent must still infer which of those is the alternative for partial-name or radius queries.

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