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

The description goes well beyond the readOnly/idempotent annotations by explaining per-row status values, ordered output, per-row error isolation, the hard deadline with pending rows, omitted description by default, and the lot_size_acres null behavior. This is rich, accurate 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 dense but every sentence adds value: core capability, ordering/error behavior, field inheritance, optional description, deadline semantics, and sibling comparison. It is front-loaded with the primary purpose and not padded.

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 fully covers the return shape: per-row records, status values, included fields, ordering, error handling, and pending behavior. It also points to homes_get_property for the per-row record shape, giving an agent everything needed to invoke 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 the schema carries the parameter definitions. The description still adds practical semantics for include_description (raw marketing prose, default false) and clarifies that urls accepts paths from search results. It does not add much beyond the schema for view, but the schema already documents it fully.

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 action and resource: fetch up to 200 homes.com properties in one call and return structured records. It clearly differentiates from homes_get_property by framing itself as the bulk alternative and explicitly saying to use it instead of looping.

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 explicit when-to-use guidance: use this instead of looping homes_get_property when you just want the records. It also mentions the per-call limit and per-row error behavior, which help the agent decide between bulk and single-fetch approaches.

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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds that it is pure local math with no network dependency and describes the output (max home price, binding constraint, PITI breakdown). No contradictions.

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 paragraph of three sentences, front-loaded with purpose. Nearly every sentence adds value, but a more structured listing of inputs and outputs would improve clarity.

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, no output schema, and sparse annotations, the description covers inputs and outputs but lacks details on defaults, edge cases, or precise DTI ratio specification (just 'standard 28/36'). Adequate but incomplete.

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%. The description lists several input parameters but does not explain their meaning or constraints (e.g., what front_end_dti and back_end_dti represent). It adds some context but insufficient for 10 parameters.

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 solves for maximum affordable home price using standard 28/36 DTI rule, lists inputs and outputs, and distinguishes from siblings by noting identical math to zillow-mcp and redfin-mcp.

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 for affordability calculation but does not explicitly state when to use it over the sibling tool homes_calculate_mortgage or what alternatives exist within the suite. It mentions identical math externally but no internal differentiation.

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?

Beyond the annotations (readOnlyHint, idempotentHint), the description adds key behavioral details: it is local-only, no network call, PMI applies automatically when LTV > 80% and pmi_rate is provided. 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 two sentences long, front-loading the purpose and then succinctly covering parameter details. Every sentence serves a purpose with no wasted words.

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, no output schema, and rich annotations, the description covers key behaviors (no network call, PITI breakdown, parameter alternatives). It could mention return format but 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?

With only 40% schema description coverage, the description compensates by explaining defaults (down_payment_percent defaults to 20%), conditional PMI behavior, and alternative ways to provide property tax. This adds significant 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?

The description clearly states the tool is a 'Local-only mortgage payment calculator' that returns a 'full PITI breakdown', using specific verbs and distinguishing it from the sibling tool 'homes_calculate_affordability' by focusing on detailed mortgage components.

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 guidance on when to use (local calculation, no network call) and parameter alternatives (e.g., 'Provide either down_payment OR down_payment_percent; defaults to 20%'). It lacks an explicit when-not-to-use statement for other scenarios but is clear enough.

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 readOnly/idempotent annotations: it discloses per-row error isolation, concurrent execution, default omission of `description` and `summary`, and the exact behavior of the `view` parameter. This is rich behavioral context that an agent cannot infer from the schema or 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 long but densely informative, with the core purpose front-loaded and behavioral details following logically. The list of returned fields is lengthy but justified because no output schema exists. Slightly more brevity would be possible, but no sentence feels wasted.

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 tool with no output schema, the description supplies the critical return fields, error behavior, concurrency model, default omissions, and opt-in flags. Combined with a fully documented input schema, an agent has everything needed to call this tool correctly and interpret its results.

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 each parameter. The description adds meaningful semantics on top: where to obtain each `url`, why `include_summary` is redundant by default, and that `include_description` controls marketing prose. This exceeds the baseline for fully-covered schemas.

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?

