TerraVue

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description adds real behavioral context beyond them: it clarifies that monthly_debts feeds DTI while monthly_expenses is deliberately excluded, and that supplying address switches from national defaults to ZIP-grounded tax/insurance figures. It does not disclose latency, caching, or external-call implications of the open-world lookup.

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 question and output list, then the two parameters that most change results. The trailing paragraph largely restates schema-level guidance, which is mild redundancy, but no sentence is filler and the sizing fits a 12-parameter financial tool.

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 (PITI, DTI ratios, 28% income need, after-tax slack, cash cushion, verdict), and it explains how optional inputs change those returns. For a complex 12-parameter tool it covers everything an agent needs to call it correctly.

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 schema already documents all 12 parameters with units and percent-vs-fraction warnings. The description's distinct contribution is sharpening the monthly_debts vs monthly_expenses split, but the same distinction is already stated verbatim in the schema property descriptions, so the marginal value is small. Baseline 3 is appropriate.

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 states a specific question ('Can this buyer afford this home?') and enumerates the exact computed outputs (PITI, front/back-end DTI, 28% income requirement, after-tax slack, cash cushion, verdict), so the agent knows precisely what the tool answers. However, it never names or contrasts with the closest sibling, affordable_price, leaving the affordability-vs-max-price distinction to inference.

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?

It gives conditional guidance for optional inputs ('Pass `address` whenever it is known', 'Pass `liquid_savings` to get the post-closing cash cushion'), which implies usage context. But there is no when-to-use-this-tool-vs-alternatives guidance, no exclusion conditions, and no mention of when buy_vs_rent or affordable_price would be the better call.

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 only declare readOnlyHint and openWorldHint; the description goes well beyond by disclosing the two default DTI caps, the conditional behavior when `liquid_savings` is supplied (adds cash cushion and reports which limit binds), and the returned fields. It does not contradict the annotations. Only missing piece is any note on precision/assumption limits of the solver.

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 core question, then the mechanism, then the caveat and downstream handoff. Dense and mostly waste-free, though the two-paragraph layout is slightly long for the content.

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 complex 11-parameter solver with no output schema, the description explains the computation, the conditional outputs, and the returns (price, PITI, DTIs, cash to close). An agent has enough to invoke correctly.

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 description coverage is 100%, so baseline is 3, but the description adds real meaning beyond the fields — it ties `liquid_savings` to a limit-binding outcome and `address` to ZIP-grounded tax/insurance rates. This exceeds what the schema alone conveys.

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 computational verb+resource: it solves for the maximum affordable home price. It explicitly contrasts itself with the `affordability` sibling ('the reverse of affordability — what price can I afford? instead of can I afford this specific home?'), so an agent can route without opening either 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?

Gives explicit when-to-use, an exclusion ('This is a lender-limit ceiling, not a comfort recommendation'), and names the downstream alternatives (`affordability`, `buy_vs_rent`) to feed the result into. Usage is fully determined.

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=true and openWorldHint=true, so safety is covered. The description adds real context beyond that: data provenance (FHFA back to 1975), what the sub-ZIP nbhd* fields mean, and a caveat that they represent POSITION rather than a neighborhood forecast. The forward reference to '_units' is unexplained and undefined in the 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?

Information-dense and front-loaded: the primary output set comes first, then the sub-ZIP caveat. It is slightly cluttered by the dangling '_units' pointer, but no sentence is purely redundant.

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 carries the return-value burden and does so by naming the forecast, rent, neighborhood signals, and sub-ZIP fields. Annotations cover the safety profile, and the only omissions are rate limits/auth and explaining the '_units' reference.

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 description coverage is 100%, so the baseline is 3. The description restates the property_type values (sfr | condo | townhome | multi), which is marginally helpful since the schema lists no formal enum, but this duplicates the schema's own field text rather than adding meaning.

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 states a specific verb ('look up') and resource ('a US address or bare 5-digit ZIP') and enumerates the returned dimensions: appreciation forecast, market rent, and neighborhood signals. This is clearly distinguishable from analytical siblings like buy_vs_rent or affordability, though it never names an alternative to contrast against.

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?

