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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses substantial behavior: per-target error capture, ~6 in-flight server-side concurrency, retry-once-on-timeout, a hard deadline, and retryable pending status rows. This gives the agent accurate expectations about failure modes and partial 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 dense but every sentence earns its place: capability, target forms, output relation, error behavior, concurrency, timeout semantics, and usage guidance are all covered without filler. The most important facts are 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?

Given the readOnly annotations and rich schema, the description covers what an agent needs to select and invoke the tool: batch size, target formats, response relationship to redfin_get_property, error isolation, retry behavior, pending status semantics, and the comparison-tool alternative. No critical gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning to the targets parameter: it clarifies the three accepted target forms, explains internal redirect resolution for property_id, and notes that pairing with listing_id is fastest. This is practical routing information not present in the schema.

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

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

The description opens with a specific verb and resource: 'Fetch up to 200 Redfin property records in a single tool call.' It distinguishes itself from siblings by stating it returns the same per-property record shape as redfin_get_property but without a summary table, and explicitly names redfin_compare_properties for that alternative.

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

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

The description gives explicit when-to-use guidance: 'Use this when you have a list of saved homes / candidate properties and need the full structured data for every one of them.' It also names the alternative for summary comparison and implies the distinction from single-record fetching.

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?

Discloses it uses canonical 'realty-core' engine, is pure local math with no network, and outputs constraint breakdown. Adds behavioral context beyond annotations (idempotentHint, readOnlyHint) 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?

Four well-structured sentences front-load purpose, list inputs/outputs, and add engine/network context. 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 10 params and no output schema, description provides solid coverage of inputs and expected outputs. Could detail output format more, but mentions price, constraint, and PITI breakdown sufficiently.

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

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

With 0% schema descriptions, description lists most inputs (income, debts, down payment, rate, tax, insurance, HOA, loan term). Omits front_end_dti/back_end_dti but references 28/36 rule, implying defaults. Adds meaning beyond raw property names.

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 solves for max affordable home price using 28/36 DTI rule. Distinguishes from sibling redfin_calculate_mortgage (monthly payment vs price) and search tools. Uses specific verb 'Solve for' and specifies resource 'max home price'.

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?

Describes use case for affordability based on income/debts, implying for given-price payment calculations use mortgage tool. No explicit when-not-to-use or alternatives list, but context is clear enough.

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

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

Description adds value beyond annotations (readOnlyHint, idempotentHint) by explaining no network call, deterministic behavior, and PMI applicability. 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?

Four focused sentences, each providing essential information. Front-loaded with purpose, 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?

Covers all key behaviors and parameters despite 10 parameters and no output schema. Could mention default loan term, but schema already provides default.

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 40%, but description clarifies relationships (down_payment vs. percent, property tax options, PMI condition). Compensates well for missing 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?

Clearly states it is a local mortgage calculator returning a full PITI breakdown. Distinct from all sibling tools, which focus on property searches, market reports, etc.

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 notes it is deterministic and safe for scenario comparison without network calls. Does not state when to avoid use, but context is sufficient for selection as the only mortgage 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 annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds valuable behavioral context beyond them: individual property errors are captured per-row, calls are concurrent, the raw marketing description is omitted by default, and include_summary duplicates ~30% of response weight. 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?

Every sentence earns its place: core purpose and range are front-loaded, then selection guidance, then optional flags with their tradeoffs, then error/concurrency behavior. There is no filler, tautology, or redundant restating of the schema.

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

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

With no output schema, the description compensates thoroughly by enumerating key returned fields, explaining default response shape, describing per-row error handling, and noting concurrency. An agent has enough context to call the tool correctly and anticipate response size and failure behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real semantics beyond the schema: targets may be a url OR a property_id+listing_id pair, include_summary has a quantified response-weight tradeoff, and include_description defaults off. Only the view parameter's behavior is left to the schema, which is acceptable given full coverage.

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

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

The description opens with a specific verb and resource: 'Fetch and compare 2 to 25 Redfin properties side-by-side.' It states the accepted target formats (url or property_id+listing_id), names the return fields, and clearly distinguishes itself from redfin_bulk_get and other siblings.

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

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

