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

The description goes well beyond the read-only/idempotent annotations by disclosing per-target error capture, retry-once-on-timeout behavior, ~6 concurrent requests, a hard overall deadline, and the pending-status fallback for slow or hung rows. This gives the agent an accurate model of batch failure and retry 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 long but every sentence contributes behavioral or routing information, and the core purpose is front-loaded. It is dense and somewhat run-on, but not bloated or redundant.

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

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

For a complex bulk tool with no output schema, the description covers the essential runtime contract: input shapes, per-record output parity with redfin_get_property, error isolation, concurrency, timeout handling, and retry semantics. The summary-table distinction and explicit use case complete the picture.

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 semantics around the targets array by explaining the three accepted target forms, the internal resolution path for property_id, and that pairing property_id with listing_id skips resolution for speed. It does not need to repeat the schema's detailed view and include_description docs.

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 clear verb and resource ('Fetch up to 200 Redfin property records') and immediately differentiates itself from siblings like redfin_get_property and redfin_compare_properties by noting the same per-property record shape but no summary table. The batch aspect is explicit 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?

It explicitly says when to use the tool: 'when you have a list of saved homes / candidate properties and need the full structured data for every one.' It also routes the agent away from the tool for summary tables by pointing to redfin_compare_properties, and implies single-record use belongs to redfin_get_property.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld=false), and the description reinforces this with 'No network — pure local math' and, importantly, describes the return structure (max price, binding constraint, PITI breakdown) that has no output schema. Adds real value 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?

Front-loads the purpose, then inputs, outputs, and a local-math note; every sentence is informative. The 'Same math across the realty MCP cohort' line is marginal filler but does not derail structure.

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

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

For a 10-parameter tool with no output schema, the description adequately covers inputs, the deterministic local behavior, and the return shape. It is complete enough to invoke correctly, missing only explicit alternative-selection 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?

With 60% schema coverage, the description compensates by enumerating the undocumented parameters (down payment, HOA, insurance) and framing the DTI caps via the 28/36 rule. It adds meaning beyond the raw schema without fully documenting every field.

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

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

States a specific verb+resource ('Solve for the maximum home price you can afford') scoped by the 28/36 DTI rule, so the agent immediately knows what computation it performs. However, it never differentiates from the close sibling redfin_calculate_mortgage, leaving the agent to infer the distinction.

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

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

Usage is only implied by the input/output enumeration; there is no explicit 'use this when...' guidance nor any mention of when to prefer redfin_calculate_mortgage instead. Adequate context but no routing help.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the description's added value is the operational detail: no network call, fully deterministic, and the conditional PMI logic (auto-applies when LTV > 80% and pmi_rate is provided). It does not describe error behavior or loan-term edge cases, but it goes meaningfully 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?

Dense but front-loaded: what it is, what it returns, why it is safe, then the parameter rules. Every sentence carries information, though the parameter-rules block is a little packed and could be broken up for scannability.

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

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

For a 10-parameter tool with no output schema and 40% schema coverage, the description covers the return structure (PITI components + total interest) and the key parameter ambiguities. Gaps are minor — permissions/edge-case behavior are irrelevant for a pure local computation.

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

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

Schema coverage is only 40%, so the description has to compensate, and it does: it declares the down_payment/down_payment_percent mutual exclusivity, the down_payment 20% default, and the property_tax_annual vs property_tax_rate duality. It leaves hoa_monthly, insurance_annual, and loan_term_years semantics to the schema, but the ambiguous pairs are resolved.

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

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

States a specific verb and resource ('mortgage payment calculator') and immediately qualifies it as local-only and deterministic, which separates it from the network-backed siblings like redfin_calculate_affordability and redfin_get_property. The return contents (PITI + total interest) are named, so an agent knows exactly what it 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?