It implies when to pass a full address versus a bare ZIP (the nbhd* sub-ZIP fields only appear with a street address), which is useful. But it gives no guidance on when to choose this tool over affordability, affordable_price, compare_areas, or buy_vs_rent, so the agent must infer routing.

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 only declare readOnlyHint and openWorldHint; the description adds genuinely non-obvious behavior — deterministic simulation plus Monte Carlo over correlated market paths, and the specific return values (win probability, breakeven, net worth). It also discloses the precedence rule that explicit parameters override ZIP defaults, which is behavioral context the annotations do not carry.

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 decision and the engine, then returns, then parameter caveats — good ordering with no filler. The monthly_rent paragraph partly restates the schema's own description, which is mild redundancy but defensible given how easy that field is to misread.

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 10-parameter financial simulation with no output schema, the description covers the mechanism, the return values, key parameter caveats, and the address-vs-explicit-parameter precedence. Nothing critical to calling 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 parameters are already documented, but the description adds real semantic value: it disambiguates `monthly_rent` as owner-occupant rent (not landlord income) and supplies the sanity heuristic that a rent far out of line with home_price signals a misunderstanding. That heuristic goes beyond anything in the schema.

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 the exact decision the tool answers ('Should someone buy this home or keep renting?') and names the mechanism (TerraVue engine, 30-year deterministic simulation + 500-scenario Monte Carlo) plus the outputs (probability buying wins, breakeven hold period, net-worth outcomes). It is a specific verb+resource, though it never explicitly contrasts itself with siblings like affordability or affordable_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?

It clearly frames the use case as an owner-occupant decision and routes the landlord/rental-income lens elsewhere, and it gives situational guidance ('confirm rent before trusting the verdict', pass `address` whenever known, prefer unset appreciation over a guess). There is no explicit when-not relative to the sibling tools, so it falls short of a 5.

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 and openWorldHint, so the safety profile is covered. The description adds non-obvious behavior beyond that: TerraVue has no listing inventory, cannot discover ZIPs on its own, the ranking covers exactly what was passed, and it returns the correct city name per ZIP. These are real behavioral constraints, not restated annotations.

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 action and signal list, then a second paragraph for usage. Every sentence earns its place, though the no-listing-inventory caveat is somewhat verbose and overlaps with the schema's addresses description.

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 carries the return-value burden and does so by stating it returns ranked signals plus the correct city name per ZIP. It is largely complete for a two-parameter read tool, though it could say more about ranking direction or output shape.

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 description coverage is 100%, so both parameters (addresses, bedrooms) are already documented, including the 2-12 range and the bedroom-to-rent-estimate link. The description restates the range and the ZIP-discovery caveat but adds no new syntax or format meaning, so the baseline 3 applies.

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 (analyze and RANK) and resource (2-12 ZIPs or addresses side by side) and enumerates the exact signals computed (appreciation forecast, school rating, walkability, education level, water quality). The multi-location scope implicitly but clearly separates it from single-location siblings like analyze_address and affordability.

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 an explicit trigger ('Use for "which areas have the best appreciation / schools / upside"') and a clear operational constraint (pass a metro's ZIPs explicitly because TerraVue cannot discover ZIPs). It stops short of naming an alternative sibling or stating when not to use it, so it is clear context without exclusions.

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 show readOnlyHint=false and idempotentHint=false, consistent with a write that appends a new request each time — no contradiction. The description adds genuine behavioral context beyond annotations: the PII prohibition ('no names, emails, or other personal details') and the user-facing confirmation step. It does not discuss deduplication or what happens to the captured request downstream, so it stops short of 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?

Front-loaded with the purpose, then the trigger, then the constraint, then the follow-up action. Efficient prose, though the enumerated category list is duplicated verbatim in the schema and could be trimmed.

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 simple two-parameter intake tool with no output schema, the description covers the trigger, the scoping constraint, the privacy rule, and the required user-facing message. Nothing an agent needs 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 description coverage is 100%, so both `category` and `description` are already documented in the schema. The description largely echoes that content (the category list and the PII rule appear in both places), adding little new parameter meaning beyond the schema.

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: record an unanswerable question so the capability can be built. An agent can immediately distinguish this fallback/escalation tool from siblings like affordability, buy_vs_rent, and analyze_address, which are actual analysis tools.

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 an explicit trigger — 'Call this whenever a user asks for something outside the current tools' coverage' — and enumerates concrete gap categories (rental metrics, Airbnb modeling, valuations, move-vs-stay, non-US). It also specifies the required follow-up action ('tell the user their request was captured'), removing ambiguity about post-call behavior.

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