It explicitly directs non-side-by-side or >25-property workflows to redfin_bulk_get. It also gives actionable guidance on when to set include_summary and include_description, including the context-cost tradeoff, so an agent can make a well-informed invocation decision.

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, idempotentHint) cover safety; description adds context on aggregation and per-URL transparency. No contradictions. Slightly more detail on return format would push to 5.

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

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

Three sentences, front-loaded with purpose and usage. Every sentence adds value. No wasted words.

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

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

Complete for a simple tool with one fully described parameter, no output schema, and clear annotations. Description explains return values and usage context adequately.

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 already fully describes the single parameter (sample_urls: array of 2-10 URLs). Description reinforces but adds no new details beyond what schema provides. Baseline 3.

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

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

Description clearly states the tool fetches climate risk for representative URLs and returns averaged baseline values with cluster_id. Distinguishes from sibling tools like redfin_get_climate_risk (per-property) and redfin_get_climate_risk_bulk.

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

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

Explicitly advises using this before fanning out per-property calls to avoid redundant fetches if cluster agrees. Also mentions limitations (no landslide coverage). Clear when-to-use and 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 provide readOnlyHint, openWorldHint, idempotentHint. The description adds significant context: the 3-rung resolution ladder, matched_via values, graceful degradation with resolved: false, address discrepancy conflicts via address_alternates field, and that no auth is required. 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 that front-loads the main purpose, then details the algorithm, edge cases, and usage guidance. Every sentence adds essential information without redundancy. It is concise yet comprehensive.

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?

The description covers the resolution algorithm, return values (URL, home_id, matched_via, address_alternates), graceful degradation, and when to use. No output schema exists, so mentioning key return fields is helpful. It could be slightly stronger by fully specifying the output structure, but overall it is complete for the tool's complexity.

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 3. The description adds value by clarifying that city/state/zip are optional, explaining their role in the search fallback step, and calling the address 'free-text'. This helps the agent understand parameter optionality and fallback behavior 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 specifies the verb 'Resolve' and the resource 'address', and explains the outcome: canonical URL and home_id. It distinguishes from siblings like redfin_resolve_addresses by focusing on a single address resolution with a detailed algorithm.

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

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

The description explicitly states when to use: 'Use this when you have a property address and need its Redfin home_id for follow-on calls.' It also mentions read-only nature and no auth. However, it does not explicitly contrast with alternatives like redfin_resolve_addresses for bulk, though the singular vs plural hints at it.

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

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

Discloses source (Redfin HTML, no API), response shape (including `available: false` reasons), and performance tips (cluster_id grouping). Annotations already indicate read-only and idempotent, and description adds valuable 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?

Well-organized with clear sections (covered risks, exclusions, response shape, source). Some redundancy (e.g., 'DOES NOT COVER' appears twice), but overall efficient and 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?

With no output schema, description fully explains response structure, error reasons, and data source. Covers all necessary context for an agent to invoke correctly and interpret results.

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

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

Schema already describes the url parameter with 100% coverage. The description adds context about accepted formats (full URL or path) and examples, but the schema is already sufficient; slight extra value.

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

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

The description clearly states the tool retrieves First Street Foundation climate risk scores for a property, listing covered risk types (flood, fire, heat) and explicitly excluding landslide, which distinguishes it from other 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?

Provides explicit guidance: use for climate risk, excludes landslide (referencing alternatives), and suggests leveraging cluster_id to avoid redundant fetches. Also explains how to construct the URL.

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), description adds: server-side concurrency (~5 fetches), per-row error capture, output order preservation, and batch size limit. 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?

Six sentences, each serving a distinct purpose: purpose, output shape, error handling, concurrency, usage scenario, limitations. No redundancy, front-loaded with main action.

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?

Single parameter is fully explained; behavior (error handling, concurrency, order) and limitations are covered. Output shape is referenced to another tool, which is acceptable. No output schema, but sufficient for a bulk fetch 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?

Input schema already covers parameter fully (with description). Description restates batch limit and adds error handling context but no new semantic constraints beyond schema. Baseline 3 as schema coverage is 100%.

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

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

