HouseData — Zillow data

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

Annotations already cover read-only, idempotent, and open-world behavior. The description goes beyond them by disclosing the output shape (region id, type, centre) and the kind of data Zillow knows (cities, ZIPs, neighborhoods, counties). This is genuinely useful since there is no output schema, and it does not contradict any 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 tight sentences with no filler. The first sentence defines the tool and its result; the second situates it in the search flow. Every phrase 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 an autocomplete-style lookup with annotated safety, the description is complete: it covers input intent, result contents, and how the result should be used downstream. The schema covers parameters, and the description covers the missing output-shape context that would normally come from an output schema.

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

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

Schema description coverage is 100%, so the parameter meanings are already fully documented in the schema. The description adds a little semantic color by naming the region types, but it does not materially improve on the existing parameter 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 identifies the resource exactly: regions known for a partial place name, including the concrete outputs (region id, type, centre). It also differentiates the tool from nearby siblings by framing it as the prerequisite for zillow_search_listings and the path to a regionId.

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 phrase 'What a search box needs before zillow_search_listings, and the way to a regionId' gives clear contextual guidance on when to use this tool. It names a related sibling and the intended flow, though it does not explicitly state when not to use it or list alternative tools.

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

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

Annotations already declare this as read-only, open-world, and idempotent, so the safety profile is covered. The description adds useful return-field context, but it does not disclose that the default compact form may omit photo and tour links (per the expand parameter). It does not contradict the annotations, but it misses an opportunity to clarify response-shape behavior for the default call.

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 one efficient, front-loaded sentence that packs resource, returned fields, and lookup modes without filler. It is slightly noun-phrase-like rather than an imperative sentence, but every clause carries useful 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 usefully enumerates the primary return fields: name, address, description, amenities, unit and floor-plan counts, rent range, and photos. It also explains both parameterization options. The main missing piece is an explicit note about the compact vs. expanded response controlled by the expand parameter, though the schema covers that.

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 value beyond the schema by stating that buildingId must come from a forRent search row with resultType propertyGroup and that lat/lng can serve as an alternative identifier. This helps the agent understand the relationship between the parameters without reading every schema detail.

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

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

The description clearly identifies the resource (a rental building) and the return fields, and it specifies the two lookup modes: buildingId or lat/lng. It does not use an explicit verb like 'get' or 'retrieve', but the 'by buildingId ... or by lat and lng' construction makes the action clear and distinguishes this from generic property or search 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 concrete context for when to call the tool: after obtaining a buildingId from a forRent search row with resultType propertyGroup, or when lat/lng are available. It does not name alternative sibling tools or explicitly state when not to use it, but the source-of-buildingId guidance is strong 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 declare readOnlyHint, openWorldHint, and idempotentHint, which cover the core behavioral traits (no side effects, repeatable). The description adds detail about the output content (fields included), but it does not disclose limitations such as maximum number of comps, ordering, or behavior when no comps exist. It neither contradicts nor substantially extends the annotation-provided safety profile.

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, compact sentence that front-loads the core purpose and then enumerates the returned fields. It contains no filler or redundancy. It could be slightly more structured (e.g., separating purpose from output details), but it is efficiently written and easy to parse.

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 does provide a useful field list, which is necessary for an agent to understand the shape of results. However, it omits structural context such as whether the response is an array, whether results are ordered, and whether 'expand' alters the fields listed. For a simple read-only tool with full schema coverage, it is adequate but not complete.

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

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

Schema description coverage is 100%, with both 'zpid' and 'expand' already described in the input schema. The description does not add any additional parameter meaning beyond what the schema provides. Baseline of 3 is appropriate because the schema fully carries the parameter documentation burden.

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

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

The description clearly identifies the resource ('comparable homes Zillow uses to value this one') and implies the verb 'return'. It is specific enough to distinguish from generic 'nearby homes' tools, though it does not name siblings explicitly. The phrase 'uses to value this one' grounds it in Zillow's valuation process, which is a unique angle.

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?

