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

Annotations only declare readOnlyHint=true and openWorldHint=false; the description supplies the real behavioral substance an agent needs to trust the numbers: transfers tax-free under 26 U.S.C. 1041 with carryover basis, LTCG at 2026 0/15/20% plus 3.8% NIIT, section 121 $250,000 exclusion with selling costs, QDRO 401(k) taxed as income without the 10% penalty, IRA 10% penalty before 59½, and a retirement draw rate. That is exactly the kind of modelling assumption the annotations cannot convey.

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?

Every clause carries real content and the scope ('US divorce, tax year 2026') is front-loaded before the tax mechanics and return description. The weakness is structural: the entire definition is one semicolon-chained sentence, so the tax rules and the return-value statement are not visually separated for quick scanning.

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 takes on the burden of describing returns — each spouse's share on paper and after tax, plus the equalizing cash payment — which is sufficient for an agent to interpret results. Nested spouse and asset objects are fully described in the schema, so the only gap is the exact shape and units of the returned figures.

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 already 100%, so the baseline is 3, but the description adds meaning the schema lacks: it explains why cashOut, over59, qualified, retireRate, sellPct and basis matter by tying each to a specific tax treatment (QDRO income tax, early-withdrawal penalty, Roth qualification, §121 use test). It also clarifies targetShareA's role by describing the output as 'the cash payment that reaches the agreed share.'

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 names a specific verb and resource: computing the after-tax value of each asset for the spouse who receives it in a US divorce for tax year 2026. It goes on to enumerate the exact asset classes handled (brokerage, home, 401(k)/QDRO, IRA, Roth, cash, debt) and the outputs, so an agent can distinguish it from every sibling calculator 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?

Scope is clear — US divorce, tax year 2026, after-tax asset valuation and the cash equalization payment — which implicitly tells an agent when this tool applies and when a different country/tax tool does. What's missing is any explicit exclusion or named alternative (e.g., a pre-tax or non-divorce split calculation), so the routing guidance is inferred rather than stated.

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