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

Adds substantial context beyond annotations: concurrency cap (6 in flight), per-host rate limiting, retry-on-timeout, bot-wall handling with error_kind 'bot_challenge' and envelope, hard deadline with 'pending' error_kind. No contradictions with annotations (readOnlyHint, openWorldHint, idempotentHint).

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 longer than average but every sentence adds necessary detail. It is front-loaded with purpose and structured logically: purpose, result format, concurrency, throttling, error handling, deadline. Could be slightly tighter, but no redundant sentences.

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 (concurrent fetches, throttling, multiple error modes, deadline), the description covers all critical aspects. No output schema exists, but the description explains the return structure (rows with success/error, envelope). Sibling tools are listed elsewhere; description handles differentiation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that either 'zpids' or 'urls' must be provided (mutually exclusive) and specifying the max of 200 (already in schema but restated). Also elaborates on error handling per row, which enriches parameter semantics.

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

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

The description clearly states the verb ('Fetch'), resource ('Zillow property records'), and scope ('up to 200', 'single call'). It distinguishes from sibling zillow_compare_properties by explicitly noting the absence of a side-by-side summary table.

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

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

Provides explicit when-to-use ('give me everything for these N saved homes'), when-not ('no pivoted side-by-side summary table'), and alternative ('for 2-25 listings with a comparison summary use zillow_compare_properties'). Also mentions error handling and retry behavior, guiding agent on how to handle partial failures.

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, indicating safe reads. The description adds 'No network — pure local math,' which confirms no side effects and local computation. It also describes outputs (max home price, binding constraint, PITI breakdown). This adds value beyond annotations.

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

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

The description is a single paragraph of ~80 words, efficiently summarizing purpose, inputs, and outputs. Every sentence adds value; no fluff or repetition. It is front-loaded with the core purpose.

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

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

Given no output schema, the description explains the output in detail (max home price, binding constraint, PITI breakdown). It covers all important aspects: inputs, outputs, and behavioral trait (local math). For a simple computation tool with annotations, this is complete and sufficient.

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 has 60% coverage, and the description lists primary inputs (income, debts, down payment, interest rate, optional tax/insurance/HOA/term). It adds context like 'recurring debts (car loans, student loans, etc.)' and mentions outputs. However, it does not significantly elaborate on parameter meaning or defaults beyond what the schema already provides. 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?

The description clearly states the tool solves for maximum affordable home price under the 28/36 DTI rule. It uses specific verbs ('Solve for the maximum home price') and specifies resource ('affordability'). It distinguishes from siblings like calculate_mortgage by focusing on affordability rather than monthly payment.

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 lists required inputs and expected outputs, making it clear when to use it (when needing affordability calculation). It does not explicitly state when not to use it or mention alternative tools, but the purpose is sufficiently distinct. Could be improved by contrasting with zillow_calculate_mortgage.

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

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

Annotations already indicate readOnly and idempotent. Description adds that it is local-only, deterministic, safe, and explains automatic PMI application when LTV > 80%. Does not contradict annotations.

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

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

Three well-structured sentences: purpose/output, safety/determinism, parameter guidance. No wasted words; fully front-loaded.

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

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

Covers main output and key parameter usage. Lacks explicit mention of home_price, interest_rate, hoa_monthly, insurance_annual, and output format. Given complexity and no output schema, it is mostly complete but could be slightly more detailed.

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 low (40%), but description compensates well by explaining mutual exclusivity of down payment fields, defaults, PMI condition, and property tax options. Adds significant meaning beyond schema.

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

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

The description clearly states it is a mortgage payment calculator, specifies the output (PITI breakdown, total interest), and distinguishes itself from siblings by emphasizing local-only, no network call, and safe for scenario comparison.

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

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

