Retirement Contribution Limits 2027

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

Annotations already establish that this is a safe, read-only, idempotent, closed-world calculation, so the description spends its words well on domain behavior instead: the exact rule set applied (402(g) sharing, separate 457(b) limit, compensation cap, HSA catch-up) and the SECURE 2.0 age 60-63 cliff. What it does not cover is the shape of the response (per-plan breakdown? single total?), which matters since there is no output schema.

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 verb and inputs, and every clause carries factual load rather than filler. It is a single dense paragraph, though; the long run-on rule list would scan faster as a short structured enumeration.

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 7-parameter, rule-heavy domain tool with no output schema, the description conveys the required inputs, the optional inputs that unlock extra behavior, and the governing rules. The remaining gap is return-value structure and the defaults/effects of the two boolean flags.

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%, so the baseline is 3; the description earns a bump by adding meaning the schema cannot: age must be measured at Dec. 31, the 60-63 window explicitly excludes 64, and prior_year_fica_wages carries a concrete threshold (2026: over $150,000 of 2025 FICA wages). It leaves simple_higher_limits and plan_offers_super_catch_up unmentioned, so it does not fully close the loop.

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?

States a specific verb ('Calculates') and a precisely scoped resource: the maximum contribution given age, year, plans and wages. The scope is distinct from siblings like get_contribution_limits (raw limits) and compare_years, so an agent can route 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?

Usage is only implied: the description enumerates which rules the tool applies, which hints that it is the tool to reach for when you need a personalized max rather than a raw limit table. It never explicitly says when to use this versus get_contribution_limits or compare_years, nor does it state any prerequisites or exclusions.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavioral information beyond them: unpublished figures (e.g., 2027 plan limits as of 2026-11-02) return as null rather than being estimated, which is exactly the kind of caveat an agent needs to interpret results.

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 dense sentences that lead with the comparison output and follow with the null-handling caveat; the figure list is long but readable and materially useful. Nothing is redundant with the title, though the enumeration could be trimmed slightly.

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 correctly carries the burden of describing return content (side-by-side dollars and percent change) and null semantics, so an agent knows what to expect. The remaining gap is edge-case behavior for invalid or reversed year pairs, which is not addressed in either the schema or the description.

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 50%, but the undocumented parameter (to_year) is a $ref to from_year, which is itself described as 'Calendar year: 2025, 2026 or 2027.' The description reinforces the two-year scope but adds no new semantics, such as whether reversed years are rejected or whether a one-year range is legal (the schema imposes no ordering constraint).

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 gives a specific verb and output shape ('Shows each retirement, IRA, HSA and Social Security figure for two years side by side with the dollar and percent change') and enumerates exactly which figures are covered. It is clearly a comparison tool rather than a single-value lookup, but it never names the sibling tools (get_contribution_limits, get_social_security_cola) that would be the obvious alternative for a one-year query.

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 only implied: an agent can infer this is the tool for two-year comparisons while the siblings retrieve single values. There is no explicit 'use this when / use X instead when' statement and no mention of prerequisites such as whether prior-year data must already be cached.

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

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.

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 goes beyond them by naming the provenance (SSA's official annual notice in the Federal Register) and by disclosing a concrete figure set, which tells the agent this is authoritative published data rather than a computed estimate.

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?

One front-loaded sentence opens with the verb and the subject, then enumerates the returned figures. The dense numeric listing is long but each figure earns its place as expected return content, though it risks going stale and could have been condensed into field names.

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 carries the full burden of describing return content and does so by listing the concrete returned figures. Combined with annotations covering the safety profile and a fully documented single parameter, an agent has everything needed to invoke 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?

Schema description coverage is 100% and the single parameter already documents the valid range (2025-2027) with min/max bounds. The description restates the same year coverage without adding format or semantics beyond the schema, so baseline 3 applies.

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 definition states a specific verb ('Returns') and a well-defined resource set (COLA, taxable maximum, earnings test limits, quarter of coverage, SGA, SSI), so the agent knows exactly what data comes back. It does not explicitly contrast itself with the sibling tools (get_contribution_limits, compare_years), leaving the differentiation to be inferred from content 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 only implied: the year range ('Covers 2025, 2026 and 2027') signals when it is applicable, but there is no explicit statement of when to call this instead of get_contribution_limits or compare_years. No prerequisites or exclusions are given.

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