Description clearly states verb 'Fetch' and resource 'climate risk for up to 100 property URLs'. It differentiates from sibling `redfin_get_climate_risk` by specifying bulk nature and output shape consistency.

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?

Description explicitly says 'Use this when batching ~60-property workflows where climate risk is the dominant cost.' It also notes limitations from per-property tool apply, guiding when not to use. Could be more explicit about single-query alternatives but sufficient.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds that it returns nearby active rental listings with specific fields, giving good transparency. No contradictions.

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

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

The description is concise (3-4 sentences), front-loaded with purpose, and every sentence adds value. 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?

For a tool with 5 params and no output schema, the description explains inputs, outputs, and typical use. It could mention result limits or pagination, but overall 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 coverage is 40% with descriptions on two parameters. The description mentions the parameter group (rent estimate range, lat/lng, propertyId) but adds little beyond the schema. It does not compensate for undocumented parameters.

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

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

The description clearly states it finds nearby rental comparables, specifies the output fields, and distinguishes from sibling tools like redfin_get_property and redfin_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?

It provides context on when to use the tool (estimating rent, finding rentals) and mentions inputs are typically from redfin_get_property, but does not explicitly exclude alternative tools or scenarios.

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

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

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description reveals the exact output structure for each metric, warns about empty data for neighborhoods, and confirms safety for repeated calls. This provides comprehensive behavioral insight.

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: first enumerates returned metrics, second explains parameter options, third details output format. No extraneous content, front-loaded with purpose, and logically ordered.

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 4 parameters (0 required), 100% schema coverage, no output schema, and straightforward return type, the description covers all necessary aspects: what the tool returns, how to invoke it with both region identification methods, and output format. No gaps identified.

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

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

Schema coverage is 100%, but the description adds practical guidance: location free-text with autocomplete, recommendation to use city names, warning about neighborhoods, and default for property_type. These enrich understanding beyond basic schema types.

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 a market report for a Redfin region with specific metrics: median prices, $/sqft, sale-to-list ratio, homes for sale/sold, and year-over-year/month-over-month changes. It distinguishes from sibling tools like redfin_search_properties or redfin_get_property by focusing on aggregated market data rather than 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?

The description provides two ways to specify the region (location free-text or region_id+region_type), notes that neighborhoods often return empty data, and mentions the default property_type. It does not explicitly state when not to use this tool (e.g., for single property queries), but the context of being a market report heavily implies that.

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 it as read-only, idempotent, open-world. The description reinforces this with 'safe to call repeatedly' and describes the output structure (date, event, price, days-on-market, source) plus tax history, adding useful 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?

Four sentences, front-loaded with purpose, no redundancy. Every sentence adds value: what data is returned, input options, read-only safety.

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, but description adequately explains return values (date, event, price, days, source, tax history). Missing details on conflict resolution (e.g., if both url and property_id supplied) but sufficient 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 covers 3 parameters but only url has a description (33% coverage). The description compensates by explaining the logical grouping: 'Provide either url or property_id+listing_id,' which adds critical usage semantics not in the schema.

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

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

The description clearly states the tool retrieves 'listing-price events for a property' and details the contents of each entry. It distinguishes from siblings by specifying the unique data (price history, tax history) and input methods (url or property_id+listing_id).

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 input guidance: 'Provide either url or property_id+listing_id.' Also states 'Read-only; safe to call repeatedly.' While it doesn't compare to all alternatives, the context is clear enough for selecting this tool over siblings.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description reinforces this with 'Read-only; safe to call repeatedly' without contradicting them. It goes well beyond annotations by disclosing non-obvious behaviors: lot_size is null (never 0) for condos, primary_photo_url is dropped on the default compact view, the marketing description is omitted by default, and the internal resolution chain (initialInfo endpoint, /home/<id> redirect) is laid out. 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?

