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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description's main contribution is substantive: it discloses the output shape (issues, terms, fiscal-year totals, new money/refunding breakdown) and the coverage boundary (primary-market only, no trade prices). This adds useful behavioral context beyond the annotations without contradicting them.

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 three sentences with no filler: it front-loads the core scope, provides concrete illustrative questions, and ends with a crucial data-coverage caveat. Every sentence serves a distinct purpose and earns its place.

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?

Despite having no output schema, the description fully explains what the tool returns—individual issues with terms, fiscal-year totals, and new money/refunding breakdowns—and states the data universe and exclusion. Combined with a well-covered input schema regarding the only required parameter, an agent has enough context to select and invoke the tool correctly.

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 input schema has 100% description coverage for both parameters: 'authority' is documented as loosely matched, and 'limit' has a default and maximum. The description adds examples of authority names and clarifies the scope to one authority, but it does not materially expand on the parameters' meaning beyond the schema, so the baseline of 3 is appropriate.

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 returns the complete debt issuance profile for a single New York public authority, including individual issues, fiscal-year totals, and new money versus refunding breakdown. While it does not explicitly name sibling tools such as ny_authority_debt_search or ny_authority_debt_totals, the singular 'one New York public authority' scope effectively differentiates it from those broader search/total tools.

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 concrete usage scenarios via example questions like 'how much has the Dormitory Authority borrowed' and 'is this issuer mostly refinancing', making the intended use clear. It also states a key limitation—primary-market issuance only, with no reported trade prices—which implicitly tells the agent when this tool is not appropriate. It does not explicitly enumerate alternatives, so it falls short of a 5.

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