underwrite_backsolve

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

With no annotations provided, the description carries the full behavioral burden, and it does so strongly. It discloses the iterative bisection method, the fact that debt/tax/equity are re-priced each run, the response fields, the safety guarantee that no price outside a proven bracket is returned, and that missing-input refusals are delivered as payloads rather than validation crashes.

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?

Three dense sentences cover purpose, algorithm, outputs, safety guarantee, and a quirk about optional arguments. Every sentence earns its place, and the most important information is front-loaded in the first sentence.

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?

The description is thorough about behavior and outputs, but this is a complex 8-parameter tool with no output schema and no annotations. It doesn't explain what the `inputs` argument should contain or what the required core inputs are, so an agent could struggle to invoke it correctly even though it understands the tool's intent.

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?

The description adds important meaning for the core parameters: 'target Year-1 post-debt cash-on-cash return' maps to target_coc_pct, 'highest price' relates to min_price/max_price, and 'iteration count' relates to max_iterations. However, with 0% schema description coverage, it still leaves the critical `inputs` parameter unexplained, and several other parameters like agency_spread_pct and benchmark_5yr_treasury_pct are only implied by domain terminology, not actually described.

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 opens with a specific verb and resource: 'Backsolve the highest price meeting a target Year-1 post-debt cash-on-cash return, via the engine's own search.' This clearly distinguishes it from sibling tools like underwrite_run or evaluate_bid, which imply running at a fixed price or evaluating a proposed bid rather than solving for a price.

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?

The description provides clear context for when to use the tool: when you need to find the highest price that hits a target cash-on-cash return. It doesn't explicitly name alternatives or state when not to use it, but the 'backsolve' framing makes the intended use case obvious enough for an agent to select it over the siblings.

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