Opens with a specific verb-resource pair: 'Fetch 2 or more homes.com properties and align their facts side-by-side.' This immediately differentiates it from single-property tools like homes_get_property and from search tools, and the rest of the description reinforces the comparison use case.

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 clearly establishes the input source ('pass the `url` field from a homes_search_properties result') and the minimum target count, giving an agent solid context for when to invoke it. It does not explicitly exclude single-property fetches or name an alternative tool, so it stops short of full when/when-not 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 explains internal behavior: 'Accounts for down payment, closing costs, monthly PITI, maintenance (~1%/yr default), appreciation (~3%/yr default), rent growth (~3%/yr default), and the opportunity cost of the down payment (renter invests it at investment_return_rate, default 6%/yr).' It states 'Returns year-by-year cumulative costs, break-even year, and the net difference at horizon' and 'No network — pure local math.' These detail effects beyond annotations (readOnlyHint, idempotentHint) and do not contradict them.

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 concise and well-structured: two paragraphs—first explaining the tool's function and inputs, second providing a critical note about data sourcing. It front-loads the primary purpose and uses clear language. Every sentence adds value, with no repetition of schema fields.

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 is fairly complete: it explains the model, outputs (year-by-year costs, break-even, net difference), and the need for a rent estimate. It could mention the relationship to siblings (e.g., similar to homes_calculate_mortgage but adds rent comparison) and clarify the absence of network dependency (already stated). Still, it covers the essential context for effective tool selection.

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 0% schema description coverage, the description must compensate. It does so by explaining many parameters in context: down payment, closing costs, monthly PITI, maintenance (maintenance_rate), appreciation (appreciation_rate), rent growth (rent_growth_rate), opportunity cost (investment_return_rate). However, not every parameter (e.g., hoa_monthly, insurance_annual) is explicitly named, though they are implied by 'closing costs' and 'PITI'. Overall, it adds substantial 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?

The description clearly states the tool's purpose: 'Project the cumulative cost of buying a home versus renting a comparable place over N years.' It specifies the factors considered (down payment, closing costs, PITI, maintenance, appreciation, rent growth, opportunity cost) and distinguishes from siblings like homes_calculate_mortgage by focusing on the buy-vs-rent comparison. The mention of same math contract as zillow_estimate_rent_vs_buy further aids differentiation.

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 usage guidance: 'NOTE: caller must supply `monthly_rent` — homes.com does not publish rental estimates...' and suggests alternative tools (zillow_get_property, redfin_get_comparable_rentals) for obtaining a rent estimate. It also indicates when not to use (if no rent estimate available) and contextualizes that this is pure local math with no network dependency.

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 indicate read-only, open-world, and idempotent. The description adds substantial behavioral details: three resolution rungs, matching logic, price bound scope, known failure modes, and return format. 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 long but well-structured: purpose first, then mechanism, params, returns, and caveats. Every sentence adds value, though slightly verbose. Front-loaded with core 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?

Given the tool's complexity (multiple rungs, fallback, price bounds), the description covers resolution flow, match confirmation, failure modes, and batch alternatives. No output schema but return format is detailed. Complete for a read-only lookup 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%, so baseline is 3. The description enriches parameters by explaining price_min/max's role only in the fallback, and the optionality of zip. It adds context beyond 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 it resolves a US street address to a canonical homes.com property URL and hash, using a specific verb and resource. It distinguishes from sibling tools like homes_resolve_addresses by noting batch size preference.

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 advises using homes_resolve_addresses for batches of 3 or more addresses, and explains when price bounds are applicable. While not exhaustive on when-not-to-use, it provides clear context for invocation.

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?

Description adds response structure details and cross-MCP normalization beyond annotations. States read-only and safe to call repeatedly, consistent 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?

Five sentences, front-loaded with purpose, efficient in conveying all 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?

Adequately describes response structure and empty series behavior. No output schema, but description covers key aspects for a simple read 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?

Single parameter with 100% schema coverage. Description only restates schema ('full property detail URL'), adding minimal extra 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?

Clearly states it is a combined endpoint replacing two other tools. Specifies return fields and distinguishes from 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?