Front-loaded with the core purpose and organized in a logical progression: purpose, input modes, return fields, edge cases, view behavior, opt-in flags, safety. It is dense and every sentence carries information, but at roughly 200 words it tests the upper bound of conciseness, and the closing 'Read-only; safe to call repeatedly' partially duplicates what the annotations already state.

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 must document return values itself — and it does, listing core fields plus derived fields (lot_size_acres, price_drop_*, hoa_monthly_usd, last_sold_*, tax_annual, extracted_features). It also covers edge cases (null lot size, dropped photo URL, omitted description), the include_* opt-ins, and sibling alternatives, leaving almost nothing for an agent to guess. The only omission is error behavior for invalid inputs, which is minor 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% and the schema's own per-parameter descriptions are already rich (e.g., the view enum and property_id resolution notes), so the baseline is 3. The description adds genuine value on top by explaining the cross-parameter resolution modes — which combination is fastest and which endpoint each hits — and by tying the include_* flags to specific response fields and sibling round trips. This is above baseline but not a 5 because per-parameter semantics are largely carried by 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?

Opens with a specific verb+resource statement — 'Fetch a property's full Redfin record' — and the body distinguishes this tool from siblings by naming redfin_get_property_photos for galleries and redfin_get_price_history for price-history follow-ups. The three input modes (url, property_id alone, property_id+listing_id) further pin down exactly what this tool does and how it resolves records.

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 enumerates when to use each of the three input modes and labels the trade-off: 'property_id + listing_id — fastest, skips resolution.' It names alternatives with their conditions — 'use redfin_get_property_photos for the whole gallery' and 'Saves a follow-up redfin_get_price_history round trip — use this when a workflow needs both' — giving an agent clear decision 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 and idempotentHint, and the description reinforces 'Read-only; safe to call repeatedly.' It adds behavioral context by explaining the URL resolve step and the possibility of count=0 for off-market listings, providing transparency beyond the annotations.

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

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

The description is extremely concise, using two efficient sentences to convey all essential information. It front-loads the purpose and then details parameters and return structure without unnecessary words, earning 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 the absence of an output schema, the description fully explains the return format ({ property_id, listing_id, count, photos }) and mentions the content of each photo entry (multiple sizes, thumbnail, caption). It also covers edge cases (count=0) and security (read-only). This is complete for the tool's complexity.

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 meaningful context by explaining the logical grouping of parameters: 'Provide either url or property_id+listing_id' and clarifying the resolve step. This enhances understanding beyond the individual 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 clearly states the tool retrieves the full photo gallery for a Redfin property, specifying the return values (CDN URLs at multiple sizes, thumbnail, caption) and distinguishing it from sibling tools like redfin_get_property that return property details. The verb 'get' and noun 'photo gallery' are specific and 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 explicitly directs how to specify the property (via url or property_id+listing_id) and notes that off-market listings may return count=0. It includes a read-only note indicating safe repeated calls. While alternatives are not explicitly listed, the context makes it clear when 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?

Annotations already declare readOnlyHint and idempotentHint, which the description echoes. Beyond that, it adds the auth prerequisite ('Requires the user to be signed in') and summarizes the returned fields, which is useful behavioral context not present in 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?

Three short sentences, each carrying distinct information: what the tool returns, what fields are included, and the auth/safety profile. No filler or redundant restatement; the most important scoping information comes first.

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 list tool with one optional parameter and no output schema, the description is complete: it states the resource, return fields, authentication requirement, and safety. There are no obvious gaps that would prevent an agent from invoking it correctly.

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

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

