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.