No guidance is provided about when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or when to choose zillow_nearby_homes or zillow_zestimate instead. An agent must infer usage from the name and description alone.

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 safety and idempotency are covered. The description adds real behavioral context by explaining that compact mode drops photo and tour links while expand true keeps them, and that cost is the same either way. No annotation 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 carry a large amount of useful information without fluff: the full output hierarchy and the compact/expand trade-off. The core resource 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?

With no output schema, the description does a good job enumerating the returned fields and the compact/expand distinction. The schema handles parameter semantics, though the description never explicitly states that callers must provide either buildingId or a lat/lng pair, since all parameters are optional in the schema.

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

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

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description mostly restates the expand behavior already documented in the schema and adds no new format, mutual-exclusivity, or source-guidance details for lat/lng or buildingId.

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 resource as floor plans of a rental building and enumerates the exact fields returned, including units and their availability. It is unambiguous and distinct from sibling tools, though it lacks an explicit imperative verb like 'retrieves' or 'lists.'

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 through the phrase 'Every floor plan of a rental building' and the focus on units, but it never explicitly says when to choose this tool over siblings such as zillow_building or zillow_search_listings. There is no when-not-to-use guidance or alternative routing.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds meaningful behavioral context: the null behavior when there's no active listing and a privacy warning about handling personal data. These go beyond the annotations and help an agent understand data sensitivity and 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?

Two dense sentences cover the full scope, the null case, and a privacy note without wasted words. The core purpose 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?

For a tool with no output schema, the description enumerates the key fields returned and the null-case behavior, which is sufficient for an agent to know what to expect. It doesn't describe error handling or response format beyond that, but for a single-record read tool with safe annotations, this is adequate.

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

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

Schema description coverage is 100% and both parameters (zpid, expand) have detailed descriptions. The tool description adds no extra parameter semantics beyond what the schema provides, so the baseline 3 applies.

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

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

The description clearly states the tool returns the listing agent's full profile (name, license, phone, email, website, brokerage, bio, social links, rating, review count) along with broker and MLS ID. It is specific about the resource ('listing agent's profile') and distinguishes from siblings like zillow_top_agents or zillow_property by focusing on the agent attached to a specific listing.

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 it: for a listed home (zpid required) and notes that agent fields are null when no active listing exists. However, it does not explicitly mention alternatives or when NOT to use it, leaving some ambiguity versus sibling tools like zillow_top_agents.

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

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

Annotations already cover read-only and idempotent behavior. The description adds useful behavioral details beyond annotations: results are newest first, limited to 100 months, and 'latest' contains the newest row of each series. This is meaningful context for invoking and interpreting results.

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 main output and then covers input and ordering constraints. There is no filler or redundancy that fails to earn 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?

Given the absence of an output schema, the description does a good job summarizing the returned series and the special 'latest' field. It does not mention the expand parameter or default months, but those are fully documented in the schema, so the description is reasonably complete for an agent to call the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the either/or relationship between location and regionId, but this is already implied by the schema's 'instead of location' text. No additional parameter semantics are provided beyond what the schema already states.

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 as providing monthly market statistics for a region and enumerates the specific metrics returned. It does not explicitly distinguish itself from sibling tools, but the content is specific enough that an agent can infer 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?

No guidance is given about when to use this tool versus siblings like zillow_region or zillow_property_facts. The instruction to provide location or regionId is input guidance, not tool-selection 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 establish readOnlyHint, openWorldHint, and idempotentHint. The description adds useful context by specifying the source ('as Zillow lists them') and that Zillow's tag is included, but it does not disclose response shape, aggregation behavior, or freshness caveats. There is no contradiction with annotations.

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

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

