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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond those annotations by specifying the boundaries of the dataset: no secondary-market trade prices and no CUSIP identifiers. It reinforces the open-world hint by warning against interpreting empty results as absence of issuance, which is genuinely helpful.

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 sentences with no filler, each earning its place: what is covered, what is explicitly excluded, and a critical usage caveat. The description is front-loaded with the core purpose and remains tightly scoped for a discovery-oriented tool.

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 zero-parameter, no-output-schema tool, the description is admirably complete: it states the data classes, the count dimension, the date range, and the notable exclusions. The only minor gap is that it does not name the sibling tools it complements, but an agent can still act correctly from the provided context.

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 tool has zero parameters, so the description carries no burden to explain parameter behavior. It instead provides the meaningful semantic context an agent needs: what data is included, its scope, and its limitations. This is appropriately handled given the empty schema.

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 that this tool reveals what New York public authority debt data is available, covering the four authority classes, issue counts, and date range. It also differentiates itself by explicitly listing what is NOT included (trade prices, CUSIP identifiers), which helps distinguish it from related debt tools. It lacks a strong imperative verb naming the operation, but the scope is unmistakable.

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 instructs the agent to read this tool before treating an empty search result as evidence that an authority issued nothing, giving a concrete when-to-use context. It also states exclusions, telling the agent this tool will not provide secondary-market prices or CUSIPs, which implies when not to use it. However, it does not name specific sibling alternatives for those needs.

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