Schema description coverage is 100%, and the single 'view' parameter already has a detailed explanation of compact vs. full responses. The tool description adds no additional meaning about this parameter, so the baseline score 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 identifies the resource (the signed-in user's favorited homes on redfin.com) and the action (returns them). The phrase 'favorited homes' distinguishes this from sibling tools like redfin_get_saved_searches, and the listed return fields make the tool's scope concrete.

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

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

The description gives clear context: this is for the signed-in user's own saved homes and requires authentication. It does not explicitly name alternatives or state when not to use it, but the scope is specific enough that an agent can route appropriately.

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

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

Beyond the annotations, the description discloses authentication requirements, the source of the data, the empty-array behavior, and explicitly confirms read-only/idempotent behavior. This is exactly the kind of contextual behavioral information an agent needs that the annotations do not fully express.

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

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

The description is compact and front-loads the main purpose, then adds entry shape, auth requirement, empty behavior, and safety. The final 'Read-only; safe to call repeatedly' partially duplicates the readOnlyHint and idempotentHint annotations, but the redundancy is minor and the overall size is well calibrated.

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 one-optional-parameter read-only tool with no output schema, the description is complete: it defines the return entry shape, explains the empty result, flags authentication, and identifies the data source. Nothing critical to calling the tool correctly appears to be 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 the view parameter is already thoroughly documented in the schema with compact/full semantics and caveats. The tool description adds no additional parameter-level meaning, which matches the baseline of 3 for high schema coverage.

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 exact resource: the signed-in user's saved searches on redfin.com, sourced from the saved-searches page HTML. This is a specific verb-plus-resource statement that makes the function's job unambiguous. It does not explicitly contrast with redfin_get_saved_homes, but the resource name itself is distinctive enough to avoid serious confusion.

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

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

The description gives clear context for when to call this tool: when you need the current signed-in user's saved searches, and it notes the signed-in prerequisite. It also says what happens when there are none, which is useful operational guidance. It does not mention alternatives or exclusions, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by specifying the return fields (sessions and active_session_id) and the null case for no sessions, providing behavioral edge-case info not 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 sentences, zero wasted words. The main action is front-loaded, and key details (edge case) are provided concisely.

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 parameters and no output schema, the description covers the essential behavior and edge cases. Could briefly mention relationship to session registration/setting, but not required for completeness.

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

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

No parameters exist, so schema coverage is 100%. Per guidelines, 0 params defaults to baseline 4. Description adds no parameter info (unnecessary) but is clear.

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 full set of registered sessions and the current active_session_id, with explicit edge-case behavior (empty sessions and null active_session_id). It distinguishes itself from sibling tools like redfin_register_session and redfin_set_active_session by focusing on retrieval.

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 on when to use this tool versus alternatives. Does not mention prerequisites (e.g., requiring an active session) or scenarios where this is preferred over other session-related 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?

The description discloses much beyond annotations: it is read-only, requires no auth, performs a round-trip through the bridge, and returns specific diagnostic categories. It also explains the failure-mode hint, helping the agent interpret results. No contradiction with the readOnlyHint/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 front-loaded with the action and purpose, then lists the diagnostic outputs, then gives usage guidance. Every sentence adds value, and the length is appropriate for a healthcheck tool with no parameters and no output schema.

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 enumerates the diagnostic fields returned: role, port, version, extension link state, elapsed time, and human-readable hint. It also explains how to interpret the failure categories, making the tool fully usable without external 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?

The tool has zero parameters, so there is no schema burden to compensate for. The description adds relevant input context by stating no auth is required and that the URL is fixed, making the no-input nature clear.

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

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

The description names a specific verb and resource: round-tripping a public /robots.txt URL through the fetchproxy bridge. It clearly differentiates this diagnostic tool from the surrounding Redfin property tools by focusing on bridge health rather than real estate 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?

It explicitly states when to call the tool: 'Call this when a real tool fails and you want to know which hop broke.' It does not enumerate when not to use it or list alternative diagnostics, but the context is clear enough for an agent to make the right 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?

The description adds behavioral context beyond annotations: it states that re-registering updates rather than duplicates, and explains the default active session behavior. Although annotations include 'idempotentHint: true', the description clarifies the update semantics. No contradictions with annotations.

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

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

The description is four sentences, each serving a purpose: registration action, update behavior, return value, and active session handling. It is front-loaded with the key verb and resource, and 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 the simplicity of the tool and the absence of an output schema, the description covers all necessary aspects: registration/refresh mechanism, session identity, active session management, and return value. It is fully adequate for an AI agent to use correctly.

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

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

Schema coverage is 100%, but the description significantly adds meaning: it explains that 'account_identity' is the key for session identity, clarifies the effect of re-registration, and describes how 'mark_active' works. It also explains the return value 'session_id' which is not in the schema.

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

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

The description clearly states that the tool registers or refreshes an authenticated Redfin session, using specific verbs and resource identification. It distinguishes itself from sibling tools like 'set_active_session' and 'get_session_context' by focusing on session creation/update and identity keying.

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

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

The description provides clear context on when to use: for registering or refreshing sessions to route per-tool calls. It explains the behavior of re-registering and setting active session, but does not explicitly state when not to use or directly compare to the sibling 'set_active_session' 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?

Beyond the readOnly/idempotent/openWorld hints, the description adds substantial behavioral detail: output order preservation, `resolved: false` for no-match, distinct retryable statuses (timeout/bridge_down/pending), per-row retry-once-on-timeout, server-side concurrency ~6, a hard overall deadline, and a pending count for selective re-runs. This far exceeds what the annotations alone convey and matches the read-only/idempotent hints 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 information-dense and front-loaded with the core action, but not maximally concise. Every sentence adds value, but details like 'server-side concurrency ~6 in flight' are non-essential for invocation and could be trimmed. Overall structure is strong and readable.

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 having no output schema, the description covers the essential invocation context: input format and limits, batch behavior, failure semantics, retry policy, deadlines, and the intended follow-on use case. It even tells the agent what to do with pending results ('re-run just those'). This is complete enough for correct selection and 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%: the `addresses` array and `view` enum are fully documented in the schema. The description only restates the input shape ('string or a structured {street, city, state, zip} object') without adding new parameter-level semantics. 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 opens with a specific verb and resource: 'Resolve up to 100 free-text street addresses to Redfin canonical home URLs + home_ids in a single tool call.' It clearly distinguishes this bulk resolver from sibling tools like redfin_search_properties and redfin_get_by_address by framing it as a bulk batch operation that collapses a multi-call flow into one trip.

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

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

The description explicitly states when to use it: 'Use this when you have a list of properties from another system (Compass, MLS, spreadsheet) and need their Redfin handles for follow-on calls.' It also contrasts with the 'typical 6-search-call + 15-resolve flow,' providing clear context. It does not explicitly spell out when-not-to-use or name alternative sibling tools, so it misses the full 5.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses location resolution via autocomplete and gis API, the short-circuit behavior for addresses, the coverage field, result_cap_hit, ZIP error handling, and explicitly states 'Read-only; safe to call repeatedly.' No contradictions with annotations.

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

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

The description is six sentences, each providing unique value. It front-loads the main purpose and progressively adds detail. Minor redundancy (e.g., 'Search Redfin listings' in title and description) could be trimmed, but overall well-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 8 parameters and no output schema, the description covers return fields, edge cases (cap hit, ZIP error, status limitation, coverage scenarios), and read-only safety. It is comprehensive for the tool's complexity.

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 50%; the description does not explicitly detail each parameter but mentions 'optional filters' and references price/beds filters for narrowing cap hits. It adds meaning by explaining the location parameter's resolution behavior and the status limitation. However, it could individually describe price_min/max, beds_min, baths_min to fully compensate for the missing schema descriptions.

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

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

The description clearly states the tool's purpose: 'Search Redfin listings by location... and optional filters.' It specifies the verb (Search), resource (Redfin listings), and provides differentiation from siblings by noting location resolution via autocomplete and gis API, and that full addresses short-circuit.

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

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

The description provides explicit usage guidance, including when to use a full street address (short-circuits, returns single home), when to narrow filters (result_cap_hit signals ~350 cap), and limitations (v0.1.0 supports for_sale only, ZIP fallback errors). It implicitly differentiates from alternatives like redfin_get_by_address for profile_only coverage.

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 idempotentHint=true and readOnlyHint=false. The description adds that this tool sets the default routing for subsequent calls, providing useful behavioral context beyond the annotations.

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

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

The description is two sentences with no wasted words. The main purpose is stated first, making it 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?

For a simple tool with one parameter and no output schema, the description explains its purpose, how to use it, and its interaction with other tools. It is fully complete.

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

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

Schema coverage is 100% and the description adds the crucial context that session_id must be previously returned by redfin_register_session, which the schema's description does not provide.

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 'Switch' and the resource 'active session'. It distinguishes itself from sibling tools like redfin_register_session (creates a session) and redfin_get_session_context (gets context).

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 specifies that the session_id must come from redfin_register_session and notes that explicit session_id parameters override the default. It provides clear context but does not explicitly state when not to use it.

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