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

Even though annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavior: per-row success/error isolation, retry-once-on-timeout, concurrency cap of 6, bot-wall handling with exponential backoff, error_kind values like bot_challenge and pending, a blocked/retry_after_s envelope, and an overall hard deadline. This goes far beyond the annotations.

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

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

The description is front-loaded with purpose and the alternative tool, but the rest is one dense paragraph packed with implementation specifics, issue references (#78, #90, #98), and jargon like 'SW evictions' and 'burst 20'. The content is valuable, but the structure is not concise or easily scannable; bullet points would improve it.

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 takes on the burden of explaining return values—and it does cover the per-row shapes, error kinds, bot-challenge envelope, and pending count. The main gap is that the success `property` object's fields are left unspecified, though the description is otherwise remarkably complete for a complex bulk endpoint.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds 'one structured row per input id' and explains that a bad zpid does not fail the whole call, but it does not define exact URL/path formats or clarify how zpids and urls relate beyond what the schema already says. The schema carries most of the parameter meaning.

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

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

The description opens with a specific verb and resource: 'Fetch up to 200 Zillow property records in a single call' and clearly frames it as the bulk endpoint. It also distinguishes itself from zillow_compare_properties by stating there is no pivoted side-by-side summary table, so an agent can tell them apart.

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 routes to an alternative: 'for 2-25 listings with a comparison summary use zillow_compare_properties'. This is a clear when-to-use-this-versus-that signal, which is exactly what an agent needs for tool selection.

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 and idempotent, but the description adds 'No network — pure local math', clarifying it is a deterministic, side-effect-free calculation. It also discloses the output structure (binding constraint, PITI breakdown), which goes beyond annotations. No contradiction found.

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

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

Two sentences, front-loaded with the primary action and rule, then inputs and outputs. Every sentence adds value—no fluff. The 'No network' note is a meaningful behavioral distinction, not 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 tool with 10 parameters and no output schema, the description covers the purpose, inputs, outputs, and a behavioral note. It gives an agent all information needed to decide whether to call it and what to expect. Nothing critical 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 60%, but the tool description lists all input categories (income, debts, down payment, interest rate, property tax, insurance, HOA, term) and adds meaning to parameters lacking schema descriptions (e.g., down_payment, insurance_annual, hoa_monthly). It also explains the 28/36 DTI context, which enriches parameter understanding.

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 ('Solve for'), resource ('maximum home price'), and the governing rule (28/36 DTI). It clearly differentiates from siblings like zillow_calculate_mortgage by focusing on affordability rather than payments, and notes 'No network — pure local math' to distinguish from network-based tools.

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

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

The description implicitly conveys when to use it (when an agent needs to determine max affordable home price), but it does not explicitly name alternatives or state when not to use it. It gives clear context via inputs/outputs, but lacks explicit exclusions. Still, the purpose is unambiguous enough for an agent to route correctly.

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

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint=false. The description adds valuable beyond-annotation context: no network call, fully deterministic, safe for scenario comparison, automatic PMI logic, and default down payment behavior. This significantly enhances an agent's understanding of side effects and constraints.

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 dense sentences with no filler. The core purpose and key outputs are front-loaded, followed by the most important parameter rules. Every clause earns its place.

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

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

For a 10-parameter tool with no output schema, the description covers the main return values and the critical parameter interactions. Minor gaps remain—such as what happens if both down_payment and down_payment_percent are provided, and the loan_term_years default (though the schema handles it). These are small enough not to hamper correct invocation.

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

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

Schema description coverage is only 40%, so the description carries the burden—and it delivers. It explains the mutual exclusivity of down_payment and down_payment_percent, the 20% default, the property_tax_annual vs property_tax_rate alternatives, and the PMI condition tied to LTV and pmi_rate. These are the trickiest parameters and the description clarifies them.

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+resource: 'Local-only mortgage payment calculator.' It further details the exact outputs (full PITI breakdown and total interest over the life of the loan), making the tool's function unambiguous. It is clearly distinct from sibling tools like property search or market report tools.

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

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

The description explicitly states when to use it: 'safe to use for scenario comparison without burning a fetch.' This gives clear context for local/no-network usage. However, it does not explicitly name alternatives or state when NOT to use it, 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?

Beyond what readOnlyHint/openWorldHint/idempotentHint already convey, the description discloses per-row error isolation, a concurrency cap of 6 in-flight requests, retry-once-on-timeout behavior, and default omissions of description and summary. This is rich behavioral context that helps the agent predict partial failures and response weight.

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

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

The description is front-loaded with purpose and the key alternative, then moves methodically through inputs, output, and failure behavior. It is dense but mostly earns its length. Some internal issue references ('Issue #79', 'issue #78') are changelog-style noise that an agent does not need for invocation.

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 clearly describing the return shape: full per-property records per row, extracted_features populated, optional pivoted summary, and behavior when a single zpid fails. Together with the schema and annotations, an agent has enough context to call this tool correctly and interpret 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 description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining when to use zpids vs urls, how include_summary affects response weight, and why include_description defaults off. It doesn't fully re-document each parameter, but it adds meaningful usage 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 uses a specific verb and resource: 'Side-by-side analysis of 2-25 Zillow properties.' It clearly scopes the tool to comparing properties rather than fetching them, and explicitly names the sibling it is not (zillow_bulk_get), so an agent can distinguish it from related tools.

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

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

The description states exactly when to use this tool versus zillow_bulk_get: use compare for genuine side-by-side analysis, use bulk_get when you just want N property records. It also explains optional flags (include_summary, include_description) and their defaults, giving clear invocation 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 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 the operation as readOnly, openWorld, and idempotent. The description adds substantial behavioral detail beyond that: the dual output arrays (events and events_normalized), the fixed type enum, and the critical edge case where empty events plus a note indicate omitted history rather than a genuine absence. This is exactly the kind of contextual disclosure that helps an agent handle responses correctly.

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

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

The description is three dense sentences with the core purpose front-loaded, followed by output structure and a caveat. Every sentence earns its place, and there is no filler or repetition of the title/name.

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

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

Even without an output schema, the description fully explains the return shape (raw events vs. normalized events with the enum) and the important non-Showcase edge case. Combined with the annotations covering safety, idempotency, and open-world behavior, an agent has everything needed to call and interpret this 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?

The input schema already documents both url and zpid at 100% coverage, so the baseline is 3. The description adds value by clarifying that the two parameters are alternative lookup keys ("by zpid or homedetails URL"), which is a relationship not explicitly stated in the individual schema descriptions. This modest extra semantics justifies 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: "Listing-price events for a property" and states the two input identifiers (zpid or homedetails URL). It clearly differentiates this tool from siblings by focusing on listing-price events and explicitly mentioning the same source page as zillow_get_property, which helps distinguish it from property-details and other 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?

The description provides clear context: it is for retrieving price history events, and it explains the cross-MCP normalized shape, which is a strong usage signal. It also discloses the non-Showcase caveat where history may be omitted. However, it does not explicitly name alternative tools or give when-not-to-use conditions, stopping 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?

Annotations already mark this read-only, open-world, and idempotent, and the description adds substantial behavioral detail beyond that: exact formulas for lot_size_acres and zest_vs_list_pct, null-never-zero behavior for lots, keyword-derived extracted_features, and default omission of raw description. No contradiction with annotations exists.

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

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

The description is long but appropriately dense for a tool with no output schema; the primary purpose is front-loaded and every major field/formula earns its place. Minor redundancy exists, such as restating the read-only/safe-to-repeat trait that annotations already convey, so it is not flawless.

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 an output schema, the description carries the full burden of explaining the return shape, and it does so thoroughly: address variants, neighborhood, prices, Zestimate, derived lot fields, schools, extracted_features, and the list-vs-Zestimate spread. It also covers all opt-in flags and the 'exactly one' input constraint, leaving no obvious gap for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description raises this by clarifying the exclusivity of zpid vs url, giving a numeric zpid example, and explaining when include_description is unnecessary. It adds useful decision context on top of the schema's 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 opens with a specific verb and resource: 'Fetch a property's full Zillow record by zpid ... or by homedetails URL.' It clearly distinguishes this from sibling tools like zillow_get_by_address, zillow_search_properties, and the history-specific tools by framing it as the comprehensive property-record fetch.

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 concrete usage context, including 'Provide exactly one of zpid or url' and recommends bundling price/tax history 'to skip a separate call,' which routes the agent away from zillow_get_price_history and zillow_get_tax_history. It does not explicitly name alternatives for address-vs-zpid lookups, but the input conditions are clear enough for selection.

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, and the description reinforces these with 'Read-only; safe to call repeatedly.' It adds substantial behavioral detail beyond annotations: the token-budget warning for 50+ photo properties, the conditional behavior of include_sources, and the exact return shape including optional keys.

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?

Four dense sentences with no filler: purpose, return contents, parameter rules, warning, return shape, and safety are all included. The most important scoping information is front-loaded, and every clause earns its place.

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

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

Even with no output schema, the description provides enough context for an agent to call the tool correctly: return object shape, optional fields, exclusivity constraint, include_sources behavior, token risk, and read-only safety. This is complete for a photo-fetching 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%, but the description adds critical semantics the schema omits: `zpid` and `url` are mutually exclusive despite both being optional in the schema, and `include_sources` carries a warning about token usage. It does not fully reconcile the schema's ambiguous 'on for properties with <~15 photos' default, which keeps this from a 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?

The description opens with a specific verb-resource pairing: 'The full photo gallery for a Zillow property.' It explains exactly what is returned (hero URL, widest jpeg/webp variants, caption) and is clearly distinct from sibling tools like zillow_get_property or zillow_get_price_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?

The description gives clear invocation guidance: provide exactly one of `zpid` or `url`, and set `include_sources: true` only when the full source lists are needed. It does not explicitly name sibling alternatives or state 'use this when you need photos rather than property details,' so it falls just short of full when-to-use-vs-alternatives 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 declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context: it requires the user to be signed in, it flattens across collections, and it is safe to call repeatedly. It does not detail pagination or error behavior, but for a read-only list tool with these annotations, the added context is sufficient.

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

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

The description is three sentences with no wasted words. It front-loads the core purpose and return fields, then covers the optional parameter and safety note. Every sentence earns its place.

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

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

For a read-only list tool with one optional parameter and no output schema, the description is nearly complete. It covers the resource, scope, return fields, session handling, and sign-in requirement. The only minor gap is the lack of explicit pagination or result-limit information, but that is not critical for a saved-homes list 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 description coverage is 100%, so the schema already documents the single optional `session_id` parameter. The description adds meaning by explaining the parameter's purpose (target a specific signed-in account) and its default behavior (defaults to the active session). This goes beyond the schema's description, which only says 'Optional registered session id'.

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

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

The description states a specific verb ('get'), a clear resource ('saved/favorited homes'), and a scope ('flattened across all collections'). It also lists the returned fields (address, price, Zestimate, status, saved timestamp), which distinguishes it from sibling tools like zillow_get_saved_searches and zillow_search_properties. The title reinforces the purpose without being a tautology.

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 says when to use this tool: to retrieve the signed-in user's saved homes. It also provides a clear alternative/context by mentioning `session_id` from `zillow_register_session` and the default active session. It does not explicitly name sibling alternatives, but the resource and scope are so specific that an agent can route correctly without ambiguity.

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 covered. The description adds valuable context beyond annotations: the authentication requirement, the specific error thrown, and the session targeting behavior. It does not describe pagination or exact response shape, but for a read-only list tool this is a minor gap.

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 with no filler. The core purpose is front-loaded, followed by the key prerequisite/error, then the optional parameter behavior. Every sentence earns its place.

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

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

For a read-only, single-optional-parameter tool with no output schema, the description covers purpose, auth requirement, error behavior, and session selection. It is slightly incomplete in not mentioning whether the result is paginated or limited, but the annotations (readOnly, idempotent, openWorld) cover the safety and world-modification aspects.

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 already documents session_id. The description adds meaning by explaining where session_id comes from (zillow_register_session) and its default behavior (active session), which goes beyond the schema's description. This justifies a score above the baseline 3.

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

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

The description states a specific verb ('get'), a resource ('saved searches on zillow.com'), and enumerates the returned fields (name, filters, new-listing count, notification frequency). It is clearly distinguishable from sibling tools like zillow_get_saved_homes and 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?

The description explicitly states the prerequisite (signed in at zillow.com in the bridged browser tab), the failure mode (SessionNotAuthenticatedError), and how to target a specific account via session_id from zillow_register_session. It also notes the default behavior (active session). This is strong when-to-use 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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral detail by specifying the empty-sessions edge case: when no sessions are registered, sessions is empty and active_session_id is null. This goes beyond what the annotations state.

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 short, information-dense sentences. The primary return value is front-loaded, and the edge-case behavior is stated in a separate concise clause. There is no redundant or filler 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?

For a parameterless, read-only session-context tool, the description covers the key return values and the empty-sessions behavior. It does not describe the structure of each session object, but given the simple scope and read-only annotations, this is a minor omission rather than a blocking gap.

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

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

The tool has zero parameters, so there is no parameter documentation burden. The description instead clarifies what the response will contain, which fully compensates for the absence of an output schema. This is appropriate for a parameterless context getter.

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 uses a specific verb ('Return') and names the exact resource ('the full set of registered sessions plus the current active_session_id'). It clearly distinguishes this read-only context tool from mutation-oriented siblings like zillow_register_session and zillow_set_active_session by focusing on retrieval rather than modification.

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 implies this is the tool to call when the agent needs to inspect all registered sessions and the current active session ID. It does not explicitly exclude alternatives, but the read-only nature and focus on session state make the intended usage unambiguous compared to its 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, openWorldHint, and idempotentHint. The description adds valuable behavioral context beyond that: it explains the source page, that non-Showcase listings may omit the history, and that an empty `events` plus a `note` is distinct from a genuine no-history response. This gives the agent actionable expectations about edge cases.

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 efficiently structured: each sentence earns its place. It front-loads the core purpose, then adds practical use context, then explains an important edge case without 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?

There is no output schema, so the description must convey what the tool returns. It does so thoroughly: tax paid, assessed value, change rates, and the `events`/`note` behavior for omitted history. Combined with the annotations, the agent has enough to call the tool correctly 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 description coverage is 100%, and the input schema already documents both `url` and `zpid`. The description does not add parameter-level detail, which is acceptable given the high schema coverage, but it also does not go 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?

The description states a specific verb and resource: retrieving the year-by-year property-tax record for a property. It names the exact data included (tax paid, assessed value, change rates), making it instantly distinguishable from sibling tools like price history or 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?

The description gives clear use context: spotting reassessment jumps and comparing tax burdens across properties. It does not explicitly name sibling alternatives or state when not to use it, but the tax-specific focus makes the appropriate use case 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 readOnlyHint and idempotentHint annotations, the description discloses that rent values are conditionally included, that empty `points` may indicate a rendering limitation rather than absence of history, and that an explanatory `note` is returned in that case. It also reiterates that the tool is read-only and safe to call repeatedly, adding useful behavioral context.

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

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

The description is compact yet information-dense, front-loading the core behavior and output format before addressing the edge case. Every sentence adds value—either clarifying the return structure, guiding tool selection, or explaining empty results—so nothing is 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?

Given that there is no output schema, the description adequately explains the return format (time series of {date, value, rent?}), the conditional rent inclusion, and the empty-points note behavior. It also covers parameter choice and read-only safety, leaving no critical gap for an agent to call and interpret 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?

The input schema fully documents both parameters with clear descriptions ('Provide either zpid or url'). The description only restates the 'zpid or homedetails URL' selection without adding new semantic information, so the baseline of 3 is appropriate because schema coverage is 100%.

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 historical Zestimate values for a property by zpid or homedetails URL, and describes the output as a time series. It explicitly distinguishes itself from the sibling zillow_get_property, which returns only the current Zestimate as a scalar, so an agent can immediately tell the tools apart.

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 guidance on when to use this tool: 'call this tool when you need the trend.' It contrasts with zillow_get_property and even explains an edge case where `points` is empty due to client-side rendering versus a genuine no-history scenario, which helps the agent interpret a non-obvious result.

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 read-only and idempotent annotations, the description discloses the exact network action (fetching a public URL through the bridge), the diagnostics returned (role, port, version, link status, elapsed time, hint), and the three failure modes it can disambiguate. It also adds 'no auth required,' which is not covered by the annotations. Nothing contradicts the annotations.

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

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

The description is a single dense sentence that front-loads the action and then uses a colon to itemize the diagnostic output. Every clause adds useful information: the URL probed, the fields returned, the hint categories, and the read-only no-auth note. There is no filler or redundancy.

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

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

With no output schema and no parameters, the description carries the full burden of explaining the return value, and it does so by listing every diagnostic field plus the plain-English failure hints. It also supplies the invocation context and safety profile, so an agent has enough information to call and interpret 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?

The tool has zero parameters and the schema is empty, so there are no parameter semantics to clarify; the baseline for a zero-parameter tool is 4. The description focuses on what the tool returns rather than input semantics, which is appropriate.

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

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

The description names a concrete verb ('Round-trips'), a specific resource ('fetchproxy bridge' via www.zillow.com/robots.txt), and the diagnostic purpose, which clearly separates this healthcheck from the property-data sibling tools. It even enumerates the diagnostic fields returned, leaving no ambiguity about what the tool does.

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 says to call it 'when a real tool fails and you want to know which hop broke,' giving a clear triggering condition. It does not name sibling alternatives or explicitly state when not to use it, but for a diagnostic utility the use case is well scoped.

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: false, openWorldHint: false, and idempotentHint: true. The description adds context beyond that: the refresh behavior aligns with idempotency, and it explains the default-active-session rule and mark_active semantics. However, it doesn't disclose side effects like authentication requirements, rate limits, or what happens to other session contexts. Given the annotations cover the safety profile, a 3 is appropriate.

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: the first sentence states the action and scope, followed by two focused sentences that cover refresh behavior and active-session logic. No wasted words or repetition. It earns a 5.

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 session-registration tool with only three parameters, 100% schema coverage, and no output schema, the description covers all essential operational details: the refresh path, the return of session_id, the default active behavior, and mark_active. An agent can correctly invoke it without gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it clarifies account_identity is 'typically the saved-account email', explains that re-registering the same identity updates rather than duplicates, and describes the effect of mark_active. This goes beyond the bare schema definitions, so a 4 is justified.

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

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

The description opens with a clear verb+resource statement: 'Register (or refresh) an authenticated Zillow session keyed by signed-in account identity.' It also explains the refresh behavior ('updates the existing session rather than creating a duplicate'), which distinguishes it from a naive create. Though it doesn't explicitly contrast with siblings like set_active_session, the core purpose is unambiguous and specific.

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 on when to use the tool: for registering or refreshing a session, and how to make it active via mark_active. It notes that the first registration becomes default active, and that routing uses session_id. It doesn't explicitly name alternatives or exclusions, but the sibling set_active_session is implicitly differentiated (register vs. switch active), so it earns a 4 rather than 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?

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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses important behaviors: it throws LocationNotResolved rather than silently falling back, it auto-paginates past Zillow's ~40-listing page cap by default, it does not apply filters in the address-resolved path, and it does not return Zestimate history. The safety profile is consistent with the annotations and the 'Read-only' statement.

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 carries actionable information: scope, return fields, path-specific behavior, error behavior, pagination mechanics, and sibling routing. The main function is front-loaded, and caveats are grouped logically 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?

For a 10-parameter tool with no output schema, the description covers the essential invocation context: inputs, return fields, error semantics, pagination defaults, and alternatives for adjacent use cases. An agent has enough to call it correctly and interpret 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?

With 60% schema coverage, the description adds meaningful semantics for key parameters: it explains what 'location' accepts, that limit interacts with auto_paginate, that status/price/beds/baths/home_types are filters, and that 'full' view vs. compact is about field presence. It doesn't detail every parameter, but the schema covers several, and the description compensates for the most behaviorally important ones.

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

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

The description states a specific verb ('Search'), resource (Zillow listings), primary input (location), and optional filters, and enumerates the return fields (price, beds/baths, sqft, Zestimate, status, image, homedetails URL). It also explicitly distinguishes itself from sibling tools like zillow_get_by_address and zillow_get_zestimate_history, so an agent can select it without opening their 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?

The description gives explicit routing guidance: use zillow_get_by_address for the cleanest one-shot address→zpid lookup, and use zillow_get_zestimate_history when Zestimate history is needed. It also explains the two query paths (region-level vs. address-level) and when filters are applied, plus the practical hint to price-band dense markets for full enumeration.

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 a mutating (readOnlyHint=false) and idempotent operation, and the description does not contradict that. It adds the key behavioral fact that this sets a default for later calls and that explicit per-call session ids take precedence. It doesn't discuss persistence or error behavior, but these are less critical given the simple semantics and idempotence annotation.

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

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

Two sentences, front-loaded with the core switching behavior, followed by the prerequisite and override rule. Every sentence adds necessary information without repetition.

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

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

For a one-parameter setter with annotations for mutation and idempotence, the description covers what the tool does, where the session_id comes from, and how it interacts with per-call overrides. The only minor gap is lack of explicit return-value or error semantics, but that is low-stakes for such a simple setter.

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 alone documents session_id as 'Session id to make active' and covers 100% of parameters. The description adds essential provenance: it must be a previously registered session from zillow_register_session. This extra context helps the agent supply a valid value rather than any arbitrary string.

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 uses a specific verb ('Switch') and resource ('which registered session subsequent tool calls route through'), making the action unmistakable. It also distinguishes itself from session creation by requiring a previously registered session_id. No ambiguity with siblings like 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 states the exact use case: change the default routing for subsequent calls. It conditions the input on a session_id previously returned by zillow_register_session, telling the agent where to obtain a valid value. It further clarifies that explicit per-call session_id parameters override this default, which prevents misuse, though it does not explicitly enumerate when not to use the tool.

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