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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is to explain what is computed — and it does, naming each tax component (1245 recapture, unrecaptured 1250 at up to 25%, stacked 0/15/20% rates, 3.8% NIIT, state tax) and the exchange outputs. It also discloses scope limits (2025 or 2026 brackets) and provenance ('same engine as the 1031.help calculator'), though it does not state that results are estimates with no filing-grade guarantee.

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 primary computation, with the conditional exchange branch clearly signaled by 'when a replacement price is given'. The single dense sentence packing the tax components is information-rich but borders on a list dump.

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 15 parameters and no output schema, the description carries the return-value burden and does so fully: it names every output (gain, recapture, unrecaptured 1250 gain, NIIT, state tax, cash left, boot, boot tax, deferred gain, replacement basis). Combined with the bracket-year scope, an agent has everything needed to call it and interpret the result.

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 baseline is 3; the description still adds value by explaining the conditional role of replacement_price (it toggles the entire exchange/boot computation) and by tying other inputs into the described outputs (other income drives capital gains stacking, depreciation drives recapture). It does not clarify ambiguous inputs such as cash_added or depreciation_personal_property beyond what the schema already says.

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 and resource ('Estimates the tax on selling investment real estate outright') and enumerates the computations performed, including the 1031 branch when a replacement price is supplied. Nothing about it could be confused with the sibling tools exchange_deadlines or list_dst_offerings.

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?

Gives a clear triggering condition for the second mode: 'when a replacement price is given' you also get the exchange result, which tells the agent how to switch between sell-only and exchange analysis. It stops short of explicit when-not-to-use guidance (e.g., personal residence, non-US property), but no sibling competes for the same job.

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