Explicitly says to pass the full property detail URL and describes behavior when series are empty. Implies preferred over individual history tools but lacks explicit when-not-to-use.

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?

Beyond the annotations (read-only, open-world, idempotent), the description adds important behavioral context: the sold page typically returns only ~40 listings, so the result is a sample-based summary rather than an exhaustive market index. It also discloses the return shape ('{ region, slug, sold_summary, sample_sold }'), which is especially valuable because no output schema is provided. There is no contradiction with the readOnlyHint.

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 compact and front-loaded: it states the core action first, then the required parameter, then the return value, and finally the critical sampling caveat. Every sentence earns its place; there is no redundant filler or vague marketing language.

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 there is no output schema, the description adequately covers what the tool does, what it returns, how to pass the location, and a key behavioral limitation. The annotations cover safety and idempotency, and the schema covers parameter details. An agent has enough information 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 coverage is 100%, so the schema already documents both parameters and the view enum. The description adds value by giving concrete free-text examples for `location` ('Brooklyn, NY', '30311') and clarifying that it is the required input, which helps the agent format the parameter correctly.

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 ('Fetch') plus a concrete resource: recently-sold Homes.com listings for a city/ZIP/neighborhood, then states the derived output: count, median sale price, and average $/sqft. This clearly distinguishes the tool from sibling tools like homes_search_properties or homes_get_property, which serve different lookup needs.

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: use this tool when you need a market summary for a location, and it specifies the input as free-text city/ZIP/neighborhood. It does not explicitly name alternatives or state when not to use it, but the market-report framing is enough to guide tool selection among the 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, openWorldHint, and idempotentHint. The description adds context by stating 'Read-only; safe to call repeatedly' and describing the return format and limitations (no price/beds/baths), which aligns with annotations and adds value beyond them.

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 well-structured paragraph with no fluff. It front-loads the purpose, then covers parameters, return format, limitations, enrichment suggestion, and safety note—all in a concise manner.

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 provides a detailed return format including structure. It covers main use, edge cases (include_rentals, limit), limitations (no price data), and relates to sibling tools. Comprehensive for a 3-param 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%, so baseline is 3. The description adds value by contextualizing each parameter: url is 'the property whose neighborhood to inspect', limit caps count, and include_rentals controls tab inclusion, including default behavior. This elevates the score to 4.

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 scrapes the nearby-links section of a homes.com detail page and returns nearby active listings. It specifies the HTML element and tab behavior, and distinguishes from sibling tools like homes_get_property and homes_search_properties.

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 explains when to use (to get nearby listings) and when not (curated cross-link list, not comparable-sales set). It suggests using homes_get_property to enrich rows and clarifies tab behavior with include_rentals.

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?

Goes well beyond the readOnlyHint/idempotentHint annotations: it discloses the parsing mechanism (Schema.org JSON-LD plus DOM-side sections), the exact derivation rule for lot_size_acres with the "null — never 0" edge case for condos, and that extracted_features is computed server-side so callers needn't parse marketing prose. The candid "this server has no verified record of which Homes.com fields matter" caveat on view=full is notable honesty about system limits. "Read-only; safe to call repeatedly" is consistent with all three 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 long, but every sentence earns its place: the load-bearing instruction (pass the url from a search result) is front-loaded, and the dense return-field list is information rather than padding. The structural weakness is a single run-on paragraph that would benefit from bulleted return fields or sentence breaks, though this is a formatting nit, not bloat.

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 full return-contract burden and mostly meets it: roughly 25 returned fields, the extracted_features sub-fields, the lot_size_acres formula and null behavior, and all opt-in flags mapped to sibling-tool equivalents. The remaining gaps are error semantics for invalid or expired URLs and an explicit note routing photo-only callers to homes_get_property_photos — both minor given how much is covered.

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 five parameters — the baseline is 3. The description adds value above that by linking include_price_history and include_tax_history to the exact sibling output shapes (listing_events, ownership_events, lien_events, events_normalized; tax_history) and by explaining the default-off rationale. The view parameter semantics are reinforced with the field-projection honesty, which goes beyond the schema's own already-strong description.

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 + resource: "Fetch a property's full homes.com record," and pins the input contract to the full property detail URL. The exhaustive return-field enumeration (address, beds/baths, price, lot_size_acres, Matterport tour, schools, etc.) separates it from history-only, tax-only, photos, and search siblings, several of which are named explicitly.

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?

