1031.help: exchange deadlines, tax math and DST filings

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.

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 genuine behavioral context by disclosing the computation rules — day 180 yields to the tax return due date when that comes first, varying by filer type and extension — plus weekend/federal-holiday flags and a 'days left' calculation. With no output schema, this disclosure of return content is valuable.

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?

It is a single dense sentence that front-loads the anchor input ('From the date the relinquished property closed') before listing outputs, with no filler. It is close to a run-on and could be split into an input statement and an output statement for faster scanning, but every clause carries information.

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 pure read-only calculator with three simple parameters, no output schema, and full schema coverage, an agent needs to know the input anchor, the branch conditions, and what comes back — all of which the description supplies, including the tax-return-due-date exception and the practical 'last closing date with full 180 days' output. Nothing required to call it correctly is missing.

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 a 3 is the baseline; the description earns above that by explaining why the non-required parameters matter, noting the exchange period depends on 'filer type and extension.' It also anchors sale_date as the relinquished-property closing date, reinforcing the schema's own note about using the first closing.

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 the specific resource (1031 exchange deadlines) and enumerates exactly what is computed: the 45-day identification deadline, the end of the exchange period, weekend/holiday flags, days remaining, and the last qualifying closing date. That is far more specific than the title alone. It does not explicitly contrast itself with siblings (estimate_exchange_tax, list_dst_offerings), but their purposes are distant enough that confusion is unlikely.

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?

"From the date the relinquished property closed" establishes the triggering context and the schema clarifies that for multiple sales in one exchange the first closing is used, so usage is implied clearly. However, there is no explicit when-to-use/when-not statement or routing to alternatives such as estimate_exchange_tax for tax liability instead of deadlines.

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 readOnly/idempotent/non-destructive/closed-world, so the safety bar is low. The description adds real behavioral detail beyond them: results are ordered newest filing first, and the response includes totals for the filtered set. It says nothing about rate limits or response size limits, keeping it from a 5.

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 sentences, front-loaded with what the tool returns and followed by filter/paging mechanics. The first sentence is a long comma-delimited field dump, which is informative but denser than necessary; still, every clause serves a purpose.

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 compensates by enumerating returned fields and the presence of aggregate totals. Combined with 100% schema coverage for the six optional parameters, an agent has what it needs to call this correctly; only edge behaviors like empty-result handling are absent.

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%, including enum values, patterns, and per-parameter examples, so the schema carries the load. The description only restates the filter axes at a high level and adds no format or syntax detail beyond what the schema already provides, matching the baseline 3.

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?

Names a specific verb and resource ('Delaware statutory trust offerings from SEC Form D filings') and enumerates the returned entity scope (issuer, offering size, first sale date, exemption, broker-dealers). An agent knows exactly what dataset this retrieves, and the sibling tools (exchange tax, deadlines) are so unrelated that no disambiguation is needed.

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?

Explicitly states the available filter axes and paging mechanism, so an agent knows how to narrow the query. It gives no when-not-to-use condition or alternative tool, but there is no plausible sibling alternative here, and the 'Filings data, not an offer or recommendation' line sets usage context.

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