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

Annotations already declare readOnly/idempotent/openWorld, and the description layers on substantial extra behavior: 6-in-flight concurrency cap, retry-once-on-timeout, per-host RPM throttle with burst 20, PerimeterX bot-wall retries with exponential backoff, a hard overall deadline, and per-row error isolation. It also names the failure taxonomy (bot_challenge vs pending vs missing) and the blocked/retry_after_s and pending envelopes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded correctly: purpose, then the sibling alternative, then return shape, then internals. It is dense and somewhat over-stuffed, and the 6-in-flight cap is stated twice ('capped at 6 in flight' then 'fan out bounded to 6 in flight'), plus issue-number citations (#78/#90/#98) are marginal for an agent, but nearly every sentence carries real behavioral information.

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 carries the return-value burden: it specifies the two row shapes, the status/error_kind/retryable fields, and the count/ok/errored/blocked/pending envelope. Combined with annotations covering safety, an agent has everything needed to call and interpret the 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 both urls and zpids are already documented (including maxItems/minItems and mutual exclusivity), which sets the baseline at 3. The description adds meaning beyond the schema by mapping inputs to outputs one-to-one ('one structured row per input id') and clarifying that a single bad id does not fail the batch.

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, and hard scope cap ('Fetch up to 200 Zillow property records in a single call') and explicitly distinguishes itself from the sibling zillow_compare_properties. An agent can route correctly without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-not rule and names the alternative with its own selection condition ('no pivoted side-by-side summary table — for 2-25 listings with a comparison summary use zillow_compare_properties'). It also frames the batch scenario ('all saved homes') that selects this tool, leaving nothing 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 establish readOnly, idempotent, and closed-world behavior, so the bar is lower; the description still adds real value by declaring 'No network — pure local math' and by spelling out the return contents (max price, binding constraint, full PITI breakdown). With no output schema, that return-shape disclosure is genuinely useful. It stops short of 5 because it says nothing about error cases or edge behavior (e.g., zero down payment).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: the core purpose first, then inputs, then outputs, with the local-math note last. Every sentence carries information an agent needs and none is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, no-output-schema tool, the description covers purpose, most inputs, return contents, and the stateless/no-network characteristic. The one real gap is that it does not explain the overridable DTI caps or defaults for the optional cost parameters, which matters for a tool whose whole premise is a debt-ratio rule.

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 60%, so the schema already documents the DTI caps, interest rate format, loan term, and property-tax rate. The description recasts the inputs in plain language ('monthly income, recurring monthly debts (car loans, student loans, etc.), down payment, interest rate, and optional property-tax rate / insurance / HOA / loan term') and clarifies which are optional, which is a modest addition over the schema. It never mentions the tunable front_end_dti/back_end_dti parameters beyond the fixed '28/36' framing, leaving part of the 60%-uncovered surface unaddressed.

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 names a specific verb and outcome: solving for the maximum affordable home price under the 28/36 DTI rule, which is inherently distinct from a payment-calculator sibling like zillow_calculate_mortgage. It is clear and concrete, but it never names or contrasts an alternative tool, so it stops short of the sibling differentiation a 5 requires.

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?

Usage is implied by the framing ('Solve for the maximum home price you can afford'), which tells an agent this is for affordability/budget questions rather than payment math. There is no explicit when-to-use, no when-not-to-use, and no reference to zillow_calculate_mortgage or zillow_estimate_rent_vs_buy, so routing must be inferred.

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 readOnly, idempotent, and openWorld=false, so the safety profile is covered. The description adds genuinely new behavior: the returned PITI components, total interest over loan life, and the conditional PMI rule (LTV > 80%). It does not discuss failure/validation behavior for bad inputs, keeping it at 4.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose and return value before usage notes and parameter rules; each sentence carries distinct information with no filler. Slightly dense in the final sentence but not wasteful.

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 steps in to describe the return (PITI breakdown plus lifetime interest), and it resolves the key input ambiguities. It is essentially complete for invocation, missing only explicit sibling routing.

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 only 40% across 10 parameters, so the description must compensate, and it does: it clarifies that down_payment and down_payment_percent are alternatives with a 20% default, and that property tax can be supplied as an annual figure or a rate. It leaves several parameters (hoa_monthly, insurance_annual, loan_term_years default) to the schema, so not fully compensating.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("mortgage payment calculator") plus the distinctive attribute "Local-only", so the agent immediately knows it is a deterministic computation rather than a network fetch. It does not explicitly differentiate itself from the related sibling zillow_calculate_affordability, keeping it just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear use context — "safe to use for scenario comparison without burning a fetch" — which tells the agent when this local tool is preferable to a network call. It never names the alternative calculator siblings (e.g. affordability) or states exclusions, so it stops at clear context rather than explicit when/when-not routing.

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

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

Annotations declare read-only/idempotent/open-world, and the description adds substantial behavior beyond that: concurrency capped at 6 in flight, retry-once-on-timeout, shared throttling, per-row error capture (one bad zpid won't fail the call), bot-wall handling surfaced as error_kind 'bot_challenge' with {blocked, retry_after_s}, and an overall deadline yielding error_kind 'pending'. This is rich operational context consistent with the annotations (no contradiction).

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 critical routing distinction is front-loaded and bolded, and most sentences carry behavioral payload. It is long though, and the internal churn asides ('Issue #79 raised this cap from 8 to 25', 'per issue #78') are development noise an agent doesn't need, which slightly dilutes structure.

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 compensates: it describes rows (full per-property record with extracted_features), the optional pivoted summary table shape, per-row error envelope fields, and terminal error kinds. Nothing needed to interpret results is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it explains why include_summary defaults off (results[].property.* already carries everything, and the summary roughly doubles response weight) and that include_description is omitted from rows by default. That rationale/payload-implication is genuine added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope ('Side-by-side analysis of 2-25 Zillow properties') and explicitly differentiates itself from the sibling zillow_bulk_get. An agent can tell immediately which tool does the pivoted comparison vs. the plain fetch-many.

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?

Names the alternative explicitly and the condition that selects it: 'If you just want N property records, use zillow_bulk_get instead — compare is for genuine side-by-side... bulk_get accepts up to 200 ids.' This gives both when-to-use and when-not-to-use with the routing rationale.

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. The description adds valuable behavior beyond that: 'No network — pure local math', handling of mortgages paid off within the horizon, and the capping of horizon_years and loan_term_years at 50. It does not contradict annotations and enriches the agent's understanding of execution 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 a single dense paragraph with five sentences, each adding substantive detail. It is front-loaded with the primary purpose and follows with assumptions and outputs. While it could be bulleted for readability, it is appropriately sized for the tool's complexity 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 15 parameters and no output schema, the description is remarkably complete: it explains inputs, defaults, edge cases (mortgage payoff, horizon caps), and outputs (year-by-year costs, break-even year, net difference). An agent has sufficient information to invoke the tool correctly without needing further clarification.

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 53%, leaving many parameters undocumented. The description compensates by explaining the role of key parameters: down payment, closing costs, monthly PITI, maintenance (default 1%), appreciation (default 3%), rent growth (default 3%), investment_return_rate (default 6%), and the cap on horizon_years and loan_term_years. This adds meaning beyond the schema, though not every parameter is covered.

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 a specific verb ('Project') and resource ('cumulative cost of buying a home versus renting'), and outlines the key factors and outputs (year-by-year costs, break-even year, net difference). It is distinct from sibling tools, none of which offer rent-vs-buy analysis, so an agent can immediately identify 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 implies usage for rent-vs-buy decisions through its detailed cost modeling, but it does not explicitly state when to use it versus alternatives. Since no sibling tool provides this functionality, the context is clear without needing exclusions, but explicit guidance would improve 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?

The description discloses the multi-rung resolution algorithm (direct, autocomplete, suffix expansion, locality remap, search fallback), the via field that reports which rung matched, the queried_city/resolved_city substitution visibility, and the degrade-to-{resolved:false} behavior. It also states 'Read-only, no auth required,' which complements the readOnlyHint annotation. This goes well beyond the annotations' boolean 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 dense but every sentence earns its place: the price-band warning is front-loaded, the rung list is compact, and the return contract is stated. It is longer than average, but the complexity of the tool (5 rungs, 2 special return fields, fallback behavior) justifies the length. Slight redundancy between the price_min schema description and the tool description is the only minor waste.

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 7-param tool with no output schema, the description covers the resolution algorithm, the failure mode, the return contract (via, queried_city, resolved_city), and the auth/read-only profile. The view parameter's behavior is documented in the schema. Nothing an agent needs to call this correctly and interpret the result is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds load-bearing context for price_min/price_max (disambiguation in search fallback) and explains the address/city/state interplay via the locality-remap rung. It doesn't add syntax details for zip/state/view, but the schema already covers those. The added price-band guidance and the rung-specific role of address components justify a 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 opens with a specific verb and resource: 'Resolve a free-text address ... to its Zillow canonical homedetails URL and zpid.' This clearly distinguishes it from siblings like zillow_search_properties (search) and zillow_get_property (fetch by ID). The title reinforces the same purpose, and the description names the exact output artifacts (URL + zpid).

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: it explains that for rural/mountain-MLS/locality-mismatched addresses, the search-fallback rung is often the only rung that hits, and instructs callers to ALWAYS pass price_min and price_max in those cases. It also names the fallback behavior when all rungs miss. This is actionable routing guidance beyond what the schema provides.

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 openWorldHint=true. The description reinforces this with 'Read-only; safe to call repeatedly' but adds no new behavioral context such as rate limits, authentication needs, or error behavior. No contradiction with annotations is 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 two tight sentences, front-loading the core purpose and metrics, then giving input instructions and safety reassurance. There is no filler or redundant expansion.

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 read-only tool with two documented optional params and no output schema, the description adequately prepares an agent by listing the expected report contents and the acceptable input forms. It would be slightly stronger if it explicitly stated the one-of requirement and possible behavior when neither parameter is supplied.

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 both parameters are already documented. The description adds the key semantic insight that the parameters are alternatives — 'Provide either a region_path ... or a full Zillow home-values URL' — which is not encoded in the schema's optional-parameter structure.

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 fetches a market report for a Zillow region and enumerates the specific metrics included (median sale/list prices, days on market, inventory, new listings, ZHVI, and YoY change). This is a specific verb+resource and it distinguishes the tool from property-level, search, and comparison siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool via its purpose, but it does not explicitly state 'use this when you need regional market stats' or mention any alternatives. It does give a clear instruction to provide either a region_path or a full URL, which is useful, but no exclusionary guidance versus 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 mark this read-only/idempotent, and the description adds substantial non-structured context: the dual return arrays, the fixed normalized `type` enum, and the important edge case where Zillow omits history (empty `events` plus explanatory `note`, distinct from genuine no-history).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose, then the return shape, then the edge case, in four tight sentences with no filler. The em-dash clauses carry real information rather than padding.

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 carries the burden: it explains both return arrays, the normalized enum, and the failure/empty case. An agent has everything needed to call 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 both parameters (url, zpid) are already documented in the schema. The description only restates the two lookup keys without adding format or precedence guidance (e.g., which key wins if both are supplied).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Listing-price events for a property') plus the full event taxonomy and the two lookup keys. It is immediately distinguishable from siblings like zillow_get_zestimate_history and zillow_get_tax_history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context: use zpid or homedetails URL, and notes it is sourced from the same page as zillow_get_property. It does not explicitly state exclusions (e.g., 'use zestimate_history instead for value estimates'), so routing is implied rather than spelled out.

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 cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial non-obvious behavior: the raw `description` is suppressed by default, price/tax history are opt-in, lot_size_acres is a derived rounded field that is null (never 0) for condos. It also pins down the sign convention of zest_vs_list_pct, which is exactly the kind of trap an agent would otherwise get wrong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Information-dense but front-loaded: the identifier options come first, then return contents, then the opt-in flags. Given there is no output schema, explaining the return payload here is earned rather than filler; the only mild duplication is restating the include_description default that the schema already states.

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 5 parameters, no output schema, and heavy derived-value logic (lot_size_acres, zest_vs_list_pct, extracted_features), the description carries the full burden and does so: it documents return shape, defaults, null semantics, and the one-of identifier rule. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema baseline is 3, but the description adds real meaning on top: why include_description defaults to false, what each history flag mirrors, and that bundling them saves a round trip. The one gap is `url`, whose accepted formats are only documented in the schema, not the 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?

Opens with a specific verb+resource ('Fetch a property's full Zillow record') and names both accepted identifiers (zpid or homedetails URL). It also enumerates the returned fields, which lets an agent distinguish it from siblings like zillow_get_by_address, zillow_search_properties, or the history tools without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a hard calling constraint ('Provide exactly one of zpid or url') and a clear decision rule for the opt-in flags ('bundle them in to skip a separate call'), naming the sibling calls they mirror. It does not, however, explain when to reach for this tool versus zillow_get_by_address or zillow_search_properties, so routing among the retrieval siblings is left 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, idempotentHint and openWorldHint, so the 'read-only; safe to call repeatedly' line is largely redundant. However, the description adds genuinely new behavioral context: the token-budget warning for large galleries and the exact return shape. That is real value beyond the structured fields.

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?

Every sentence carries a distinct payload — scope, return contents, parameter constraint, opt-in flag with warning, and return shape — and the most important scoping information is front-loaded. No 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?

With no output schema, the description compensates by naming the returned keys (zpid, count, photos, street_view_url, high_res_url) and by flagging the one real failure mode (token overflow on 50+ photo properties). Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not encode: the mutual exclusivity of zpid and url ('provide exactly one of') and the practical guidance that include_sources is on by default for properties under ~15 photos.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('full photo gallery for a Zillow property') and scopes it to images embedded in the homedetails page, which clearly separates it from the sibling zillow_get_property and history tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives the selection rule between the two input modes ('provide exactly one of zpid or url') and a condition for include_sources, but never says when to prefer this tool over zillow_get_property or zillow_bulk_get. Usage is implied by the tool name rather than stated.

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 cover readOnly/idempotent/openWorld, and the description adds genuinely non-obvious behavior: an unknown session_id errors, and the id is a label only because the request goes through whichever tab the extension is signed into. That is exactly the kind of surprising routing detail annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return contents, then the session_id caveat, then auth and safety notes. Every sentence carries information — notably the return-field list, which is needed because no output schema exists.

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 enumerating returned fields, and it also documents the auth requirement and the session-id edge case. An agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: session_id is validated against a registry and errors if unknown, yet does not control routing and defaults to the active session. That is substantive semantic detail, not a restatement.

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 names a specific verb+resource (the signed-in user's saved/favorited homes) and adds scope precision ('flattened across all of the user's collections'), which cleanly separates it from zillow_get_saved_searches and the other zillow_get_* 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?

It states the precondition ('Requires the user to be signed in') and the safety profile ('Read-only; safe to call repeatedly'), giving clear context for when the tool applies. It never explicitly routes the agent away from an alternative such as zillow_get_saved_searches, so it stops short of the 5-level 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?

Annotations already cover read-only/idempotent/open-world, yet the description adds genuinely new behavior: the authentication requirement and its named error, and the non-obvious caveat that session_id is only a registry label and does not control which tab serves the request. This is exactly the kind of auth and side-effect context annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with what the tool returns before the operational caveats. Dense with parenthetical detail but no wasted sentences; slightly crammed rather than bloated.

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 enumerating the returned fields, and it covers the auth precondition, the error case, and the session_id behavior. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3, but the description goes well beyond the schema text: it explains that an unknown session_id errors and that the parameter is a label only, with routing always following the signed-in tab. That is meaningful semantics the schema does not convey.

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 names the exact resource (the signed-in user's saved searches on zillow.com) and enumerates the returned fields (name, filters, new-listing count, notification frequency), which cleanly separates it from the sibling zillow_get_saved_homes. An agent can identify this tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the precondition clearly (user must be signed in at zillow.com in the bridged tab) and the failure mode if not (SessionNotAuthenticatedError), plus when session_id applies. It does not explicitly route the agent away from alternatives, but the context for use is unambiguous.

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?

Adds substantial context beyond annotations: describes the empty/null degenerate case, clarifies that the registry doesn't affect which account requests use, and explains the ContextMint Bridge tab-sign-in requirement for switching accounts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and return shape, then adds the important caveat about label-only semantics. Somewhat long, but every sentence earns its place given the unusual registry-vs-account distinction.

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, so description carries the return-value burden, which it does by naming sessions and active_session_id. It covers the key behavioral gotcha, though a hint about how the label maps to account changes via zillow_set_active_session would close the loop.

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?

Zero parameters, so baseline is 4. No params to document, and the description correctly omits parameter discussion.

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?

State a specific verb (List) and resource (registered Zillow sessions/account labels) and names the exact return fields (sessions, active_session_id), distinguishing it from the sibling zillow_set_active_session and zillow_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 explains the registry is a label only and that switching accounts requires signing a tab into the desired account, effectively routing agents toward the correct behavior. However, it doesn't explicitly name zillow_set_active_session as the alternative for changing the active session.

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 readOnly, idempotent, open-world, so the safety profile is covered. The description adds real value beyond that: the data source (homedetails page) and the important edge case where `events` is empty with an explanatory `note` for some (often non-Showcase) listings.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with what it returns, then source, then the edge case. Dense but every clause adds distinct information; no 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?

No output schema exists, and the description compensates by describing the record contents and the empty-events/note behavior. Both optional params are schema-documented, so the only faint gap is no explicit sibling routing.

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 `url` and `zpid` are already documented in the schema, and the description adds no format or selection guidance for them. Baseline 3 applies where structured data carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (year-by-year property-tax record for a property) and enumerates the payload (tax paid, assessed value, YoY change rates). It is clearly distinguishable from zillow_get_price_history and zillow_get_zestimate_history by resource, but it never names those siblings to route the agent 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?

Offers intended use ('spotting reassessment jumps or comparing tax burdens across properties'), which implies context but gives no explicit when-to-use-vs-alternative guidance. It does flag the empty-`events` case as distinct from a genuine no-history, which is partial exclusion 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?

Annotations already cover readOnly/idempotent/openWorld, and the description goes further by disclosing the return shape ({date, value, rent?}), when rent appears, and the empty-`points`-plus-`note` edge case that is distinct from genuine no-history. That is real behavioral context beyond what the annotations provide, even if 'read-only; safe to call repeatedly' restates the 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?

Front-loaded with the core purpose, then the sibling distinction, then the edge case — a sensible ordering with no filler. The closing 'Read-only; safe to call repeatedly' is redundant with readOnlyHint/idempotentHint, a minor wasted 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 output schema, the description carries the return-value burden and does so: it specifies the time-series shape, the optional rent field, and the empty-result semantics. An agent has everything needed to call and interpret it.

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% and both parameters (url, zpid) are fully documented in the schema, so the description adds no syntax or constraint detail beyond restating the either/or input. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (historical Zestimate values) and the exact retrieval key (zpid or homedetails URL). It explicitly distinguishes itself from the sibling zillow_get_property, which returns only the current scalar Zestimate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use rule: 'call this tool when you need the trend,' and names the alternative that covers the current value. It also flags the common failure mode (client-side-rendered trend → empty points) so the agent can interpret the result rather than assume no history exists.

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 read-only, open-world, and idempotent semantics. The description adds substantial behavioral detail beyond that: the exact round-trip performed, the diagnostic fields returned (role, port, version, extension link state, elapsed time), and a plain-English hint that distinguishes four failure modes. This is rich context for a tool with no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and a compact list of return diagnostics. The first sentence is long but every element earns its place; no filler sentences. Slightly dense, but appropriate for the amount of useful information conveyed.

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 as a diagnostic endpoint, zero parameters, rich annotations, and absence of an output schema, the description covers what the agent needs: what it does, what it returns, safety profile, and when to invoke it. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there are no parameter semantics to explain. Baseline for zero parameters is 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?

States a specific action (round-trips a URL through ContextMint Bridge) and enumerates the diagnostics returned, making clear this is a diagnostic tool distinct from all data-fetching siblings. An agent can immediately tell it apart from tools like zillow_get_property or zillow_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?

Explicitly says when to call it: 'when a real tool fails and you want to know which hop broke.' Clear context, but does not provide when-not-to-use guidance or name alternative diagnostic paths, which would be needed for a 5.

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

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

Annotations cover the safety profile (idempotent, non-destructive, not read-only), and the description adds non-obvious behavior beyond them: the registry is a label only and does not change which account requests use, plus the browser-tab constraint governing every zillow call. This is exactly the kind of caveat an agent cannot get from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, followed by idempotency, return value, parameter tip, and the routing caveat. Every sentence carries distinct information with no 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?

Covers the action, the update semantics, the returned session_id (important since there is no output schema), and the critical constraint that the registry does not affect request routing. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are already documented; the description's mention of 'keyed by account_identity' and 'pass mark_active: true' largely restates the schema. auth_expires_at is not elaborated on at all, so no value is added beyond the 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?

States a specific verb and resource ('Record (or refresh) which Zillow account the signed-in session belongs to') and names the keying field, which distinguishes it from siblings like zillow_set_active_session and zillow_get_session_context. An agent can identify the tool's scope without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context: re-registering the same identity updates the existing entry, and mark_active can promote it in the same call. However, it never explicitly names or excludes the sibling zillow_set_active_session, leaving the agent to infer when to use that instead.

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?

This is unusually transparent. It discloses concurrent fan-out, a hard overall deadline, per-row error capture, bot-wall challenges with blocked/retry_after_s, rate throttling, rung-wise confidence values, and locality remapping behavior. The readOnly/idempotent annotations are consistent with 'Read-only, no auth required,' so there is no contradiction.

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 dense and front-loaded: purpose, limit, and the critical price_hint warning come first. Some redundancy exists in repeatedly cross-referencing zillow_bulk_get and the shared resolver, but each sentence still contributes behavioral or operational context.

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 burden of explaining return semantics, and it largely succeeds. It defines all confidence values, enumerates error_kind values including 'pending' and 'bot_challenge,' and documents the pending count and blocked envelope. This is complete enough for an agent to call the tool correctly and handle failure modes.

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, but the description adds substantial param-level value. It explains that price_hint is frequently the only disambiguator, derives a ±0.5% band from it, and clarifies the bare-string vs structured-object address forms. This goes well beyond the schema's type definitions.

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: 'Resolve up to 100 free-text or structured addresses to Zillow zpids + canonical URLs in one call.' It clearly distinguishes itself from the single-address sibling zillow_get_by_address by framing this as the bulk variant and explicitly stating both share the same 5-rung resolver.

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 strong practical guidance: 'Always pass price_hint for any row where you have a sense of the price' and explains why it is load-bearing. It names zillow_get_by_address as the single-address alternative and notes that bulk and single walk the same resolver ladder, but it does not explicitly state a when-not condition such as 'for one address, prefer zillow_get_by_address.'

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 cover read-only/idempotent/open-world, but the description goes well beyond them: error behavior (throws LocationNotResolved rather than silently defaulting), the ~40-listings-per-page server cap and auto-pagination semantics, and the fact that filters are skipped on the address path. That is exactly the behavioral context annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, then routings, then caveats, with no filler sentences. It is long and leans on parenthetical asides, but nearly every clause carries actionable information, so it stays just short of over-verbose.

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 12-param open-world search with no output schema, the description names the returned fields, the meta behavior (total_result_count, pages fetched, truncated), pagination edge cases, and failure mode. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 67% schema coverage, the description still adds real meaning: the interaction between `limit` and `auto_paginate`, what `view: compact` strips (image/avatar URLs), and that `map_bounds` exists to tile dense markets. A few params (beds_min, baths_min, price_min/max) get no extra context, keeping it below 5.

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 ('Search Zillow listings by location...and optional filters') and enumerates the filter dimensions and return fields, so an agent knows exactly what it produces. It also explicitly distinguishes itself from zillow_get_by_address and zillow_get_zestimate_history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing rules: city/ZIP queries get filters applied, full-address queries do not, and zillow_get_by_address is named as the cleaner one-shot address lookup. It adds a tactical recommendation (price-band dense markets) and names the alternative for Zestimate history.

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 non-readOnly, idempotent, non-destructive, but the description adds the critical behavioral fact that this is a label only and routing is controlled by the browser tab the extension is signed into. This is exactly the context that stops an agent from assuming the call changes account 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?

Three tight sentences with the purpose front-loaded and the crucial caveat following immediately. No filler, though the routing sentence is slightly extended and could be trimmed marginally.

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, no-output tool, everything an agent needs is present: the action, the prerequisite that the session must already be registered, and the limitation that it does not affect request routing.

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% and the single parameter is fully documented in-schema, so the baseline is 3. The description adds the 'previously registered' prerequisite, but no format or syntax detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and object ('Mark a previously registered session_id as the current account label') and immediately scopes it as bookkeeping-only. An agent can tell this apart from zillow_register_session and zillow_get_session_context without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context ('for your own bookkeeping across a conversation') and an important when-not: it does not switch the account requests use. It stops short of naming a specific alternative tool, but the exclusion is explicit and prevents the most likely misuse.

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

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

Annotations only declare readOnly=false, openWorld=true, idempotent=true, destructive=false. The description goes well beyond: it discloses sequential paced requests sharing the `zillow_bulk_get` throttle, the bot-wall failure contract (`{ blocked: true, retry_after_s }` with partial results), the recursive quartering/dedupe/drift-guard algorithm, and clarifies that the only write is the optional local output file. This explains the readOnly=false annotation rather than contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then densely sequenced through algorithm, return shape, output options, and failure behavior. It is one very long paragraph and somewhat dense to parse, but essentially every clause carries operational information rather than 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?

For a high-complexity, 13-param tool with no output schema, the description covers the critical ground: what the return contains (completeness summary plus listings), the file-output alternative, the throttling model, and the blocked/retry failure mode. Only the individual filter parameters and the exact shape of individual listing fields are left unaddressed.

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 only 54% across 13 params. The description gives useful conceptual context for the sweep controls (tile_cap, max_depth, max_requests, output_path) and mentions re-applying numeric filters, but those params already carry schema descriptions, and the remaining filter params (beds_min, baths_min, home_types, status, price range) are undocumented in both places. It partially, not fully, compensates for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Enumerate EVERY Zillow listing matching the filters inside a location ... or an explicit bounding box, without silent truncation.' The phrase 'without silent truncation' and 'EVERY' distinguish it from the ordinary sibling search by defining the exhaustive-completeness guarantee. An agent can tell it apart from zillow_search_properties without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the tool's completeness guarantee suggests when to reach for it, and it advises using `output_path` for large areas. But there is no explicit when-to-use/when-not statement and no direct instruction like 'prefer zillow_search_properties for a quick single-page lookup'; the sibling references (search_properties, bulk_get) are made for resolution and throttling reasons, not routing.

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