Tells the agent exactly where the input comes from — "e.g. from a homes_search_properties result's url field" — which also disambiguates it from homes_get_by_address. For the optionally inlined data, it names the dedicated siblings (homes_get_property_history, homes_get_tax_history) and states the tradeoff ("Saves a second round trip when you need both"). The view and include_description guidance adds concrete when-to-use context rather than leaving it to inference.

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, openWorldHint, and idempotentHint, so the safety profile is known. The description adds value by detailing the returned data structures (listing_events, ownership_events, lien_events, events_normalized), going beyond annotations. No destructive behavior mentioned, consistent with readOnlyHint.

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 extremely concise, using two sentences to convey deprecation, alternatives, and output structure. No filler, every sentence earns its place. Front-loaded with the most important info.

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 deprecated tool with a single parameter and no output schema, the description is complete: it explains what data is returned and provides migration path. Could optionally mention that it only works with homes.com URLs but that is implied. Slightly more detail about the 'events_normalized' cross-MCP enum might help, but overall 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?

The only parameter 'url' is fully described in the schema (100% coverage). The description does not add additional semantic meaning beyond the schema's 'homes.com property detail URL or path.' Baseline 3 applies as schema covers the parameter; no extra clarification needed.

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 property history (three timelines) for a homes.com property. It immediately identifies the tool as deprecated and specifies the preferred alternatives, making the 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?

Explicitly marks the tool as DEPRECATED and directs users to 'homes_get_history' or 'homes_get_property' with include_price_history, providing clear when-to-use and when-not-to-use guidance. This is ideal for a deprecated tool.

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 openWorldHint, and the description adds significant behavioral context: it scrapes every <img> tag, filters to CDN, is read-only and safe to call repeatedly, and returns a specific structure. No contradictions.

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 concise and well-structured: it opens with the purpose, then explains the scraping rationale, describes the parameter with an example, and details the return type. Every sentence adds value 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?

Despite no output schema, the description fully details the return format. It addresses the single parameter, explains how to obtain the input from a sibling tool, and covers the tool's behavior. Given the low complexity and rich annotations, the description is 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 coverage is 100% for the single 'url' parameter, so the description adds only moderate guidance (e.g., passing the url from homes_search_properties result). The baseline of 3 is appropriate as the schema already documents it fully.

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 gets the 'full photo gallery for a homes.com listing' and explains why it scrapes img tags (JSON-LD only gives one image). The verb 'get' and resource 'property photo gallery' are specific, and the tool is well-distinguished from siblings like homes_search_properties or homes_get_property.

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 explains when to use this tool (when full gallery is needed, since JSON-LD only provides one image) and how to obtain the input url from homes_search_properties. However, it does not explicitly state when not to use it or mention alternatives.

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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds significant behavioral context: it scrapes DOM, fields may be missing as best-effort, and it's safe to call repeatedly. No contradictions 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 concise and well-structured: main action stated first, then return format, then usage notes. Every sentence adds value 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 has no parameters and no output schema, the description fully covers all necessary information: purpose, return shape, edge cases, and linking to sibling tool. Complete for decision-making.

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 input schema has no parameters, so the description does not need to add parameter information. Baseline of 4 for 0-parameter tools is appropriate as the description correctly avoids extraneous detail.

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 the signed-in user's saved/favorited homes from homes.com. It specifies the source URL and return structure, distinguishing it from sibling tools like homes_get_property.

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 advises calling `homes_get_property(url)` per row for canonical records, describes the prerequisite of being signed in, and notes the error when not authenticated. This provides clear guidance on when to use this tool versus alternatives.

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 provide readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral details: URL scraped, return shape, DOM-scraping edge cases for name/filters, and error condition. 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?

