US Mortgage Calculator

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

Annotations already disclose read-only, idempotent, non-destructive behavior. The description adds valuable context by stating the use of 28/36 ratios and explaining how the binding constraint translates into actionable advice, such as clearing debt affecting only back-end-ratio-limited buyers.

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 two sentences long, with the first sentence stating purpose and method, and the second explaining the unique binding-ratio output. Every sentence earns its place, and the structure is front-loaded.

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?

No output schema exists, so the description must convey return behavior. It explains the binding-ratio report and its practical interpretation, which is sufficient for an 11-parameter tool with required parameters clearly still covered by the schema. It could be more explicit about the output structure, but the core information is present.

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% for all 11 parameters with detailed descriptions, so the tool description does not need to add parameter-level detail. It only groups three key inputs (income, debt, down payment) without enriching semantics beyond the schema, hence the baseline score of 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?

The description clearly states the tool computes the maximum affordable home price from income, existing debt payments, and down payment, and uniquely highlights that it reports which ratio is binding, differentiating it from siblings like calculate_mortgage or calculate_rent_vs_buy.

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 this tool (affordability calculation) and explains the actionable meaning of the binding ratio, but it does not explicitly name alternative tools or exclusion scenarios, lacking the 'when-not-to-use' guidance needed for a top score.

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?

The description adds useful behavior context beyond the read-only/idempotent annotations, such as the split between principal and interest, the falling balance, and the extra principal payoff feature. It doesn't overpromise or contradict the safe-read nature of the tool.

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 three concise sentences, front-loaded with the primary purpose, and every sentence adds unique value. No fluff or repetition of schema details.

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 reasonably explains what the user will get: a payment breakdown, principal/interest split, and balance. It also mentions the extra principal payoff, covering a key feature. It could mention more about the return structure, but for a calculator tool this is adequate.

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 baseline is 3. The description adds extra meaning by explaining the 'granularity' parameter ('monthly' vs 'yearly') and the effect of extra principal, which goes beyond just listing parameter names.

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 what the tool does: it provides a payment-by-payment breakdown of a loan, showing the split between principal and interest and the falling balance. It distinguishes itself from sibling tools by focusing on the amortization schedule specifically, not just mortgage calculation or 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?

The description provides clear context for when to use each granularity ('monthly' for detail, 'yearly' for overview), but it does not explicitly mention alternatives or when not to use this tool. It is clear enough that this is for amortization schedules, but lacks explicit exclusions or references to sibling tools.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by detailing what the calculation includes (taxes, insurance, HOA, PMI) and that it returns lifetime totals and payoff timing. No contradictions with annotations are present.

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 only two sentences long, yet it conveys the full scope, an important usage note about state names, and a concrete example. Every sentence earns its place without any fluff or repetition of schema details.

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, complete schema coverage, and no output schema, the description does a good job of summarizing the tool's coverage. It mentions key return elements ('lifetime totals and payoff timing') and one usage pattern. However, it doesn't clarify the mutual exclusivity between state and propertyTaxRatePercent, though the schema does. This is a minor gap in an otherwise complete description.

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%, meaning every parameter already has a detailed explanation. The tool description does not add meaning beyond the schema; it only reiterates that passing a state uses that state's average property tax rate, which the schema already states. With high schema coverage, a baseline of 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 clearly states the tool's purpose: 'Full monthly housing cost for a US mortgage: principal and interest, property tax, homeowners insurance, mortgage insurance and HOA dues, plus lifetime totals and payoff timing.' It uses a specific verb (calculate), a specific resource (mortgage payment), and defines the exact scope. The inclusion of an example ('what would my payment be on a $400,000 house') further anchors the purpose and distinguishes it from sibling calculators.

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 a clear use case with the example 'what would my payment be on a $400,000 house', telling the agent when to invoke it. However, it does not explicitly name alternative sibling tools (e.g., calculate_amortization, calculate_pmi) or state when not to use this tool, so it falls short of full exclusionary guidance.

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?

The description goes well beyond the annotations by detailing specific behavioural traits: conventional PMI cancels at 80% and 78% LTV, FHA has a 1.75% upfront premium and MIP that may end after 11 years, VA funding fee is tiered by down payment and prior use, and waivers exist. This gives the agent a thorough understanding of the tool's scope and internal logic, and it aligns with the read-only and idempotent hints.

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 well-structured and front-loaded: a leading summary ('Mortgage insurance for any US loan programme, including the upfront charges most calculators omit') followed by four succinct programme-specific clauses. Every sentence conveys unique, necessary information 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 the tool's complexity (9 parameters, 4 loan types) and the absence of an output schema, the description comprehensively covers the key calculations and caveats for each programme. It also notes that it includes upfront charges typically omitted, giving the agent a complete picture of what to expect.

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?

