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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the data provenance ('Figures copied from IRS Notices 2024-80 and 2025-67 and the HSA Rev. Procs.'), a year-range boundary, and the explicit refusal-to-guess behavior for unannounced 2027 limits, which tells the agent to trust partial results rather than treat them as errors.

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 verb and scope in the first clause, and the dollar figures serve a real purpose by letting the agent confirm coverage without a call. The enumeration is dense and runs long, but each clause carries a distinct limit category rather than filler.

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 carries the full burden of describing return content — and it does so concretely with named figures, sources, and a stated data-freshness boundary. An agent has everything needed to call it correctly and interpret the results, including what happens for unannounced years.

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 enum values are fully self-documenting, so the baseline of 3 applies. The description restates the year range but adds no semantics beyond the schema — no explanation of e.g. which figures differ by account type or what 'all' returns in terms of shape.

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?

A specific verb and resource ('Returns official IRS contribution limits') followed by an exhaustive enumeration of the covered limit types (401(k), IRA, SIMPLE, 415(c), HCE, HSA, Social Security wage base) makes the scope unmistakable. It does not explicitly contrast itself with siblings like calculate_max_contribution or compare_years, so the differentiation is inferable rather than stated.

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 is implied: this is a static reference lookup parameterized by year and account type, and the note that '2027 plan and IRA limits were not yet announced on 2026-11-02 and the tool says so instead of guessing' usefully preempts a wrong expectation about completeness. However, there is no explicit routing guidance telling the agent when to call this versus calculate_max_contribution or compare_years.

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