It gives a clear context for use ('safe to use for scenario comparison without burning a fetch'), which tells the agent when this tool is preferable to a network fetch. It stops short of explicitly naming the nearest alternative (redfin_calculate_affordability) or stating exclusions, so it is strong but not fully 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, but the description adds substantial behavioral context beyond that: per-row error statuses (ok/timeout/bridge_down/protocol/pending/other), retryability, server-side concurrency, overall deadline, and the pending fallback. It also discloses response-size tradeoffs (summary duplication) and default omissions. This is exemplary transparency.

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

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

The description is longer than minimal, but every sentence carries operational information: purpose, target forms, response fields, sibling routing, parameter trade-offs, error handling, and concurrency behavior. It is dense and front-loaded, though it could be tightened with structural formatting. Appropriate for the tool's complexity.

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

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

Given the tool's complexity (4 params, varied target forms, per-row error handling, no output schema), the description covers everything an agent needs: accepted inputs, response contents, error semantics, scaling behavior, and alternatives. There are no obvious gaps that would cause incorrect 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 baseline is 3. The description adds genuine semantic value by clarifying that each target is either a url or a property_id+listing_id pair, and by noting that extracted_features is always included regardless of other parameters. This goes beyond the schema's field-level 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 begins with a specific verb-resource-scope statement ('Fetch and compare 2 to 25 Redfin properties side-by-side') that clearly distinguishes it from redfin_bulk_get and other Redfin tools. It conveys the exact operation and constraints without ambiguity.

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

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