With 100% schema description coverage, the baseline is 3. The description adds program-specific context that enriches parameter understanding, such as 'VA: the funding fee, tiered by down payment and prior use, and waivers,' which directly maps to downPaymentPercent, vaSubsequentUse, and vaExemptFromFundingFee. This extra context elevates the score above baseline.

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 specifies that the tool calculates mortgage insurance for any US loan programme and enumerates the exact charges for each type: conventional PMI with cancellation points, FHA upfront MIP, VA funding fee, and USDA fees. This not only states the purpose with a specific verb and resource but also distinguishes it from sibling calculators like calculate_mortgage or calculate_amortization by focusing exclusively on insurance costs.

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: whenever mortgage insurance or related upfront fees for conventional, FHA, VA, or USDA loans need to be calculated. However, it does not explicitly state exclusions or direct users to alternative tools for non-insurance calculations, so it stops short of a perfect score.

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, and destructiveHint, so the bar is lower. The description adds behavioral context by stating the tool returns annual and monthly tax amounts, a national rank, and a comparison to the national average, and it discloses the limitation of using average effective rates.

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 two sentences that front-load the core function and then add output details plus an alternative pointer without any filler. Every clause is informative and earns its place.

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 compensates by naming what is returned (annual/monthly totals, state rank, comparison to national average). It also covers an alternative for deeper mechanics, making it self-sufficient for a simple read-only calculator with good annotations.

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%, with clear definitions for state ('Full US state name') and homePrice ('Home value in US dollars'). The description mentions 'using a state's average effective rate' but adds no parameter-level details beyond the schema, 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?

The description opens with 'Annual and monthly property tax for a home, using a state's average effective rate,' clearly specifying the verb, resource, and scope. It also mentions additional outputs (national rank, comparison to average) that differentiate it from sibling calculators like calculate_mortgage or estimate_closing_costs.

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 directs users who need the mechanics behind the number—assessment basis, caps, exemptions, appeal deadlines—to use get_state_mortgage_rules, naming an alternative. This clearly implies when to use this tool (quick estimate using average effective rates) and when not to.

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 destructiveHint=false, so the agent knows this is a safe read operation. The description adds meaningful behavioral context: break-even analysis, monthly savings, and the warning about term reset making a lower payment cost more overall. This goes beyond the annotation baseline.

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 two sentences, front-loaded with the main question ('Whether refinancing is worth it') and then adds a valuable nuance about lifetime interest. Every sentence earns its place with no fluff 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?