The description is concise, well-structured, and front-loaded with the purpose. Every sentence adds value with no 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 zero parameters, good annotations, and no output schema, the description covers the essentials: purpose, prerequisite, return shape, and edge cases. Could optionally mention rate limits or limits on saved searches, but not necessary.

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 tool has zero parameters, so the parameter burden is minimal. The description compensates well by explaining the tool's behavior and return structure without needing param details.

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 the signed-in user's saved searches on homes.com. It uses a specific verb ('get') and resource ('saved searches'), and distinguishes from sibling tools like homes_get_saved_homes.

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 prerequisite that the user must be signed into homes.com in their browser tab, and explains the error if not. Although it does not compare directly to siblings, the context 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.

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

Annotations already indicate readOnly and idempotent. The description adds value by specifying null/empty states, which is beneficial beyond 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?

Two sentences, front-loaded with key actions and edge cases. No unnecessary words.

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 read-only tool with no parameters and annotations, the description explains return values and edge cases. Lacks detail on session object format but sufficient for use.

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?

No parameters, so baseline 4. Description adds no parameter info but none needed.

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 returns all registered sessions and the active_session_id, with edge cases explained. Distinguishes from siblings like homes_register_session and homes_set_active_session.

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 for viewing sessions but lacks explicit when-to-use or when-not-to-use guidance or comparisons with siblings.

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, openWorldHint. The description adds deprecation status, planned removal, and data shape (tax paid, assessed value, land/improvement split). No contradictions.

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 relatively short and front-loaded with DEPRECATED. It conveys deprecation, alternatives, and data shape efficiently, though the deprecation notice takes up significant space.

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 1-param tool with no output schema, the description adequately explains the return data (tax records with fields). It lacks error case info but is otherwise complete given the straightforward nature.

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?

Only one parameter (url) with full schema description coverage. The description does not add additional meaning beyond 'homes.com property detail URL or path' already 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 clearly states the tool returns property tax records (tax paid, assessed value, land/improvement split) but the deprecation notice is primary. It distinguishes from siblings by naming alternatives, but the core function is slightly overshadowed.

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 says to prefer homes_get_history or homes_get_property with include_tax_history, providing clear when-to-use guidance and naming the alternative 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the external round-trip behavior, the exact diagnostic fields returned, and how to interpret failure classes ('bridge never came up', 'extension not connected', 'real www.homes.com-side problem'). It also notes 'Read-only, no auth required,' which adds operational 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 front-loaded with the core behavior, then lists the returned diagnostics in a compact, scannable sequence. Each clause earns its place, and the when-to-use guidance is a single clear 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?

