databutler-us-rates

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: each figure carries a source URL, quoted sentence or table row, verifiedDate, and prior-year value, and unknown categories degrade to covered:false with nearest keys. It does not address data refresh cadence or rate limits, which is the only remaining 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?

It is front-loaded with the purpose and the source-provenance claim, but the middle sentence is a very long, comma-spliced enumeration of every sub-figure in all six categories. Much of that list duplicates the category enum already in the schema, and the run-on structure makes it harder to scan than a short category table would be.

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?

There is no output schema, so the description must carry the return shape, and it does: provenance fields, verifiedDate, prior-year values, and the covered:false fallback. For a zero-required-parameter reference lookup this is close to complete; only the grouping/ordering of returned figures is left unstated.

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 100% and the single category parameter is fully described in the schema, so the baseline is 3. The description goes further by spelling out what each category actually contains (e.g. bracket rows by filing status, OASDI wage base, § 415(c) limits, HDHP minimums), which helps the agent choose the right value rather than just validating it.

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 opens with a specific verb and resource — reads current US federal tax-year-2026 rates and thresholds from named authoritative sources (IRS revenue procedures, SSA Federal Register, irs.gov) — and enumerates the exact categories covered. There are no siblings to disambiguate against, and an agent can tell precisely what this tool returns without opening the schema.

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?

It gives an explicit negative boundary ('Federal only: state income taxes, AMT, EITC and capital-gains brackets are not covered') and a failure mode ('An unknown category answers covered:false with the nearest keys'), plus the omit-to-list-all behavior. What is missing is any positive 'call this when you need X rather than computing it yourself' framing, but with no siblings the routing guidance is effectively complete.

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