With no output schema, the description explains all key outputs (new payment, monthly saving, break-even months, lifetime interest) and the decision context. Optional parameters like financeClosingCosts and newTermYears are not mentioned explicitly, but the schema covers them. The description is complete enough for a calculator tool.

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% with descriptions for all 7 parameters, so the baseline is 3. The tool description does not add additional parameter-level semantics beyond the schema; it only mentions 'closing costs' and 'term reset' in a general sense, which does not exceed what the schema already provides.

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 that the tool evaluates whether refinancing is worth it, listing specific outputs: new payment, monthly savings, break-even months, and lifetime interest comparison. It distinguishes from sibling tools like calculate_mortgage and compare_loans by focusing specifically on refinance decisions.

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 implies usage context (when considering refinancing) and highlights the lifetime interest comparison as a key differentiator that catches a common trap. It does not explicitly name alternative tools or state when not to use, but the context is clear enough for an AI agent to select it correctly.

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 the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it returns the crossover year and explicitly highlights that the result is highly sensitive to appreciation and investment-return assumptions, which are returned alongside the result. This goes beyond what annotations provide.

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 the core concept, and every clause contributes meaning. No redundancy or filler.

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 15 parameters and no output schema, the description clearly explains the comparison basis, the key output (crossover year), and the sensitivity assumptions returned. This is sufficient 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 covers 100% of parameters, so the baseline is 3. The description adds extra semantic value by identifying which parameters drive the net-wealth model (equity, appreciation, maintenance, selling costs, renter's return) and flagging high-sensitivity assumptions, helping the agent understand which inputs matter most.

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 compares renting versus buying based on net wealth rather than monthly payment, and specifically names the factors considered (equity, appreciation, maintenance, selling costs, renter's return) and the return value (year buying overtakes renting). This clearly distinguishes it from sibling tools like calculate_mortgage or compare_loans.

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 makes clear the comparison is on net wealth rather than monthly payment, which implies a decision context, but it does not explicitly state when to use this tool versus alternatives or list exclusions. The context is clear enough for an agent to select it for rent-vs-buy analyses, but explicit 'use this when...' guidance is missing.

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, idempotentHint=true, and destructiveHint=false, so the tool is clearly safe. The description adds valuable behavioral context: it reports the cheapest by monthly payment and by lifetime cost separately because they often differ, which is a non-obvious output behavior.

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 two sentences: the first states the core function and output, the second lists use-case examples. It is front-loaded with the verb 'compares' and contains no redundant or filler 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?

With a rich input schema and clear annotations, the description explains the tool's purpose, output highlights (two separate cheapest categories), and common use cases. There is no output schema, but the description states what the report contains. It does not detail edge cases or calculation assumptions, but these are largely covered by the schema.

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 parameter 'scenarios' is fully documented in the input schema. The description's mention of 'two to five' scenarios repeats schema constraints (minItems=2, maxItems=5) without adding new semantic meaning. Examples like '15-year versus 30-year' provide mild usage context but do not go 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?

The description clearly states the tool compares two to five loan scenarios and reports the cheapest by monthly payment and lifetime cost separately. This distinguishes it from sibling tools that calculate individual metrics for a single scenario, and concrete examples (15-year vs 30-year, FHA vs conventional) further clarify its purpose.

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 lists when to use it: 15-year versus 30-year, FHA versus conventional, competing lender quotes, and with/without discount points. It implies single-scenario calculations should go to sibling tools like calculate_mortgage, but it does not explicitly name alternatives or state when not to use it.

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 idempotentHint=true, so the agent knows it is a safe, non-mutating calculation. The description adds valuable context beyond annotations by explaining that it marks which items are shoppable vs fixed by the county, and that it selectively applies FHA/VA/USDA fees. This provides useful behavioral nuance about the tool's logic without contradicting 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 two sentences with no wasted words. The first sentence front-loads the core purpose and output, while the second adds two important behavioral details (shopping markers and loan-type fees). Every phrase earns its place, and the structure is easy to scan.

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 tool has 10 parameters, but the schema covers all of them with descriptions, so the description need not repeat parameter details. It explains the output (line items, total cash needed, shopping markers) and the loan-type fee logic, which is sufficient given the absence of an output schema. It does not address edge cases like VA fee exemptions, but defaults in the schema mitigate that gap.

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%, establishing a baseline of 3. The description adds meaning by tying cost categories (lender fees, title, appraisal, transfer taxes, prepaid escrow) to specific parameters like escrowMonths and transferTaxPercent, and by mentioning loan-type-specific fees that enrich the 'loanType' parameter. This contextual grouping helps the agent understand how inputs relate to the overall calculation.

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 it produces line-by-line buyer closing costs and total cash needed at the table, including the down payment. This distinguishes it from sibling tools that focus on monthly payments or single cost components. The verb 'Itemise' in the title is reinforced by the description's detailed enumeration of cost categories.

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 by specifying the exact output (closing cost breakdown, total cash needed) and the types of costs included, implying when to use this tool. However, it does not explicitly name alternatives or state when not to use it, such as 'use calculate_mortgage for monthly payment estimates.' This is a minor gap given the many sibling calculation tools.

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, and destructiveHint, covering safety. The description adds valuable behavioral context about the tool's scope (e.g., county variation, link to tax authority) without contradicting annotations. It doesn't mention error handling or data limitations, but given the annotation coverage, this is sufficient.

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 a single informative sentence followed by a usage guideline. It packs many specific content details without being overly verbose. The structure is front-loaded with the core purpose and then lists topics, making it efficient.

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 single-parameter tool with no output schema, the description thoroughly explains what the tool returns (a comprehensive list of tax rule components) and when to use it. The only gap is that it doesn't specify the output format, but the enumerated content list compensates for the missing output schema.

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% for the single 'state' parameter, so the schema already provides meaning. The tool description does not add additional parameter semantics, though it implies the state is the subject. The schema's odd reference to propertyTaxRatePercent does not affect this dimension since the description avoids repeating it.

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 retrieves a state's property tax mechanics, listing specific content areas such as assessed value derivation, exemptions, deadlines, and appeals. It also explicitly differentiates from sibling tools by noting it addresses 'mechanics or deadlines rather than a dollar amount,' making its purpose 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 explicitly states when to use the tool: 'when the question is about mechanics or deadlines rather than a dollar amount.' This provides clear guidance and implicitly names the alternative (calculate_property_tax) for dollar-amount questions, fulfilling the when/when-not requirement.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds beyond this by explaining the sortability feature (which directly answers 'which states have the highest property taxes') and confirming the complete coverage of all 50 states, which is useful behavioral 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 three sentences, front-loaded with the core purpose, then a practical use case, then a cross-tool hint. Every sentence earns its place with no redundancy or filler.

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 having no output schema, the description lists the returned data fields (tax rate, median home value, annual tax). Combined with the 100% parameter schema coverage and the annotations providing the safety profile, the description provides enough context for the 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 100%, so the parameters (limit, order, sortBy) are already well documented. The description adds little beyond noting sortability, which indirectly relates to sortBy/order but does not materially enhance parameter understanding. Baseline of 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 explicitly states the tool lists every US state with average effective property tax rate, median home value, and estimated annual tax. It also distinguishes itself from the sibling calculator tools by positioning this as a data listing tool and mentioning that it provides valid state names for other 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?

The description gives clear context: it is the tool to call for discovering valid state names for other tools, and it directly answers which states have the highest property taxes. It does not explicitly list when-not-to-use scenarios or alternative tools, but the sibling tools are all calculators, implying this is the dedicated listing tool.

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