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

No annotations are provided, so the description carries the behavioral burden. It discloses the two operational modes (taxonomy listing vs. slug detail), the per-topic bill counts, and the sample of raw subject names. The GET verb implies a read-only operation, and the relationship to search_bills clarifies what the tool does *not* return. Missing error-behavior details are a minor gap.

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?

Two sentences, front-loaded with the core purpose, then the usage guidance and alternatives. Every phrase adds value; no redundancy or fluff.

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 read-only listing tool with no output schema, the description explains what to expect from both invocations (taxonomy with counts, slug detail with sample subject names). It omits error-handling details and explicit authentication requirements, but given the simple optional-slug pattern and the schema's max_items hint, the agent has enough to call it 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 schema already describes both parameters at 100% coverage, giving a baseline of 3. The description adds strategic meaning for 'slug' by framing it as the key for the search_bills topic filter and explaining the detail response. 'max_items' receives no extra description, but the schema already explains it adequately.

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's role as 'the canonical topic taxonomy with per-topic bill counts' and the GET endpoint. It distinguishes itself from search_bills by explicitly noting that actual bills are retrieved via that tool, and from raw subject names via the mention of 'sample of the raw subject names folded into it.'

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?

Provides explicit when-to-use guidance: 'Call this first to find the right slug for the topic filter on search_bills, instead of guessing one.' It also tells when to omit vs. pass a slug and routes the agent to search_bills for the actual bills, making the choice clear.

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