Analyze any US home: buy vs rent Monte Carlo, affordability, and ZIP-level appreciation data.
Scored across 6 tools
The tools are mostly distinct: affordability (can I afford this home?), affordable_price (what price can I afford?), analyze_address (area data), buy_vs_rent (buy vs rent decision), compare_areas (rank areas), request_capability (feedback). The only slight overlap is affordability vs affordable_price, but they are clearly described as reverse operations.
Tool names are mostly consistent verb_noun style: affordability, affordable_price, analyze_address, buy_vs_rent, compare_areas, request_capability. 'affordability' and 'affordable_price' are similar but not identical; the pattern is generally clear and predictable.
6 tools is well-scoped for a real-estate analysis server. Each tool covers a distinct user question: affordability, price ceiling, area analysis, buy-vs-rent, area comparison, and capability requests.
The core domain (home affordability, area analysis, buy-vs-rent, comparison) is well covered. Minor gaps: no tool for rental income/landlord analysis, no valuation tool, no move-vs-stay — but request_capability explicitly captures those as future capabilities, and the core workflows are complete.
Can this buyer afford this home? Returns the monthly PITI payment, front-end and back-end debt-to-income ratios (what a lender qualifies on), the income needed at a 28% front-end ratio, estimated after-tax money left over each month, the cash cushion left after closing, and a plain Comfortable / Qualifiable-tight / Stretch verdict.
monthly_debts = recurring debt obligations a lender counts (car, student loan, minimum
credit-card) — NOT living costs; this feeds DTI. monthly_expenses = living costs (food,
utilities, childcare) used ONLY for the 'left over each month' life check, never DTI.
Pass `address` to ground property tax + insurance in the ZIP's real rates. Pass
`liquid_savings` to get the post-closing cash cushion (months of payment covered).
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | ||
| fixed_rate | No | ||
| home_price | Yes | ||
| hoa_monthly | No | ||
| annual_income | Yes | ||
| monthly_debts | No | ||
| insurance_rate | No | ||
| liquid_savings | No | ||
| down_payment_pct | No | ||
| monthly_expenses | No | ||
| marginal_tax_rate | No | ||
| property_tax_rate | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, it clarifies the DTI-relevant vs living-cost distinction, explains that monthly_expenses is used only for the leftover-life check, and describes how address affects property tax and insurance estimates. This adds real behavioral context beyond the 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?
The description is front-loaded with the core question and output list, then organizes parameter semantics and optional inputs into short, purposeful sentences. No sentence is superfluous.
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 enumerates return values and key calculation inputs clearly, including the verdict scale. It is mostly complete for invocation, though some edge behavior (e.g., what happens when address and rate parameters are both omitted) is left implicit.
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?
It thoroughly explains monthly_debts and monthly_expenses and addresses the optional address and liquid_savings behavior. However, schema description coverage is 0% across 12 parameters, and several parameters such as marginal_tax_rate, fixed_rate, insurance_rate, and property_tax_rate are left to be inferred from their names/defaults.
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 targeted question and lists a concrete set of outputs (monthly PITI, front/back DTI, income needed, after-tax leftover, cash cushion, verdict). It is specific about the resource and calculation, though it does not explicitly distinguish itself from the sibling 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?
The first sentence frames the use case as determining whether a buyer can afford a home, and the description gives conditional parameter guidance ('Pass address to ground property tax + insurance... Pass liquid_savings to get the post-closing cash cushion'). It does not name alternatives or exclusions, so it stops 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.
What's the most this buyer can afford? The reverse of affordability — 'what price
can I afford?' instead of 'can I afford this specific home?'. Solves for the maximum
home price under standard lender limits: a front-end DTI cap (default 28% = housing /
gross income) and a back-end cap (default 36% = housing + other debts / gross income).
If liquid_savings is given, also caps by the cash available for down payment + closing
and reports which limit binds. Returns the affordable price, the PITI and DTIs at that
price, and the cash to close. Pass address to ground property tax + insurance in the
ZIP's real rates.
This is a lender-limit ceiling, not a comfort recommendation — feed the result into
`affordability` (or buy_vs_rent) to check monthly slack and whether buying pencils.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | ||
| fixed_rate | No | ||
| hoa_monthly | No | ||
| annual_income | Yes | ||
| monthly_debts | No | ||
| insurance_rate | No | ||
| liquid_savings | No | ||
| back_end_dti_pct | No | ||
| down_payment_pct | No | ||
| front_end_dti_pct | No | ||
| property_tax_rate | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint and openWorldHint, so the description carries the behavioral burden. It discloses the lender-limit ceiling logic, the conditional cash cap when `liquid_savings` is provided, the reporting of which limit binds, and the optional use of `address` to ground property tax and insurance in real rates. It also explicitly warns that this is not a comfort recommendation, preventing the agent from overstating the result.
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?
The description is front-loaded with the core question and then moves logically from formula to conditional behavior to outputs to the address option. The second paragraph is a single high-value caveat and routing note. Every sentence contributes information, with no filler or repetition.
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?
Even with 11 parameters and no output schema, the description tells the agent what the tool returns: affordable price, PITI, DTIs, and cash to close. It explains when the liquid-savings constraint binds, how `address` affects tax/insurance inputs, and how the result should be used with sibling tools. This is enough for an agent to select and invoke the tool 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 0%, so the description must compensate, and it does for the core parameters: annual income via gross income, front-end and back-end DTI caps with defaults, `liquid_savings`, and `address`. It does not explicitly define every optional parameter such as `fixed_rate`, `hoa_monthly`, `insurance_rate`, or `property_tax_rate`, though their names, defaults, and the DTI/PITI context make their roles reasonably inferable.
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 clear question and explicitly frames the tool as the reverse of `affordability`: solving for the maximum price instead of checking whether a specific home is affordable. It names the exact computation—maximum home price under front-end and back-end DTI caps—and clearly distinguishes this tool from its siblings.
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 explicitly tells the agent when to use this tool versus `affordability`: the question is 'what price can I afford?' rather than 'can I afford this specific home?'. It also gives follow-up guidance, directing the agent to feed the result into `affordability` or `buy_vs_rent` to check monthly slack, which provides clear routing and exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a US address (or bare 5-digit ZIP): ZIP-level home-price appreciation forecast (FHFA data back to 1975), estimated market rent, and neighborhood signals (schools, walkability, water quality, grocery/dining/outdoors proximity).
For a full street address this also returns sub-ZIP `nbhd*` fields describing the
specific census tract - how its prices, incomes and build era compare to the rest of
the ZIP. That is POSITION, not a neighborhood forecast; see _units.
property_type: sfr | condo | townhome | multi
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | ||
| bedrooms | No | ||
| property_type | No | sfr |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds value by clarifying the nature of the nbhd* fields (POSITION not forecast) and referencing _units for more details. It also mentions the data source (FHFA back to 1975), which is extra context beyond the read-only annotation. No contradiction with 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?
The description is reasonably concise and front-loaded with the main purpose. The first sentence states the core function, the second adds clarifying nuance about nbhd* fields, and the third lists the property_type enum. It could be slightly tighter, but each sentence earns its place without redundancy.
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?
Given no output schema, the description outlines major outputs (forecast, rent, neighborhood signals) and clarifies the nbhd* fields' meaning. However, it omits how bedrooms influences results, what 'estimated market rent' means precisely, and does not mention any error cases or rate limits. For a read-only tool, it is adequate but not fully complete.
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 0%, so the description must compensate. It provides the property_type enum (sfr | condo | townhome | multi) and clarifies address can be a bare 5-digit ZIP. However, it gives no guidance on the bedrooms parameter's effect or expected format, leaving a gap for the agent. The description partially addresses parameter semantics but not sufficiently given zero schema coverage.
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 clearly states the tool looks up a US address or ZIP and returns specific outputs: home-price appreciation forecast, estimated market rent, and neighborhood signals. It uses a specific verb ('Look up') and resource, and distinguishes itself from siblings by listing its unique outputs (FHFA data, rent, neighborhood signals) that are not covered by the sibling tools like affordability or buy_vs_rent.
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 usage context by differentiating between bare ZIP and full street address, explaining that full addresses return additional nbhd* fields. It also clarifies that these fields are positional, not forecasts, which helps the agent avoid misinterpretation. However, it does not explicitly state when to prefer this tool over alternatives like compare_areas, though the unique output set implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Should someone buy this home or keep renting? Runs the TerraVue engine: a deterministic 30-year simulation plus a 500-scenario Monte Carlo over correlated market paths. Returns the probability buying wins, the breakeven hold period, and net-worth outcomes.
monthly_rent = what the person would pay to rent THE SAME HOME to live in — an
owner-occupant buy-vs-rent decision, NOT rental income they'd collect as a landlord
(this tool does not model rental cash flow; that lens lives on terravue.app). A rent
far out of line with home_price is almost certainly a misunderstanding — confirm it
before trusting the verdict. If `address` is given, the ZIP's real appreciation forecast
and regional tax/insurance defaults are used (explicit parameters still win).
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | ||
| fixed_rate | No | ||
| home_price | Yes | ||
| hoa_monthly | No | ||
| monthly_rent | Yes | ||
| analysis_years | No | ||
| down_payment_pct | No | ||
| property_tax_rate | No | ||
| home_appreciation_rate | No | ||
| investment_return_rate | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description reveals the simulation method (30-year deterministic plus 500-scenario Monte Carlo), the returned decision metrics, and the data-source behavior when address is provided. It also flags a realistic failure mode with monthly_rent, giving the agent useful trust-calibration context.
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?
The description is dense but not wasteful: a short question and method summary up front, followed by two high-value caveats and an explicit precedence rule. Every sentence contributes to correct tool selection or invocation, and the structure front-loads the core question.
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?
Given 10 parameters and no output schema, the description covers the decision type, method, main outputs, the most common input misunderstanding, and address-related behavior. It does not specify output units/conventions such as whether probability is a 0–1 fraction or percentage, but the defaults and parameter names fill most remaining gaps.
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 0%, so the description must carry the parameter-semantics burden. It does this well for the most critical parameter, monthly_rent, explaining that it is rent for the same home, not landlord income, and adds caution about its relationship to home_price. It also clarifies address's effect and precedence, though the other eight parameters are left to their titles and defaults.
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 being modeled, then names the engine and the concrete outputs (probability buying wins, breakeven hold period, net-worth outcomes). It also disambiguates the owner-occupant buy-vs-rent case from landlord rental cash flow, making the tool's purpose unambiguous and distinct from the sibling real-estate 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?
It gives clear operational guidance: monthly_rent must be the rent for the same home, this is not a landlord cash-flow model, and a rent far out of line with home_price should be confirmed before trusting the verdict. It also explains when address-based ZIP data is used and that explicit parameters take precedence. It does not explicitly route among sibling tools, which keeps it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze and RANK 2-12 ZIPs or addresses side by side on the signals TerraVue has: home-price appreciation forecast (and how each compares to the national average), school rating, walkability, education level, and water quality. Returns the correct city name per ZIP, so locations are never guessed or mislabeled.
Use for "which areas have the best appreciation / schools / upside." TerraVue has no
listing inventory and cannot discover ZIPs on its own — to scan a metro, pass that
metro's ZIP codes (the ranking then covers exactly what you passed).
| Name | Required | Description | Default |
|---|---|---|---|
| bedrooms | No | ||
| addresses | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only and open-world; the description adds meaningful behavior: no listing inventory, no autonomous ZIP discovery, ranking coverage limited to passed ZIPs, and a guarantee of correct city names. No contradiction with annotations exists.
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?
The description is front-loaded with the core action and uses compact phrasing throughout. Every sentence contributes either the signal list, a use case, or a necessary limitation; there is no filler or redundancy.
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?
Despite no output schema, it conveys what comes back (ranking and correct city names) and covers input constraints and limitations well. The main gaps are the unexplained 'bedrooms' parameter and the absence of explicit alternatives, so it is not fully complete.
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 0%, and the description compensates for the required addresses parameter by adding constraints like 2-12 inputs and 'pass that metro's ZIP codes.' However, the optional 'bedrooms' parameter is never explained, leaving a notable semantic gap for a call parameter.
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?
Description clearly states the action ('Analyze and RANK 2-12 ZIPs or addresses side by side') and enumerates the concrete signals compared. It also distinguishes the tool from single-address/listings tools by noting TerraVue has no listing inventory and cannot discover ZIPs on its own.
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 provides a use-case ('which areas have the best appreciation / schools / upside') and instructs the caller to pass metro ZIP codes since the tool cannot discover them. It does not explicitly name sibling tools or state when to prefer alternatives like analyze_address or affordability, so it stops 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.
Record a question TerraVue could not answer, so it can be built. Call this whenever
a user asks for something outside the current tools' coverage (rental metrics, Airbnb
modeling, valuations, move-vs-stay, non-US, anything else), then tell the user their
request was captured. Keep description to the capability needed — no names, emails,
or other personal details.
category: rental_metrics | str_airbnb | valuation | move_vs_stay | data_coverage | other
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | other | |
| description | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description carries the burden of disclosing behavior. It adds context: the tool records a question, requires notifying the user, and enforces a privacy constraint on the description field. This goes beyond what annotations convey, providing meaningful operational details.
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?
The description is front-loaded with purpose, then usage, then privacy, then category list. It's efficient with no redundancy, though the category list could be considered slightly repetitive with the schema's default, but it adds the enum values not present in the schema. Structure is clear and scannable.
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 logging tool with no output schema, the description covers the essential aspects: purpose, when to use, parameter semantics, and privacy. It doesn't discuss return values or errors, but these are likely trivial for this tool. The distinctiveness from siblings is established, making it complete enough for correct invocation.
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 0%, so the description must explain both parameters. It does: the `description` parameter is defined as the capability needed, with a privacy rule, and the `category` parameter lists its valid values (rental_metrics, str_airbnb, valuation, move_vs_stay, data_coverage, other). This fully compensates for the missing schema descriptions.
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 clearly states the verb 'Record a question' and the resource 'TerraVue could not answer', defining its exact purpose. It explicitly distinguishes from sibling analysis tools by framing it as a logging tool for unmet requests, making its role unambiguous.
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 explicit 'when to use' guidance: 'Call this whenever a user asks for something outside the current tools' coverage', listing concrete examples. It also instructs the agent to tell the user the request was captured. It doesn't state exclusions or alternatives, but the context implies siblings handle covered cases, so guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
affordabilityaffordable_priceanalyze_addressbuy_vs_rentcompare_areasrequest_capabilityU.S. real-estate data: property records, AVM value + rent estimates, sale/rental listings.
US real estate data: home prices, rents, and market trends
Search real-estate deals, rank top areas, run rental/BRRRR/flip analysis, pull sold comps.
Cited, receipt-backed US home-buying data & calculators — education-only, every number sourced.
Add one secure layer between your agents and this server.
