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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety bar is low. The description adds genuinely useful context beyond them: the data provenance (CDIAC, coverage back to 1984, 76,000+ issues), the geographic restriction to California issuers, and the per-issue field set returned (CDIAC number, ratings, TIC, underwriter/advisor/bond counsel).

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?

Front-loaded with the core action and scope, then filters, then return fields, then example questions — a sensible ordering with no filler sentences. The return-field enumeration is long, but it earns its place because there is no output schema; only minor tightening is possible.

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 listing what comes back per issue, and it discloses data source, historical coverage, geographic scope, and the filter dimensions. Combined with a fully documented 17-parameter schema, an agent has everything needed to call this 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?

Schema description coverage is 100% across all 17 parameters, including enumerated value hints and example strings, so the schema carries the burden. The description's 'Filter by issuer, county, debt type, purpose, tax status, sale date and principal amount' largely restates those parameters rather than adding syntax or format meaning beyond them.

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?

Specific verb+resource+scope: 'Search California municipal bond issuance ... every state and local government bond, note, certificate of participation and Mello-Roos deal reported to CDIAC since 1984.' The explicit 'Returns per-issue ...' framing implicitly separates it from aggregate siblings like ca_debt_statewide_totals and ca_debt_issuer_profile, and the 'California issuers only' clause nails the 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?

Usage context is well established through concrete trigger questions ('how much debt did this California school district issue', 'which California cities sold bonds this year'), which tell the agent when this tool applies. However, it never names an alternative or states when NOT to use it (e.g. use ca_debt_statewide_totals for aggregates, ca_debt_issue for a single deal), so it stops short of full routing guidance.

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