The description is a single, tightly written sentence with no filler. It front-loads the core purpose ('Today's mortgage rates') and then lists the exact data elements returned, making every word informative.

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 low-complexity tool with no required parameters, the description covers the main return contents: product, rate, APR, and tag. The absence of an output schema is partially mitigated by this enumeration. Minor ambiguity remains around what 'Zillow's tag' concretely looks like, but not enough to prevent 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 100%, so the single optional 'expand' parameter is fully documented in the schema. The description adds no parameter-level detail beyond that, but none is needed; the baseline of 3 is appropriate.

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

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

The description clearly states the tool returns today's mortgage rates with product type (30-year fixed, FHA, VA, 15-year, ARMs), rate, APR, and Zillow's tag. It is easily distinguished from all sibling tools, which concern properties, agents, schools, and market statistics rather than mortgage rates.

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 phrase 'Today's mortgage rates' clearly frames when this tool is relevant: when current mortgage rate information is needed. It does not explicitly name alternatives or exclusions, but among the siblings this is the only rates-focused tool, so the intended usage context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the agent knows this is a safe, non-mutating operation. The description adds only that it returns Zillow's list of nearby homes, with no additional traits like sorting or pagination. This doesn't contradict annotations, but it also doesn't add significant behavioral context beyond them.

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

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

The description is a single sentence that front-loads the purpose and output fields, with zero filler or redundancy. It is concise without sacrificing 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?

This is a simple read-only tool with one required parameter and full schema coverage. The description lists all key output fields, and annotations cover safety and idempotency. While it doesn't mention response shape details like list ordering or expand behavior, those are not critical for a tool this simple and are partially inferable from the schema.

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

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

Schema description coverage is 100%: both zpid and expand have clear descriptions in the input schema. The tool description does not add parameter-level meaning, but the schema carries that weight, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it returns homes Zillow shows near a given property, listing zpid, address, price, beds, baths, living area, and status. The phrase 'near this one' differentiates it from search_listings and comps, though it doesn't explicitly name a sibling.

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?

There is no explicit guidance on when to use this tool versus zillow_comps or zillow_search_listings. The description implies usage through 'near this one' but lacks any when-not-to-use context or alternative routing.

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

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

Annotations already carry the operational profile (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower. The description adds genuinely useful behavior beyond that: output is ordered with the hero photo first, and size=full expands each photo to every size Zillow serves. This is meaningful context, though edge cases like empty galleries are not covered. No contradiction with annotations.

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

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

Two sentences, roughly 30 words, with the core purpose and output shape front-loaded. The second sentence earns its place by explaining the size=full expansion behavior. There is no filler or redundant phrasing.

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?

This is a simple tool — one required parameter, read-only, idempotent, open-world — and the description covers the response shape while the schema documents all three parameters, including expand's compact/full tradeoff. No critical information for making a correct call is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's size=full sentence essentially restates the schema's own size description ('full to add every image size Zillow serves'), so it adds no new semantic information beyond what the schema already provides.

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

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

The description identifies the resource precisely — a home's photo gallery — and specifies the output structure (one URL per photo, in order, hero first). This scope clearly distinguishes it from siblings like zillow_floor_plans, zillow_price_history, and zillow_market_stats. The missing explicit verb ('returns') is a minor style issue that doesn't hurt clarity.

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 what the tool returns but never articulates when to choose it over alternatives. Usage is only implied by the tool name and the phrase 'photo gallery for a home'; no sibling is named and no conditions, exclusions, or decision rules are given.

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, covering safety and idempotency. The description adds behavioral detail: events are listed newest first and include price, change, and source. This goes beyond the annotations and gives the agent a sense of the response shape without contradicting any 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, tightly packed sentence that leads with the core purpose and immediately lists the event types, ordering, and key fields. There is zero fluff or redundant phrasing, making it easy to scan and understand quickly.

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 annotations cover safety and idempotency, and the schema fully documents both parameters, the description supplies the missing behavioral context: what events are included, the order, and the data fields returned. It does not describe pagination or limits, but for a read-only list tool this is sufficient. No output schema exists, but the description's field list provides the necessary guidance.

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 both zpid and expand having detailed descriptions. The tool description adds no additional parameter meaning beyond what the schema provides, so the baseline of 3 applies. It does not compensate for any gaps because there are none.

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 exactly what the tool returns: every listing, price cut, pending, sale, and delisting event for a home, ordered newest first, including price, change, and source. This clearly distinguishes it from siblings like zillow_tax_history or zillow_comps, which cover different data types. The verb is implicit but the resource and scope are 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 does not explicitly state when to use this tool versus alternatives. It implies use for price history data, but there is no guidance like 'use this for historical price events' or 'not for tax history.' The context is clear enough for a user who knows the domain, but no explicit exclusions or alternative routing are provided.

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 annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description's main added value is detailing response contents and approximate size (~17 KB). It also clarifies that every zpid has a record, whether listed or off market, which is useful behavioral context. No contradiction with annotations.

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

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

The description is dense but well organized, with the resource and scope stated up front and then cleanly labeled sections for compact vs expanded output. Every phrase contributes information, and there is no filler or repetition.

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

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

With no output schema, the description carries the burden of explaining what the tool returns, and it does so thoroughly by enumerating both the compact fields and the expanded additions such as history, schools, scores, nearby homes, and photos. The description is complete enough for an agent to decide when to invoke this tool and which mode to use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful detail beyond the schema by explaining what the compact form includes, what expand true unlocks, and that pricing is the same either way. This genuinely helps an agent decide how to set the boolean parameter.

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 target as the property record for any zpid, including off-market listings, and distinguishes it from specialized siblings by offering a full or compact record. It lacks an explicit retrieval verb like "gets" or "fetches" and does not name sibling alternatives, which keeps it from a 5.

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

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

It provides clear context: use the default compact form for the headline, or set expand true for the complete record. It explains the key decision point between the two modes, but it does not explicitly say when to prefer sibling tools such as zillow_property_facts or zillow_price_history, so exclusions and alternatives are missing.

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

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

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds contextual scope by listing the fact sheet contents and noting current status/price, but it doesn't disclose behaviors like missing fields, freshness, or response size. This is adequate but not rich behavioral disclosure.

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?

A single, front-loaded sentence states the core purpose immediately and then lists concrete examples. Every phrase earns its place; the enumeration is informative without being padded. No redundant restatement of the tool name or title.

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

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

For a simple read-only tool with one required parameter and an optional boolean, the description provides enough information for an agent to know what the call returns and what facts to expect. The expand parameter is documented in the schema, and annotations cover idempotence and read-only behavior. It does not describe output structure, but no output schema exists and the listed fields largely cover that.

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 zpid and expand are already well documented. The description adds only general context ('one home') and lists fact types, which maps loosely to the response but not to parameter handling. The baseline of 3 applies because the schema carries the parameter documentation burden.

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

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

The description identifies the resource as 'one home' and enumerates the fact categories (beds, baths, living area, etc.), making it clear this is a property-facts lookup. It lacks an explicit verb like 'retrieve' or 'get', but the noun-phrase phrasing still conveys an operation. It differentiates from siblings by emphasizing the full fact sheet for a single home.

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?

No when-to-use or when-not-to-use guidance is provided, and no alternative tools are named. With 18 siblings including zillow_property, zillow_comps, and zillow_nearby_homes, an agent is left to infer which tool to choose. The 'one home' phrasing implies a use case, but the description never explicitly states selection criteria.

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 useful behavioral context beyond those annotations by stating what fields are returned, including the exact bounding rectangle search uses. It does not contradict 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 compact and front-loaded, with no filler or redundant explanation. The em-dash structure is slightly awkward, but every segment contributes useful information about purpose, output, or input.

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

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

For a simple, read-only lookup with no output schema and fully documented parameters, the description adequately covers what the tool returns and how to invoke it. It does not discuss failure or ambiguity behavior when a place name does not resolve, but that is a minor gap given the tool's simplicity.

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

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

Schema coverage is 100% and the schema already describes both location and regionId, including the anyOf relationship. The description's 'Give location or regionId' only restates this relationship and adds no new parameter-level 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 clearly states the tool resolves a place name to a Zillow region and enumerates the returned data: id, type, parent state and city, centre, and the bounding rectangle used by search. It also covers the reverse path, describing a region given a regionId. It does not explicitly differentiate itself from sibling tools, so it falls short of a 5.

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

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

The imperative 'Give location or regionId' offers invocation guidance, and the lookup purpose implies when it would be appropriate. However, there is no explicit when-to-use versus sibling tools like zillow_autocomplete_places or zillow_property, and no mention of caveats 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds useful context about the data content (school name, level, grades, distance, rating) but does not disclose any further behavioral traits such as return shape, behavior when no schools are assigned, or data freshness.

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 compact sentence that conveys the core purpose and the main returned fields without redundancy. Every element earns its place and the key association with a specific home is front-loaded.

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

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

For a simple read-only tool with only one required parameter and no output schema, the description explains what the caller will receive: school assignments with name, level, grades, distance, and rating. It is complete enough for an agent to know when and how to use it, though it could note that results are tied to a single zpid or address potential absence of assigned schools.

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 zpid and expand already well documented in the schema. The description does not need to add parameter detail, and it does not add anything beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states the resource clearly: schools assigned to a home, and enumerates the returned fields (name, level, grades, distance, GreatSchools rating). It is distinguishable from siblings like zillow_scores or zillow_property_facts, though it does not explicitly contrast itself with them or use a direct verb like 'gets'.

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 context is implied: use this when you need the schools assigned to a particular home, identified by zpid. However, it provides no explicit when-to-use guidance, no exclusions, and does not mention alternatives among the many 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 disclose the read-only, idempotent, and open-world nature of the call. The description adds only the detail that each score comes with a description, plus the 'home's location' scope. There is no contradiction and no need to restate safety traits, but no extra behavioral context such as data sources or missing-data behavior is provided.

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?

A single sentence, front-loaded with the three score types and ending with the relevant scope. No filler, no repetition of schema details, and every phrase 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 lookup with one required parameter and no output schema, the description conveys what the agent gets (three scores plus descriptions). It does not specify score ranges or how missing scores are handled, but those are minor for a tool of this simplicity.

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 fully documents zpid and expand. The description adds no real parameter meaning beyond clarifying the scores are for a home's location, which is a modest extension of the schema's 'Zillow property 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 clearly names the resource (Walk Score, Transit Score, Bike Score) and ties it to a home's location, which separates it from most sibling tools. It lacks an explicit verb like 'returns' or 'retrieves,' so it reads as a noun phrase rather than a full operational statement.

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 phrase 'for a home's location' gives some context: the tool is appropriate when the agent already has a home or zpid and wants neighborhood mobility scores. It does not state when to prefer this over related Zillow tools or mention any exclusions, so the usage guidance remains implied rather than explicit.

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 meaningful behavioral context: rental results come as buildings or homes, pagination caps at 1,000 total, and the daysOn sort with sortAscending gives newest first. These go beyond the annotations and help the agent anticipate output structure and sorting semantics.

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

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

The description is dense but well-organized: core purpose first, then row details, pagination, rental behavior, and sorting. Every sentence carries information; there is no fluff. While it is a bit long, the structure front-loads the most critical usage context and then provides operational details, making it efficient for an agent to parse.

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 8 parameters and no output schema, the description is remarkably complete. It covers return fields, pagination limits, rental result grouping, sort behavior, and the expand option. It also explains the relationship between location and regionId. Nothing essential for calling the tool correctly is missing, given the detailed schema and annotations.

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

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

Schema coverage is 100%, so each parameter has a description. The description adds extra semantic value by explaining the interaction between sort and sortAscending (daysOn + ascending = newest first), the 1,000-per-search limit (page x pageSize), and the expand option's size implications. These clarifications are not obvious from the schema alone, raising the score above the baseline of 3.

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

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

The description states a specific verb (search) and resource (listings) with clear scope: place types (city, ZIP, neighborhood, county) and statuses (for sale, for rent, sold). It distinguishes itself from siblings like zillow_property (single record) and zillow_autocomplete_places (place lookup) by focusing on listing search results. The detail about row fields and pagination further clarifies the tool's exact function.

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 this tool: to find listings across multiple statuses and place types. It mentions rental grouping (buildings vs. homes) which hints at edge cases. However, it does not explicitly state when not to use it or name alternative tools (e.g., use zillow_property for a specific zpid). The guidance is clear but lacks explicit exclusions or comparisons to 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 carry readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds that the output consists of assessed value and tax paid per year, which is mildly informative, but it does not describe response structure, pagination, or any edge-case behavior. It adds some value without contradicting the annotations.

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

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

A single sentence that leads with the core data returned (assessed value and tax paid) and ends with a scope qualifier. Every word earns its place; there is no fluff 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?

For a simple read-only lookup with two fully documented parameters and no output schema, the description adequately tells the agent what it will receive. The only missing piece is an explicit statement of the required input (zpid), but that is already enforced and documented in the schema, so the description does not need to repeat it.

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

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

Schema coverage is 100%, with zpid and expand fully documented in the schema. The description does not add parameter-level detail beyond what the schema provides, so the baseline score of 3 applies. No param information is missing.

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

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

The description names the resource ('Assessed value and tax paid by year for a home') and the scope ('as far back as Zillow records them'), which distinguishes it from sibling tools like zillow_price_history (sales prices) and zillow_zestimate (estimated value). It lacks an explicit verb like 'retrieve' or 'get', but the meaning 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?

No guidance is given about when to choose this tool over alternatives such as zillow_price_history or zillow_property_facts. The phrase 'as far back as Zillow records them' hints at historical data but does not state usage conditions or exclusions. An agent must infer when this is the right 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 provide readOnlyHint and idempotentHint, and the description adds valuable behavioral context: the ranking basis (past-year sales) and the specific fields returned. It does not mention pagination or list limits, but the safety profile is already covered by 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 short sentences carry the full product concept with no filler. The key ranking idea and output contract are front-loaded, and the final phrase is memorable rather than redundant.

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

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

With no output schema, the field list in the description is a useful substitute for return-value documentation. The only weakness is the slightly ambiguous 'sales in this price range,' but overall the description plus schema and annotations give an agent enough to call 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 zpid and expand, so the description does not need to repeat parameter details. It reinforces that zpid refers to a home, but adds no new parameter-level semantics beyond the schema.

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

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

The description clearly identifies the resource: agents ranked around a home by sales, and enumerates the expected output fields. The coda 'Who actually sells here' captures the purpose in a way an agent can confidently distinguish from listing-agent or property lookups.

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 phrase 'around a home' and 'who actually sells here' makes the intended use case clear: get the local agent landscape for a property. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough to guide 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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond annotations: it returns null where Zillow publishes no Zestimate, explicitly does not fabricate an estimate, and describes the monthly history cadence. No contradiction with annotations.

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

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

Two sentences with no filler. The central resource is front-loaded, the returned data is organized in a clear list, and every clause adds either precision or behavioral 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?

There is no output schema, so the description carries the full burden of explaining return content. It enumerates the key fields, explains the null behavior, and clarifies the history span. Nothing an agent needs to decide whether to call the tool is missing.

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

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

Schema description coverage is 100%, and both parameters (zpid and expand) are already well documented in the input schema. The description adds no parameter-level meaning, but it does not need to because the schema fully carries that burden.

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

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

Although phrased as a noun phrase rather than an imperative, it unambiguously identifies the resource: the Zestimate for a given zpid, including value range, value 30 days ago, rent Zestimate, zestimate history, and price history. The phrase 'for any zpid, listed or not' clearly separates this tool from listing/search-oriented 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 gives a clear usage condition: use this when you need Zestimate data for any zpid, whether or not the property is currently listed. It does not explicitly name sibling alternatives or when-not conditions, so it falls short of full routing guidance, but the scope is clear.

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