With no parameters and no output schema, the description carries the full burden of explaining what the agent gets back. It names all diagnostic components and the meaning of the hint, making the tool callable without missing information.

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 tool has zero parameters and the input schema is empty, so schema coverage is complete. Per the rubric, 0 params earns a baseline of 4; the description has no parameter semantics to add.

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 states a specific action ('Round-trips a small public www.homes.com URL ... through the fetchproxy bridge') and a concrete deliverable ('returns diagnostics'). It clearly differentiates this healthcheck tool from the property-data sibling tools, which are all about retrieving home information.

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 an explicit trigger: 'Call this when a real tool fails and you want to know which hop broke.' It does not list exclusions or alternative tools, but no sibling serves a similar diagnostic role, so the guidance is sufficient.

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 significant context beyond annotations: it explains idempotent update behavior (re-registering same identity updates instead of duplicate), default session assignment, and mark_active effect. Annotations already indicate idempotentHint=true and readOnlyHint=false, which are consistent. The description could further detail side effects or auth requirements but does not contradict 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 concise—four sentences, front-loaded with the primary action. Every sentence adds essential information: registration/refresh, idempotency, return value, default behavior, and mark_active option. No redundant or wasted words.

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 lack of output schema, the description adequately explains the return value (session_id) and key behavioral aspects. It covers registration, refresh, idempotency, and active session behavior. Minor gaps: error conditions, authentication prerequisites, or effects of auth_expires_at are not addressed, but the core functionality is well-covered.

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 parameters. The description adds extra meaning: it clarifies that re-registering the same account_identity updates the session, and explains the significance of mark_active in making the session active immediately. This enriches parameter understanding beyond the schema's basic 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 tool registers or refreshes an authenticated Homes session, explicitly distinguishing idempotent behavior (updates rather than duplicates) from potential duplication. It differentiates from sibling session tools by explaining the role of 'mark_active' and default session behavior, making its purpose distinct.

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 (registering or refreshing a session) and hints at related functionality (mark_active to set active). However, it does not explicitly exclude alternatives like 'homes_set_active_session' or mention when not to use this tool, leaving some ambiguity for agents.

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 idempotentHint. Description adds detailed behavioral info: fan-out process, matching criteria, per-row outcomes (failure won't fail all), result ordering, and safe-to-call nature. No contradictions.

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?

Well-structured with clear sections: batch size, parameter format, matching process, outcome shape, usage recommendation. Could trim some technical details but overall effective.

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?

Without output schema, the description thoroughly explains the return object structure and fields. References sibling tools and provides usage context. Complete for an AI agent to select and 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 coverage is 100%, but description adds meaning beyond schema: explains matching logic, optional price bounds, and outcome field mapping (property_id vs property_hash).

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 resolves up to 100 street addresses to homes.com property URLs and opaque property hashes. It distinguishes itself from siblings by explicitly comparing to homes_get_by_address and homes_bulk_get.

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?

Provides explicit guidance: 'Use this instead of looping homes_get_by_address for any batch ≥ 3.' Describes fan-out logic and fallbacks. Lacks explicit 'when not to use' but threshold is clear.

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?

Beyond the readOnly/idempotent/openWorld annotations, the description discloses valuable behavioral details: location slugification into homes.com URL routing, JSON-LD parsing, the exact returned listing fields, the known ~40-listing cap, and the truncated/total_estimated response signals. This gives an agent a realistic model of what the tool will actually do.

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 well-structured: main purpose, filters, URL transformation, response contents, and the KNOWN CAP limitation each earn their place. The example route ('Atlanta, GA' + condo + for_sale → /atlanta-ga/condos-for-sale/) is a compact illustration that prevents ambiguity.

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 burden of explaining return values, and it does: address, price, beds/baths, sqft, photo, agent/brokerage, and property URL. It also covers the truncation signal, the cap, and the strategy for enumerating large markets, making the tool fully actionable for an agent.

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?

Parameter schemas cover 100% of parameters, so the baseline is 3. The description adds meaningful context above that by explaining how location gets slugified into URLs, how price_min/price_max can be used to band a busy market under the SSR cap, and what limit's default of 40 means. This is genuine added value rather than schema repetition.

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 ('Search homes.com listings') and clearly scopes the tool to free-text location plus optional property_type, listing_type, and sort filters. This distinguishes it from siblings like homes_get_property or homes_get_by_address, which target individual properties rather than listing searches.

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 operational guidance: it explains the ~40-listing SSR cap, how to detect truncation, and explicitly advises price-banding or sub-area searches for busy markets. However, it does not name sibling alternatives or state when this tool should be preferred over homes_get_nearby_listings or homes_get_market_report, so it stops short of a full 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?

The description explains the side effect: changing default routing for subsequent calls. Annotations indicate idempotent and not read-only, which aligns. It adds context beyond annotations by explaining the override 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, front-loaded with the action, and every sentence adds value. No unnecessary words.

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 tool with one parameter and no output schema, the description is complete. It explains the effect, prerequisite, and interaction with other tools. No 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?

The schema describes the parameter as 'Session id to make active.' The description adds meaning by specifying it must be 'previously returned by homes_register_session', which is not in the schema. Since schema coverage is 100%, the description provides valuable extra context.

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: 'Switch which registered session subsequent tool calls route through by default.' It uses a specific verb 'Switch' and resource 'registered session', and distinguishes from siblings by referencing 'homes_register_session'.

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: pass a session_id from homes_register_session, and notes that explicit session_id parameters override the default. It lacks explicit exclusions but is sufficient for this simple tool.

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