Explicitly states when NOT to use the tool ('For >25 properties or workflows that don't need side-by-side analysis use redfin_bulk_get') and gives parameter-level usage advice (include_summary default false to save context, include_description opt-in). This leaves no doubt about 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?

Goes well beyond the readOnly/idempotent/openWorld annotations: server-side concurrency (~5 fetches in flight), retry-once-on-timeout per URL, an overall deadline after which unsettled samples return status "pending" with a pending count and are excluded from averages, and inherited per-property limitations (no landslide coverage). This is exactly the operational context an agent needs.

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

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

Front-loads the purpose and the routing rationale, and packs retry/deadline/pending semantics tightly. It is a dense single paragraph, and the closing limitations pointer to another tool's description is slightly indirect, but no sentence is filler.

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

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

Although there is no output schema, the description enumerates the return shape (aggregate baseline values, shared cluster_id, per-URL responses for transparency, pending status/count) and the failure mode, so nothing needed to call or interpret the result is missing.

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

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

Schema coverage is 100% and the single parameter is already documented, so the baseline is 3. The description adds genuine meaning beyond the schema: the URLs must be representative of the area, and the count rationale (enough samples to establish cluster agreement).

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

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

States a concrete verb and resource (fetch climate risk for a set of representative URLs, return averaged baseline plus cluster_id) and immediately frames it as an area-level read distinct from per-property calls. An agent can tell it apart from redfin_get_climate_risk, redfin_get_climate_risk_bulk, and redfin_get_property from the description alone.

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

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

Gives explicit when-to-use (a cheap area-level read BEFORE fanning out per-property calls), the decisive condition (if all sample properties share cluster_id and fire/flood/heat factors, the baseline applies to the whole cluster and redundant fetches are avoidable), and the input guidance (pass 2–10 URLs you believe represent the area). No alternatives are left to inference.

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

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

Goes well past the readOnlyHint/idempotentHint/openWorldHint annotations: it discloses the 3-rung resolution ladder, the matched_via discriminator, that a total miss returns resolved:false with attempts rather than throwing, and that signed-out sessions, bridge failure or region mismatch DO surface as errors. That error-vs-empty-result boundary is the most decision-relevant behavior for an agent and is not in any structured field.

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 the ladder, and most clauses carry real information. Some internal issue references (#75, #42) and the parenthetical cross-MLS anecdote add length without much selection value, costing a point.

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 still names the returned fields (matched_via, resolved, attempts) and the error conditions, and it ties the result to the next call in the chain. Nothing needed to invoke or interpret this tool correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine meaning: address is free-text and city/state/zip are optional, plus the non-obvious dependency that city/state are what enable rung 3's locality-to-region search fallback. That conditional relevance is beyond what the schema says.

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

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

States a specific verb (resolve) and resource (free-text address → Redfin canonical URL + home_id), and goes further by naming the exact follow-on sibling (redfin_get_property) and the cross-MLS discrepancy case it feeds. An agent can distinguish it from redfin_resolve_addresses / redfin_bulk_get by the single-address scope stated in the name and text.

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?

Explicit trigger: 'Use this when you have a property address and need its Redfin home_id for follow-on calls (e.g. redfin_get_property).' It also implies when the fallback rung applies (city/state provided). It never states when NOT to use it, notably against the very similar sibling redfin_resolve_addresses, which is the one real routing gap.

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

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

Annotations already declare read-only, idempotent, open-world, but the description adds substantial behavior beyond them: the data source (server-rendered homedetails HTML, no clean endpoint), URL validation that rejects non-/home/<id> pages without fetching, the surfaced not_covered field, and the available:true/false response branches with enumerated reason values (no_first_street_data, new_construction, address_outside_coverage).

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 front-loaded with the core purpose, and the COVERS/DOES NOT COVER and 'Response shape' labels make it scannable. It is dense and the NCGS/USGS landslide detour plus cluster_id note push length for a one-parameter tool, though both still serve routing/dedup decisions.

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

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

With no output schema, the description carries the full burden and does so: it documents the response shape, success and failure branches with reason enums, the not_covered field, and the sourcing. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% (baseline 3), and the description adds real value beyond the schema's example: the URL must end in a /home/<propertyId> segment, accepts full or path form, and other pages are rejected without being fetched. That constraint meaningfully clarifies how to construct the single 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?

Names a specific verb+resource ('First Street Foundation climate risk scores for a property') and then enumerates exactly which vectors are returned (flood, fire, heat) with their scoring scales. The COVERS/DOES NOT COVER framing makes the scope of the tool unambiguous, including the explicit landslide exclusion.

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

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

Gives clear applicability context (property-level, Helene-relevant NC mountains/California/Pacific Northwest markets) and practical dedup guidance via cluster_id. It does not, however, explicitly route the agent to the natural alternatives redfin_get_climate_risk_bulk or redfin_get_area_climate_baseline, so the when-to-use-vs-sibling condition is left to inference.

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

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

Annotations already mark readOnly/idempotent/open-world; the description goes well beyond that by disclosing per-row error capture with `available:false`, server-side concurrency (~5) and retry-once-on-timeout, and the overall deadline with `pending` rows returned retryably. This is exactly the operational behavior an agent needs to know.

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 but every sentence contributes: scope, output shape, error handling, concurrency/retry, deadline/pending behavior, use-case, and inherited limitations. It front-loads the core action and then layers operational detail logically.

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 substitutes by describing the per-property shape, failure representation, timeout/pending behavior, and counting information. Combined with annotations and the single parameter schema, an agent has what it needs to invoke and interpret the call.

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

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

Schema coverage is 100%, so baseline is 3. The description mainly reinforces 'property URLs' and the 100-item ceiling but adds no new parameter format detail beyond the schema; however it does explain that output preserves input order, which is behavior rather than parameter meaning.

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

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

The description names a concrete action ('Fetch climate risk'), a limit ('up to 100 property URLs'), and explicitly ties the output shape to `redfin_get_climate_risk`, distinguishing it from the single-property sibling. It also promises input-order preservation and per-row error handling, which clarify what the bulk variant does differently.

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

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

It states the intended workload directly: 'Use this when batching ~60-property workflows where climate risk is the dominant cost.' It references the per-property sibling and notes shared limitations, giving clear context. It doesn't spell out an explicit 'don't use for a single property' exclusion, so slightly below the top bar.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower. The description nonetheless adds a genuine behavioral gotcha: the rent range is transmitted to Redfin as a server-side filter, so a wrong or invented range silently narrows the comps, and low must not exceed high. It stops short of describing pagination, result limits, or rate limits, so it falls one step short of full.

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?

Purpose is front-loaded in the first clause, followed by use cases and then input requirements. Roughly five sentences, nearly all load-bearing; the alternatives list (property page / Zillow / wide range) is slightly dense but still earns its place by preventing a failed lookup.

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

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

With no output schema, the description steps in and specifies the return payload (monthly rent, distance, Redfin URL). Combined with the input-sourcing guidance and the filter caveat, an agent has everything needed to call this correctly on the first attempt. Nothing material is missing for a read-only lookup 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 80%, which sets a baseline of 3, but the description adds real value: it groups the inputs (rent estimate range + lat/lng + propertyId) and, crucially, documents property_id's provenance since the schema leaves that property undescribed. The low<=high validation rule is also repeated here as intent rather than just a constraint.

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

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

States a specific verb and resource ('Find nearby rental comparables') and immediately differentiates the result from generic property lookups by listing the returned fields: active rental listings with similar bed/bath/sqft, monthly rent, distance, and Redfin URL. An agent can distinguish this from redfin_get_property and redfin_search_properties without opening any schema.

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

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

Gives two concrete use cases (estimating achievable rent, finding rentals near a home under consideration) and explicitly routes the agent when it lacks an input: it names redfin_get_property as the source of property_id/latitude/longitude but warns it does NOT return a rent estimate, then offers alternatives (property page rental estimate, Zillow Zestimate, or a deliberately wide range). This is explicit when-to-use and how-to-source guidance, not inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so 'Read-only; safe to call repeatedly' largely restates them. What adds real value is the disclosure of the autocomplete resolution behavior, the neighborhood-empty-data edge case, and the per-metric return shape.

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 what the report contains, then input modes, then return shape, then safety. Dense but organized; a couple of long compound sentences carry several ideas but nothing is wasted.

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

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

With no output schema, the description correctly carries the return-value burden by specifying the per-metric `{ label, value, unit, yoy_change_fraction, ... }` structure. Combined with the input-mode guidance and edge-case warning, an agent has enough to call it correctly.

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

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

Schema coverage is 100% (baseline 3), but the description adds genuine meaning: the location-vs-region_id/region_type choice, the autocomplete resolution path, the neighborhood caveat, and the property_type default. This goes beyond the terse 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?

States a specific verb+resource ('market report for a Redfin region') and enumerates the exact metrics returned (median list/sold prices, $/sqft, sale-to-list ratio, homes for sale/sold) with yoy/mom framing. This clearly sets it apart from siblings like redfin_get_price_history or 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?

Gives explicit invocation guidance: provide either `location` (free-text via autocomplete) or `region_id`+`region_type`, and warns that neighborhoods typically return empty data. However, it never names alternative sibling tools or when NOT to use this one, 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 read-only, idempotent, and open-world hints. The description adds valuable behavioral context by detailing the returned entry fields, data-source attribution, tax-history inclusion, and the either-or identifier requirement. Restating 'read-only; safe to call repeatedly' is redundant but harmless.

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 mostly efficient and front-loaded with the core purpose and returned contents. The final 'Read-only; safe to call repeatedly' repeats annotation hints, adding slight redundancy, but the overall length is reasonable and each other sentence earns its place.

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

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

For a read-only, 3-parameter tool with no output schema, the description explains both the main return contents and the valid input modes. Minor gaps remain around what happens if both url and IDs are supplied, and how to obtain the identifiers, but the agent has enough to invoke it correctly.

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

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

Schema coverage is only 33%, with just the url parameter described. The description compensates by specifying the critical relationship: provide either url or the property_id+listing_id pair. It does not deeply define each ID's origin or format, but the names are self-explanatory and the grouping rule is materially useful.

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 listing-price events for a single property and enumerates event types (listings, price changes, pending, sold). It also mentions the tax-history series, distinguishing this tool from property-details, market-report, and climate-risk siblings.

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

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

The description implies when to use this tool — when you need listing-level price events or tax history for one property. However, it does not explicitly contrast it with siblings like redfin_get_property or redfin_get_market_report, nor does it 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.

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses concrete data-shape behavior: lot_size null for condos never 0, primary_photo_url dropped on compact view, raw marketing description omitted by default, and derived-field additions (events_normalized for price history). It also explicitly confirms read-only safety, reinforcing the annotations without contradicting them. 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?

Though the description is long, every sentence carries actionable detail — resolution mechanics, output fields, edge cases, and opt-in flags. It is front-loaded with the core purpose and input routes, and the subsequent clauses each add a distinct behavioral fact. No filler, no restatement of the title, and no redundancy with 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 must specify the return shape itself, and it does: it enumerates address, beds/baths, sqft, lot_size, year built, price, status, days on market, and a set of derived fields, plus the exact null behavior for condos. It also covers conditional output (photo drop, description omission) and how to enable them. Given the 7 optional parameters and multiple resolution modes, this is as complete as needed.

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

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

Schema coverage is 100%, but the description goes well beyond the schema by explaining each parameter's behavioral purpose: url resolution via initialInfo, property_id's internal redirect, pairing listing_id to skip resolution, and the context-saving rationale for include_description. This adds operational meaning the schema's enum/value descriptions do not convey, such as 'fastest' and 'skips resolution'.

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

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

The description opens with a specific verb-resource pair — 'Fetch a property's full Redfin record' — and immediately enumerates the three possible input routes (url, property_id alone, property_id+listing_id), each with a distinct resolution path. It clearly delineates this tool from siblings like redfin_get_property_photos and redfin_get_price_history by pointing to those as alternatives for photo galleries and price history, so an agent can select it unambiguously.

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

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

It gives explicit when-to-use guidance: the three call patterns are contrasted by speed ('fastest, skips resolution'), and each optional flag (include_description, include_tax_history, include_price_history) names the exact scenario that warrants it ('use this when a workflow needs both'). It also points to redfin_get_property_photos as the alternative when a photo gallery is required, making the routing decision fully 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, and the description reinforces these with 'Read-only; safe to call repeatedly.' It also adds behavioral details beyond annotations, such as the URL resolution via initialInfo, the return structure, and the edge case of count=0 for off-market listings. This provides a clear picture of what happens during the 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 two sentences with no redundant words. It front-loads the core purpose ('The full photo gallery') and then provides necessary details about output format, input options, and edge cases. Every sentence earns its place.

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

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

For a read-only photo retrieval tool with no output schema, the description covers everything an agent needs: the exact return shape ({ property_id, listing_id, count, photos }), the contents of each photo entry, the two input methods, and a potential edge case (count=0). No critical information 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?

Although the schema already documents each parameter (100% coverage), the description adds significant semantic value by explaining the two mutually exclusive input groups (url OR property_id+listing_id) and that the latter skips the resolve step. This clarifies the relationship between parameters and helps the agent choose the correct combination.

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 does: it retrieves the full photo gallery for a Redfin property, including every image in mediaBrowserInfo, with CDN URLs at multiple sizes, a thumbnail, and captions. This is a specific verb+resource that clearly distinguishes it from sibling tools like redfin_get_price_history or redfin_get_climate_risk.

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 guidance on the two invocation modes (url vs property_id+listing_id) and includes a caveat about off-market or stub listings returning count=0. It does not explicitly name alternatives or state when not to use this tool, but the purpose is unambiguous enough that an agent knows to use it for photo retrieval.

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 bar is lower. The description still adds real value: the sign-in requirement, the return envelope `{ count, homes }`, and an honest caveat that a missing `note` can mean either no favorites or a page-scrape miss.

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 short sentences, front-loaded with the resource and return shape, then the auth prerequisite, then the safety profile. Nothing is redundant with the title or annotations.

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

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

No output schema exists, and the description compensates by describing the return envelope and its edge-case `note`. Auth requirement, safety, and return shape are all covered, so an agent has what it needs to call it correctly.

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

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

Schema description coverage is 100% and the enum's compact/full tradeoff is fully documented in the schema itself. The description never mentions the `view` parameter, so it adds nothing beyond structured data; 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?

States a specific resource (the signed-in user's favorited homes on redfin.com), which is clearly distinct from the sibling redfin_get_saved_searches. It is not framed as a verb+resource action and names no sibling explicitly, so it stops just short of a 5.

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

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

Gives the key prerequisite ("Requires the user to be signed in") and a safety note ("safe to call repeatedly"), but never says when to prefer this over redfin_get_saved_searches or redfin_search_properties, nor any when-not condition. Usage is implied rather than routed.

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?

With annotations already declaring readOnlyHint, idempotentHint and openWorldHint, the description adds genuinely non-derivable context: the data comes from scraping page HTML, so an empty `searches` plus a `note` may mean a scrape miss rather than truly no saved searches. It also states the sign-in requirement and the return contract.

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 compact sentences, front-loaded with what the tool returns and the auth prerequisite. Every sentence carries information; only the trailing "Read-only; safe to call repeatedly" is partly redundant with the annotations.

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

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

With no output schema, the description carries the return contract itself (`{ count, searches }` with per-entry `{ url, region_segment, display_text }`) plus the empty-result caveat and auth requirement. An agent has everything needed to call and interpret the result.

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

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

Schema description coverage is 100% and the single `view` enum is documented in exhaustive detail in the schema itself. The description adds nothing about parameter behavior, so the baseline 3 is appropriate.

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

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

States a specific verb+resource and scope: "The signed-in user's saved searches on redfin.com". The qualifier "saved searches" cleanly distinguishes it from the sibling redfin_get_saved_homes, and the note that data is derived from the saved-searches page HTML pins down exactly what is being fetched.

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

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

Usage is implied rather than stated: the description tells the agent it "Requires the user to be signed in" and is idempotent, which frames when it is callable, but it never names an alternative (e.g. redfin_get_saved_homes) or explicitly contrasts the two. No when-not-to-use guidance.

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

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

Annotations already cover readOnly/idempotent/openWorld, and the description adds substantial non-obvious behavior: the registry is label-only and does not change which account requests use, and every call routes through whichever browser tab the extension is signed into. This is exactly the kind of gotcha an agent needs.

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

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

Front-loads the purpose, then adds the empty/null edge case and the label-only caveat. Four sentences all carry information, though the browser-tab explanation is slightly wordy for what it conveys.

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 present, the description steps in to document return fields (sessions empty, active_session_id null) and the key semantic caveat about what the registry does not control. Nothing needed to call or interpret it correctly is missing.

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

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

The tool takes zero parameters, so per the rubric this is a baseline 4. The description correctly presents it as a parameterless list operation with nothing extra to specify.

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

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

States a specific verb and resource: 'List every registered account label plus the current active_session_id'. It also distinguishes itself from the write-oriented siblings (register/set_active_session) by clarifying the registry is 'a label only'. An agent can identify the tool's scope without opening anything else.

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

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

Gives clear context that this reads labels and does not affect which account requests use, plus the corrective action ('sign that tab into it'). It effectively routes away from assuming this tool changes account, but never names the sibling tools (e.g. redfin_set_active_session) that actually change state, so the alternative selection is 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 cover readOnly/openWorld/idempotent, and the description adds substantial context beyond them: it discloses the probe target, the exact diagnostic fields returned, the failure-mode classes it distinguishes, and that no auth is required. This is rich disclosure for a tool with no output schema.

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

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

Dense and front-loaded: the action and probe target lead, the returned fields and failure-mode hints follow, and the invocation condition closes. Every clause carries diagnostic information, though the long enumeration of returned fields is slightly heavy.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the fields (role, port, version, extension link, elapsed time, hint) and the distinctions between failure modes. Nothing an agent needs to interpret the result is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing to disambiguate; the description correctly implies no inputs are needed.

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

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

States a specific action (round-trips a URL through ContextMint Bridge) plus the exact resource (/robots.txt) and the diagnostic nature of the result. It is unmistakably distinct from every sibling, which are all real Redfin data/session 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?

Explicitly says 'Call this when a real tool fails and you want to know which hop broke,' giving the agent a concrete trigger condition relative to the real tools. No alternatives needed because its role as a fallback diagnostic is unambiguous.

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

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

Annotations only declare write/idempotent/non-destructive. The description adds substantial, non-obvious behavior: re-registration updates rather than duplicates, it returns a session_id, mark_active acts in the same call, and critically the registry is inert — it does not redirect which account requests use because calls follow whichever tab the ContextMint Bridge extension is signed into. That is exactly the kind of context an agent would otherwise get wrong.

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

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

Front-loaded with the core action, then layered with the two clarifications that actually matter (label-only semantics, tab-based auth). It is dense but every sentence earns its place; only the closing sentence is slightly sprawling relative to the rest.

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

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

No output schema exists, yet the description still names the return value (session_id). For a mutation tool whose safety profile is covered by annotations, it covers the behavioral and authentication model fully enough for an agent to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so account_identity, mark_active, and auth_expires_at are already fully documented in the schema. The description restates mark_active ('mark it as the current account in the same call') and mentions the session_id return, adding only marginal meaning over the structured fields. Baseline 3 is appropriate.

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

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

States a specific verb+resource: 'Record (or refresh) which Redfin account the signed-in session belongs to, keyed by account_identity.' It further distinguishes itself from the sibling redfin_set_active_session by explaining that the registry is 'a label only' and does not change which account requests use, so an agent can tell the two apart without opening either schema.

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

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

Gives clear context: re-registering the same identity updates the existing entry, mark_active marks it current in the same call, and it explicitly warns that to read a different account you must sign the browser tab in. This is strong when-to-use guidance, but it never names the obvious alternative (redfin_set_active_session) or states when-not to use this tool, so it stops short of the top score.

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 bar is lower — yet the description still adds substantial behavioral context: input-order preservation, per-row no-match (`resolved: false`) vs. distinct retryable statuses (timeout/bridge_down/pending), retry-once-on-timeout, ~6 in-flight concurrency, and a hard overall deadline with re-runnable `pending` rows. This is exactly the kind of failure/semantics disclosure agents need and no annotation covers.

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?

Though long, every sentence earns its place: purpose → input forms → ordering → no-match vs. retryable failure → retry/concurrency → deadline behavior → usage scenario. It is front-loaded with the core action and flows logically with zero filler or repetition of schema content.

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 present, the description carries full burden for return semantics — and it delivers: input-order preservation, resolved vs. unresolved vs. transient statuses, pending re-run guidance, batch limits, retry behavior, and the motivating use case. For a complex batch tool this is remarkably complete; nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% — both `addresses` and `view` carry rich descriptions (including the compact/full distinction and the anyOf string/object shape). The tool description restates the input forms but adds little beyond the schema; the error-semantics detail it provides is output behavior, not parameter meaning. Baseline 3 applies since the schema does the heavy lifting.

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.' The batch scope (up to 100) and the URL+home_id output clearly distinguish this from single-address siblings like redfin_get_by_address, and the title reinforces the same 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?

Ends with an explicit when-to-use clause: '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 frames the value proposition by contrasting with the 'typical 6-search-call + 15-resolve flow.' However, it does not name a specific alternative sibling for the single-address case or state any when-not-to-use conditions, so it falls just short of a 5.

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

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

Annotations cover safety (readOnly, idempotent, openWorld), and the description adds substantial behavior beyond them: coverage codes and their meaning, result_cap_hit semantics, limit clamping, and the loud error on ZIP cross-continent fallback. This is rich operational context not derivable from structured fields.

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

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

Purpose is front-loaded in the first sentence and each sentence carries operational value (coverage, cap, fallback, status). It is dense and long, but the density is justified; only mild trimming is possible.

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

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

No output schema, yet the description enumerates returned fields (price, beds/baths, sqft, year built, address, URL) and decodes resolved_as/coverage/result_cap_hit. An agent has everything needed to call and interpret it.

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

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

Schema coverage is only 56%, and the description compensates for the key params — limit default/max behavior, bounds overriding the resolved region, status enum restriction, and accepted location formats. Beds/baths/price/home_types are left as 'optional filters' without added meaning, a minor gap.

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

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

Specific verb+resource ('Search Redfin listings by location...and optional filters') with explicit scope, and it distinguishes itself from siblings by naming redfin_get_by_address, redfin_get_comparable_rentals, and redfin_get_market_report. The agent knows exactly what this does versus the alternatives.

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?

Explicit when-to-use for bounds (drawn-map area in big cities), for address short-circuit, for profile_only coverage (use per-property lookup), and for status restrictions (rentals/sold routed to named siblings). Conditions that select alternatives are stated directly.

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 a genuinely non-obvious behavioral fact that annotations cannot convey: the registry is a label only and does not change which Redfin account requests use, with the real switch being the signed-in browser tab. This prevents a costly misconception about auth state. It is consistent with readOnlyHint=false and idempotentHint=true, and adds 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?

Three tight sentences: purpose first, the label-only caveat second, the account-switching workaround last. Every sentence carries information an agent needs; no filler.

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

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

For a single-parameter state setter with no output schema and simple annotations, the description covers purpose, the important no-op caveat about account routing, and the alternative path. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by qualifying the session_id as 'previously registered', telling the agent the id must originate from the registration flow. No format or syntax detail beyond that.

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

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

States a specific verb and resource ('Mark a previously registered session_id as the current account label') and immediately scopes it as bookkeeping-only. An agent can distinguish this from the sibling redfin_register_session, which creates the session this tool merely marks active.

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

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

Gives a clear condition for use ('previously registered session_id', 'across a conversation') and a corrective path for the adjacent need ('to read a different account, sign that tab into it'). It does not explicitly name redfin_get_session_context or redfin_register_session as alternatives, so it stops short of full when/when-not routing.

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

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

Annotations only declare the coarse safety profile; the description adds substantial behavioral context beyond them: the 350-home server cap, recursive quartering, property_id dedup, local filter re-application, drift exclusion, sequential requests with a delay, and the completeness summary returned. Crucially it explains why readOnlyHint=false despite being read-only against Redfin (the only write is the local output file), which reconciles the annotation rather than contradicting it.

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

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

The lead sentence front-loads the core purpose and scope, and the following sentences each add distinct operational detail (cap, recursion, dedup, drift, output handling, request pacing). It is dense but nearly every clause earns its place for a tool this complex; only mild tightening is possible.

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

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

For a 12-parameter, nested-object tool with no output schema, the description covers the essentials: what is returned (completeness summary plus listings, inline or to a file), the safety/write profile, rate-limit pacing, and path-sandboxing rules. An agent has enough to invoke it correctly and interpret results.

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

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

Schema coverage is 58%, so the schema does part of the work. The description adds real meaning for `zips` (ZIP mode alternative to bounds) and `output_path` (directory constraint, no-overwrite), but says nothing about beds_min, baths_min, price_min/max, or home_types, leaving those filters undocumented in both places. The baseline of 3 for partial coverage is appropriate.

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

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

The description names a specific verb (enumerate/sweep) and resource (every for-sale Redfin listing in a bounding box), plus the defining constraint: exhaustive, no silent truncation. This clearly distinguishes it from sibling tools like redfin_search_properties (a normal search) or redfin_get_property (single home), so an agent can route correctly without opening the schema.

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

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

It gives explicit internal guidance: use `zips` (ZIP mode) when Redfin ignores drawn-map polygons, and use `output_path` for large areas to keep listings out of the conversation. It does not, however, explicitly compare against sibling tools such as redfin_search_properties for lighter queries, so routing across the toolset still requires some inference.

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