Provides clear guidance on parameter alternatives (down_payment vs down_payment_percent, property tax options) and highlights safe use for scenario comparison. Lacks explicit comparison to sibling calculators but gives enough context for effective use.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds substantial behavioral context: concurrency capped at 6 with retry-once-on-timeout, per-row error handling (one bad zpid doesn't fail the call), default behavior for optional fields, and a note about the cap increase from 8 to 25. No contradictions.

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

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

The description is dense but efficient, front-loading the key distinction from a sibling tool. Every sentence earns its place, covering input constraints, optional parameters, behavior, and error handling without redundancy. It is neither too long nor too short.

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 complexity of the tool (4 parameters, arrays, concurrency, error handling, optional summary), the description covers all relevant aspects: input format, size limits, default behaviors, concurrent fan-out, and error resilience. No output schema is provided, but the description states return format (per-property record with extracted_features).

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 baseline is 3. The description adds value by explaining the mutual exclusivity of 'urls' and 'zpids', the rationale behind default values for 'include_summary' (redundancy with results) and 'include_description' (omitted by default), and the size constraint (2-25).

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 performs side-by-side analysis of 2-25 Zillow properties, with a specific verb ('compare') and resource ('Zillow properties'). It distinguishes itself from the sibling tool `zillow_bulk_get` by explicitly stating when to use which.

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

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

The description provides explicit guidance: use this for genuine side-by-side analysis (value-add is the pivoted summary table) and `zillow_bulk_get` for fetching up to 200 records. It also clarifies input format (zpids or URLs) and constraints (2-25 items).

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 readOnlyHint=true and idempotentHint=true. The description adds significant transparency beyond annotations by stating 'No network — pure local math,' which confirms the tool is self-contained and safe. It also explains default values and the opportunity cost concept, giving agents deeper understanding of 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 well-structured, starting with the main purpose and then detailing components and outputs. It is slightly verbose (multiple sentences) but every sentence adds value. Could be trimmed slightly while retaining clarity.

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

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

Given the tool's complexity (15 parameters, no output schema), the description covers the key model assumptions, outputs (year-by-year costs, break-even year, net difference), and the fact it is local math. However, it does not mention edge cases (e.g., negative interest rates) or validation of inputs.

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 47% (low), so the description should compensate. It explains the model and mentions defaults (e.g., maintenance ~1%/yr, investment_return_rate default 6%/yr) that are not in the schema for all parameters. However, it does not detail each parameter individually, and some parameters like loan_term_years or hoa_monthly are not described in either schema or 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?

The description clearly states it projects cumulative cost of buying vs renting over N years, listing specific components (down payment, closing costs, PITI, maintenance, appreciation, rent growth, opportunity cost). It distinguishes from sibling tools like zillow_calculate_mortgage or zillow_calculate_affordability by focusing on the rent-vs-buy comparison and break-even analysis.

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 decision making but does not explicitly state when to use it vs alternative tools (e.g., zillow_calculate_mortgage for mortgage-only calculations) or mention any prerequisites or exclusions.

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 is exceptionally transparent: it enumerates all five resolution rungs, explains the search-fallback behavior, states that it degrades to { resolved: false } rather than throwing, and discloses read-only/no-auth behavior beyond what the annotations say. There is no contradiction with the readOnlyHint, openWorldHint, or idempotentHint 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 longer than average but densely informative and well-structured: purpose, critical warning, numbered fallback rungs, return metadata, and failure behavior. Almost every sentence earns its place, though the price-param warning is emphasized twice in slightly redundant terms.

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 complex tool with no output schema, the description is complete enough to call correctly: it explains the multi-rung algorithm, the role of price bounds, the via field values, the locality-remap fields, the no-throw failure contract, and the read-only/no-auth profile. An agent has sufficient information to know what will happen and what to pass.

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 already has 100% parameter description coverage, so the baseline is 3. The description adds meaningful cross-parameter guidance: it clarifies that address is free-text, city/state/zip are optional, and that price_min and price_max are load-bearing for the fallback rung. This goes beyond individual schema descriptions, though some of the price guidance is redundant with the schema text.

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

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

The description clearly states it resolves a free-text address to a Zillow canonical homedetails URL and zpid, with a specific verb and resource. It does not explicitly differentiate itself from the similar-sounding zillow_resolve_addresses sibling, so it stops short of full sibling differentiation.

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

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

The description gives strong context on when the tool is appropriate: resolving a free-text address to a canonical URL and zpid. It also provides crucial usage guidance around price_min/price_max for rural or locality-mismatched addresses, but it does not explicitly state when to prefer this tool over alternatives like zillow_resolve_addresses or zillow_search_properties.

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 readOnlyHint and idempotentHint; description adds concrete return data (median prices, days on market, etc.) and repeats safe-to-call nature, reinforcing transparency without 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?

Two sentences, no filler, front-loaded with key metrics and usage instruction. Every sentence serves a purpose.

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

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

For a read-only tool with full annotation coverage, the description fully explains input alternatives, output contents, and safety. No gaps remain.

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 provides 100% coverage, but description adds value by explaining that the two parameters are alternatives and giving an example for region_path. This clarifies usage beyond 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?

Description clearly states it provides a market report for a Zillow region, listing specific metrics like median prices and inventory. The verb 'get' and resource 'market report' are specific, and it distinguishes from sibling tools focusing on individual 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 instructs to provide either a region_path or a full URL, with example. Notes read-only nature. Could briefly mention when to use sibling tools for property-level data, but not necessary.

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

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

The description adds significant behavioral context beyond the annotations: it details the two return arrays (events and events_normalized), explains the normalized type enum, notes the same data source as zillow_get_property, and describes the edge case where history is omitted with a note. Annotations already indicate read-only, open-world, and idempotent, and the description complements them without 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 efficiently structured: the first sentence states the purpose, followed by details on output format, normalized shape, data source, and an edge case. Every sentence earns its place with no redundancy.

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

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

Given the tool's complexity (two arrays, edge case, no output schema), the description covers the key aspects: what is returned (events and events_normalized), the meaning of the normalized enum, and the note vs empty case. It could be enhanced by explicitly stating that both parameters are optional but at least one should be provided, and by clarifying the raw Zillow shape further if needed.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by clarifying that either the zpid or URL can be used and that they refer to a property. This goes beyond the schema's individual descriptions.

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

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

The description clearly states it retrieves listing-price events for a property, specifying the types of events and that it works by zpid or homedetails URL. It distinguishes itself from sibling tools like zillow_get_property and zillow_get_zestimate_history by mentioning the same data source and normalized output.

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 (when price history is needed) and provides context on how to use the output (normalized form for merging across MCPs). It also warns about a common edge case (missing history for non-Showcase listings). However, it does not explicitly state when not to use it or name alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description confirms 'Read-only; safe to call repeatedly'. Details response structure (address forms, derived fields like lot_size_acres and zest_vs_list_pct) and behavior of raw description omission. 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?

Single dense paragraph, but every sentence adds value. Front-loaded with primary purpose. Could be more structured (e.g., bullet points), but efficient for the information provided.

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, yet description comprehensively covers return fields including derived calculations. Parameter count 5, none required — described well. Lacks error scenarios, but acceptable given detail level.

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 100%, but description adds context: zpid explained as numeric with example, include_description highlights that extracted_features cover needs, price/tax history says they mirror other tools and save round trips. Clearly adds value beyond 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?

Clearly states 'Fetch a property's full Zillow record by zpid or homedetails URL'. Identifies verb (fetch), resource (property record), and key identifiers. Distinguishes from siblings like zillow_get_price_history by noting bundling options.

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 'Provide exactly one of zpid or url'. Suggests when to use optional parameters (include_description, include_price_history, include_tax_history) and that extracted_features usually suffice. Does not explicitly contrast with zillow_get_by_address, but provides sufficient context.

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 as true. The description adds valuable behavioral context: it is 'Read-only; safe to call repeatedly' and warns about token budget for large properties. No contradictions.

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

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

The description is a single, well-structured paragraph. It front-loads the purpose, provides essential parameter guidance, and adds warnings. Every sentence adds value with no fluff.

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

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

Despite lacking an output schema, the description explicitly states the return format ({ zpid, count, photos, street_view_url?, high_res_url? }). It covers all parameters, usage constraints, and edge cases (token budget). Completely adequate for an agent to invoke correctly.

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

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

Schema coverage is 100% with well-described parameters. The description adds significant value: explains that include_sources defaults to false but auto-enables for <~15 photos, and warns of token budget. This goes beyond the schema.

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

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

The description explicitly states the tool returns 'the full photo gallery for a Zillow property' with specific details about response structure (hero URL, jpeg/webp variants, caption). It clearly distinguishes from sibling tools (e.g., zillow_get_property) which handle different data.

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

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

Provides clear usage instruction: 'Provide exactly one of zpid or url.' Warns about potential token budget issue with include_sources. However, it does not explicitly state when to avoid this tool in favor of siblings, though the purpose makes it obvious.

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 readOnlyHint, idempotentHint, openWorldHint. Description adds 'flattened across all collections', 'requires sign-in', and 'safe to call repeatedly', providing behavioral context beyond annotations.

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

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

Two sentences with no wasted words. First sentence states purpose, second provides details. Ideal length and 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?

Despite no output schema, description lists return fields (address, price, Zestimate, status, when saved). Combined with annotations, provides complete context for agent 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?

Only one parameter, session_id, fully described with source (zillow_register_session) and default behavior. Schema has 100% coverage and description adds precise 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?

Description clearly states verb 'get' and resource 'saved homes', specifies it returns address, price, Zestimate, status, and save time. Clearly distinguishes from sibling tools like zillow_get_saved_searches 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?

Explicitly requires sign-in and explains optional session_id parameter with default behavior. Could mention when not to use, but context is clear for a simple read tool.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds information about the error condition (SessionNotAuthenticatedError) and explicitly states it is read-only and safe to call repeatedly, which reinforces behavioral understanding beyond annotations.

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

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

The description is three sentences, each providing essential information. No wasted words, and key points are front-loaded (purpose, requirement, then optional parameter).

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 simple parameter set (1 optional) and no output schema, the description adequately covers what the tool returns (name, filters, etc.) and the error condition. The requirements and side effects are clear, making it complete for a read-only tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: session_id comes from zillow_register_session and defaults to the active session. This clarifies parameter usage beyond the schema 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?

The description clearly states that the tool retrieves the signed-in user's saved searches, listing specific attributes (name, filters, new-listing count, notification frequency). This distinguishes it from sibling tools like zillow_get_saved_homes 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?

The description explains the prerequisite (user must be signed in) and the error thrown otherwise. It also mentions optional session_id for targeting a specific account, which guides usage. However, it does not explicitly mention alternatives or when not to use this tool.

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

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

The description adds value beyond the annotations by specifying the exact structure of the output (sessions array and active_session_id) and the behavior when no sessions exist. Annotations already indicate readOnlyHint, so 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 two sentences long, front-loaded with the primary purpose, and contains no unnecessary words or repetition.

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

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

Given the tool has no parameters and no output schema, the description fully explains what the tool returns, including edge cases like empty sessions and null active_session_id.

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?

There are no parameters, and the schema coverage is 100%. The description does not need to add parameter semantics, but it explains the output, which is appropriate for a param-less tool.

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

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

The description clearly states what the tool does: return the full set of registered sessions plus the current active_session_id. This distinguishes it from sibling tools like zillow_register_session and zillow_set_active_session, which perform different actions.

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 implicit context by explaining the return values when no sessions are registered. However, it does not explicitly state when to use this tool over alternatives, though the tool's purpose is clear given its name.

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 (readOnlyHint, openWorldHint, idempotentHint) already declare safe read behavior. The description adds valuable context: data source (homedetails page), the possibility of missing history with a distinguishing note, and the omission of history for certain listings. No contradictions with annotations.

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

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

Three sentences with no wasted words: first defines output, second provides context and utility, third covers an edge case. Information is front-loaded and 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?

Despite lacking an output schema, the description fully explains the return structure (tax paid, assessed value, change rates) and documents edge-case behavior (empty events with a note). This is sufficient for a read-only data retrieval 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?

Parameter schema has 100% coverage, so baseline is 3. The description does not add extra meaning to the 'url' or 'zpid' parameters beyond what the schema already provides. The description focuses on output rather than input semantics.

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

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

The description clearly states the tool retrieves year-by-year property-tax records including tax paid, assessed value, and year-over-year change rates, distinguishing it from siblings like price or Zestimate history. The specific verb 'get' is implied, and the resource (tax history) is unambiguous.

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

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

The description explains when to use the tool (spotting reassessment jumps, comparing tax burdens) and describes an important edge case (non-Showcase listings returning empty events with a note). However, it does not explicitly exclude alternatives or provide when-not-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, openWorldHint, and idempotentHint as true. The description adds value by explaining the response format (time series with optional rent), the edge case of empty points, and the safety of repeated calls. This goes beyond the annotations without contradicting them.

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

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

The description is concise at about 4-5 sentences. It is front-loaded with the primary purpose and each subsequent sentence adds key details (use alternative, edge case, safety). No extraneous 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?

Given no output schema, the description explains the return shape (time series with date, value, rent) and addresses the notable edge case of empty points. It covers the main usage scenarios sufficiently, though minor details like date ordering or pagination could be added but are not essential.

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 restates that either zpid or URL can be provided, which reinforces the mutual exclusivity but does not add substantial new meaning beyond the schema descriptions.

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

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

The description clearly identifies the tool's purpose: retrieving historical Zestimate values for a property. It specifies the input methods (zpid or URL) and explicitly differentiates from the sibling tool zillow_get_property by highlighting that it returns trends rather than a single current value.

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

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

The description provides explicit guidance on when to use this tool: 'call this tool when you need the trend' versus the current Zestimate from zillow_get_property. It also addresses the edge case of non-Showcase listings where an empty points array is expected and a note is returned, distinguishing it from a genuine lack of 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 mark the tool as read-only, open-world, and idempotent. The description adds useful behavioral detail by specifying the round-trip mechanism, the exact diagnostic fields returned, and the three failure categories ('bridge never came up', 'extension not connected', 'real www.zillow.com-side problem'). This goes beyond the structured annotations without contradicting them.

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

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

The description is compact yet information-dense: the first sentence explains mechanisms and outputs, the second covers when to use it and safety. There is no filler or repetition of schema information, and the diagnostic output list is clearly structured.

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

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

Given there is no output schema, the description adequately enumerates the return diagnostics including role, port, version, extension link state, elapsed time, and the plain-English hint. It also covers the trigger scenario and safety profile, making it complete for an agent to invoke and interpret 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 coverage is 100%, so the description carries no parameter burden. The baseline of 4 applies for zero-parameter tools, and the description appropriately focuses on behavior and outputs rather than parameter details.

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

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

The description states a specific verb and resource: it 'Round-trips a small public www.zillow.com URL (/robots.txt) through the fetchproxy bridge' and returns diagnostics. This clearly differentiates it from the data-retrieval sibling tools by framing it as a diagnostic healthcheck rather than a data lookup.

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 'Call this when a real tool fails and you want to know which hop broke,' giving a clear trigger condition. It does not explicitly list when-not-to-use or name alternative diagnostic tools, but siblings are all data-oriented, so the use case is evident.

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

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

The description adds significant behavioral context beyond the annotations: it explains idempotency (re-registering updates rather than duplicates), return value (session_id), default behavior (first session becomes active), and the mark_active parameter effect. Annotations already indicate idempotentHint=true, but the description enriches this with concrete 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 four sentences, each providing essential information: registration or refresh, idempotency, return value, default active behavior, and mark_active. No redundant or extraneous text.

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

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

Given no output schema, the description adequately explains the return value (session_id) and the active session concept. It covers key aspects for a session registration tool. However, it could briefly mention that other tools require a registered session for authentication.

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

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

Schema description coverage is 100% with each parameter documented. The description adds extra context: account_identity is typically an email, mark_active makes the session active immediately if true, and auth_expires_at is an optional expiration timestamp. It adds value beyond the schema's basic descriptions.

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

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

The description uses specific verbs ('Register (or refresh)') and identifies the resource ('authenticated Zillow session'). It clearly distinguishes from sibling tools like zillow_set_active_session and zillow_get_session_context by explaining the tool's role in session creation and refresh, and mentions the returned session_id for routing calls.

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 states the tool's purpose and how it fits into a workflow (first registered session becomes default active, mark_active parameter). However, it does not explicitly list alternatives or when not to use this tool, though sibling names imply other session management tools exist.

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/idempotent annotations, the description discloses substantial runtime behavior: the 5-rung resolver order, concurrent fan-out, per-row error capture, locality-remap substitution fields, hard-deadline behavior with error_kind 'pending', and confidence value semantics. This goes far beyond what annotations alone convey.

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

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

The description is long but every sentence earns its place: purpose is front-loaded, then essential price_hint guidance, resolver ladder, locality remap, concurrency, error handling, and deadline behavior. It is dense but structured so an agent can quickly extract invocation-critical rules.

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

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

Given no output schema, the description covers what the caller can expect: zpids, canonical URLs, confidence levels, queried_city/resolved_city, error_kind 'pending', and a pending count. It also states limits, input formats, auth requirements, and failure semantics, making the tool fully invocable without additional context.

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?

Although schema coverage is 100%, the description adds critical parameter meaning: price_hint is load-bearing, derives a ±0.5% band, and must be passed when price sense exists. It also explains that each row may be a bare string or a structured object with optional fields, and clarifies the view enum behavior by referring to field stripping.

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 this bulk resolver from the single-address sibling zillow_get_by_address, and the title reinforces the bulk zpid-resolution 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 gives strong contextual guidance: it identifies the sibling single-address tool, explains that bulk and single share the same resolver ladder, and advises passing price_hint for rural/mountain-MLS/locality-mismatched rows. It does not explicitly state 'use this instead of X when' for every sibling, but the bulk-vs-single distinction and price_hint guidance make usage 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?

Annotations declare read-only/idempotent behavior, and the description goes well beyond them: it discloses server-side ~40-listing paging, auto-pagination behavior and opt-out, the LocationNotResolved error instead of silent fallback, and the address-query exception to filter application.

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?

Long but every sentence earns its place: scope, return shape, address-query caveat, error behavior, pagination, and sibling routing are all covered without filler. Slightly dense, but structured well with the critical caveats front-loaded.

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

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

For a 10-parameter tool with no output schema, the description covers return fields, edge cases, pagination, error behavior, and alternatives. Nothing needed 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 only 60%, and the description compensates with meaningful semantics for location (city/ZIP/neighborhood/address), filters (status, price band, beds/baths minimums, home types), and especially limit/auto_paginate. It does not mention the `view` parameter, though the schema already documents it thoroughly.

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 ('Search Zillow listings') plus scope (city/ZIP/neighborhood/address with filters) and the returned fields. Explicitly distinguishes the address-query path from zillow_get_by_address, removing ambiguity.

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 alternatives and the conditions that select them: zillow_get_by_address for clean one-shot address→zpid lookup, zillow_get_zestimate_history for Zestimate history. Also clarifies when filters apply and advises price-banding for dense markets.

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 that setting the active session affects default routing for subsequent calls, and that explicit session_id parameters can override. With annotations indicating idempotentHint=true and readOnlyHint=false, the description adds context about the functional impact without contradiction. It could mention if the previous session is unaffected, but it's clear enough.

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

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

The description is concise with three sentences, all essential. It front-loads the primary action ('Switch which registered session subsequent tool calls route through by default') and provides necessary context about usage and overriding in subsequent sentences.

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, idempotent tool with one parameter and no output schema, the description covers all necessary information: what it does, how to use it, and its interaction with other tools. It is complete without being verbose.

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

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

The input schema has 100% coverage for the single parameter, which already describes it as 'Session id to make active.' The description adds value by specifying that the session_id must be previously returned by zillow_register_session, which is not in the schema, enhancing 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?

The description clearly states the tool switches the default session for subsequent calls, using the verb 'switch' and specifying the resource 'active session'. It distinguishes itself from sibling tools that are about property queries or other session operations like register.

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

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

The description explains when to use the tool: after registering a session, to set a default. It also notes that tools with an explicit session_id parameter override this default, providing context for when the tool is not needed. However, it doesn't explicitly state when not to use it, such as when a session is already active.

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