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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context: it returns both aggregate and per-URL responses for transparency, it avoids N redundant fetches when samples agree, and it notes that limitations of the per-property tool apply (e.g., no landslide coverage). This goes beyond the annotations without contradicting them.

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

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

The description is a single dense paragraph that front-loads the core behavior and then explains the use case and limitations. It is efficient and every sentence earns its place, though it could be slightly more scannable with a break between the behavior and usage guidance.

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 sampling tool with one parameter and no output schema, the description covers the key context: what it returns, when to use it, and a known limitation. It doesn't describe the exact response shape, but the absence of an output schema and the tool's simple aggregate-return nature make this a minor gap. The mention of the per-property tool's limitations is a good completeness touch.

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 sample_urls is well-described in the schema. The description adds value by explaining the purpose of the parameter (representative URLs for the area) and the expected count (2–10), which reinforces the schema's min/max constraints. It doesn't add syntax details, but with one fully documented parameter, the baseline is high.

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

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

The description clearly states the tool fetches climate risk for a small set of representative URLs, averages their baseline values, and returns a shared cluster_id when present. It distinguishes itself from per-property climate tools by emphasizing the area-level sampling approach and explicitly naming the alternative (per-property call).

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

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

The description explicitly says to use this as a cheap area-level read BEFORE fanning out per-property calls, and explains the condition under which it applies (all sample properties agree on cluster_id and factors). It also gives a concrete usage pattern: pass 2–10 representative URLs. This is strong when-to-use guidance with a clear alternative.

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?

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description reveals the 3-rung resolution ladder, the matched_via values, non-throwing resolved: false degradation, and the address_alternates conflict field. This is substantial behavior beyond what annotations encode.

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 core purpose, and every subsequent sentence adds a distinct detail: algorithm, result markers, failure mode, real-world caveat, and use case. The length is justified by the tool's complexity; there is 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?

Even without an output schema, the description discloses the key result fields (matched_via, resolved, address_alternates), the non-throwing error behavior, and the intended follow-on usage. It covers the tool's complexity well.

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

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

Schema has 100% coverage, so the baseline is 3. The description adds meaning by characterizing address as free-text, clarifying that city/state are optional but needed for the search fallback, and mentioning fuzzy street-token matching. That justifies a 4.

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

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

The description opens with a specific verb ('Resolve') and resource ('free-text address ... to its Redfin canonical home URL and home_id'), and details the resolution ladder, making the tool's purpose unmistakable. However, it does not explicitly contrast with the similarly named sibling redfin_resolve_addresses, so sibling differentiation is left to the tool name rather than the description.

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 'Use this when you have a property address and need its Redfin home_id for follow-on calls', and adds that city/state are needed for the search fallback. It does not state when not to use it or point to alternatives such as the bulk resolver.

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/openWorld/idempotent annotations by disclosing the full failure envelope: `{ available: false, reason }` with the three specific reasons, the `not_covered: ['landslide']` field surfaced on every response, and the implementation fragility ('Sourced from Redfin's server-rendered homedetails HTML (no clean stingray endpoint exists)'). It also discloses the clustering behavior (same cluster_id typically shares identical scores). Annotations are consistent — a read-only, idempotent fetch — and the description adds substantial behavioral context on top.

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 it is rigorously structured — COVERS block, DOES NOT COVER block, response-shape block, source note, input note, optimization note — and every sentence carries non-redundant information. Front-loaded with purpose and coverage before implementation details. Slightly dense, but the complexity of three risk vectors plus failure modes justifies the length.

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 explain return values, and it does: the `available: true` shape, the `available: false` reason enum, and the `not_covered` field. Input format, geographic context, alternatives, and performance optimization are all covered. No critical gap for an agent to call this 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% — the url parameter already has a clear description with an example path. The description adds only marginal reinforcement ('Pass a homedetails URL (full or path)'), mostly restating what the schema already conveys. Baseline 3 is appropriate since the schema carries the semantic load.

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 ('First Street Foundation climate risk scores for a property') and then enumerates the exact coverage — flood, fire, heat with per-vector detail (factors 1–10, FEMA zones, horizons, insurance bands). It explicitly carves out what it does NOT cover (landslide), which distinguishes it from a generic 'climate risk' tool and from siblings like redfin_get_area_climate_baseline.

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

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

Names concrete conditions for use ('Helene-relevant risk vector in the NC mountains market and many parts of California / the Pacific Northwest') and explicit alternatives for what it does not cover (NC Geological Survey and USGS for landslide). It also gives an efficiency directive — using cluster_id to group properties and skip redundant fetches — so an agent knows when to reuse results rather than call again.

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 declare readOnlyHint, openWorldHint, and idempotentHint, covering safety and variability. The description adds value by specifying the output content (similar active rentals with rent, distance, URL) and the source of inputs (upstream property data). This exceeds annotation coverage without contradiction.

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

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

Two sentences with zero waste. The first sentence states the core function and output; the second covers use case and input provenance. Information is front-loaded and every clause earns its place.

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

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

For a read-only tool with robust annotations and no output schema, the description covers the essential aspects: what it returns, how it's useful, and where inputs come from. It doesn't mention pagination or distance limits, but these are not critical for a comparables tool and the description is otherwise 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 only 40%, so the description must compensate. It does by naming the parameter groups: 'rent estimate range + lat/lng + propertyId', which maps directly to the five parameters. It also clarifies the rent estimate low/high as a range and notes they can be equal. However, it does not explain the meaning of property_id beyond 'from upstream', which is 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?

The description clearly states a specific verb ('Find') and resource ('nearby rental comparables for a given property'), details the criteria (similar bed/bath/sqft) and outputs (monthly rent, distance, Redfin URL). It also conveys the use case (estimating rent, finding nearby rentals), which distinguishes it from siblings like redfin_get_property 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?

The description gives clear context for when to use the tool: when you have a property and need rental comparables, and it specifies that inputs typically come from upstream redfin_get_property or the property page. It does not explicitly state exclusions or alternatives, but the context is sufficient for an agent to decide when to invoke 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?

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 and idempotentHint, and the description reinforces this while adding the requirement that the user be signed in. It does not disclose failure modes, but the auth requirement is meaningful 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?

Three short sentences are front-loaded with the resource and return fields. The read-only and safe-to-repeat statement is somewhat redundant with the annotations, but the overall text is compact and well organized.

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 with one optional parameter, the description plus schema covers purpose, authentication, and return fields. There is no output schema, but the listed fields give an agent enough expectation for the response shape; the main gap is unspecified pagination or limit 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?

The single optional parameter `view` is fully documented in the schema with enum values and a detailed description, so the schema carries the parameter-semantics load. The tool description adds no input-parameter meaning beyond that, matching the baseline for 100% 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 a specific verb and resource: returns the signed-in user's favorited homes on redfin.com, and enumerates key returned fields (address, price, beds/baths, status). This clearly distinguishes it from siblings like redfin_get_saved_searches 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?

The description gives clear context: this is for the signed-in user's saved/favorited homes and requires authentication. It does not explicitly name alternatives or say when not to use it, 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 and idempotentHint, and the description reinforces these by stating it is read-only and safe to call repeatedly. It adds genuinely new behavioral context: the data is derived from the saved-searches page HTML, requires authentication, and returns an empty array when no searches exist. This goes beyond what the annotations alone provide.

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 deliver the core functionality, return shape, authentication requirement, empty-result behavior, and safety profile with no filler. The most important information is front-loaded, and every sentence earns its place.

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

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

With no output schema, the description correctly fills the gap by documenting the entry structure, auth requirement, empty-array behavior, and read-only semantics. The single optional parameter is fully covered by the schema, and the tool is simple enough that nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, and the schema thoroughly explains the `view` parameter, including compact/full semantics and the rationale for not doing field projection. The tool description itself adds no parameter-specific guidance, so the baseline of 3 applies since the schema carries the full burden.

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

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

The description names a specific verb and resource: retrieving the signed-in user's saved searches from redfin.com. It also states the exact shape of each entry (`{ url, region_segment, display_text }`), making the purpose unambiguous. This clearly distinguishes it from siblings like redfin_get_saved_homes without needing 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?

The description gives clear context for when this tool works: the user must be signed in, and it returns an empty array when there are no saved searches. It does not explicitly contrast it with an alternative tool or say 'use X instead,' but the context is sufficient for an agent to know when it applies.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true) by disclosing that re-registration is an update not a duplicate, that the registry is purely a label and does NOT redirect which account requests use, and that account selection actually happens via the ContextMint Bridge browser tab. This is exactly the kind of non-obvious behavioral context that prevents misuse.

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 core action, then layers the idempotency note, the return value, and the critical label-only caveat in four tight sentences. Every sentence earns its place, and the most important warning is stated explicitly rather than buried.

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 3-param mutation tool with no output schema, the description covers the mutation semantics, idempotency behavior, the returned `session_id`, and the label-only limitation, while annotations carry the safety profile. Nothing an agent needs 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 description coverage is 100%, so all three parameters are already documented in the schema (including `mark_active` and `auth_expires_at`). The description reinforces the identity-keying and the effect of `mark_active`, but adds no syntax or format details beyond what the schema provides, 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 (record/refresh) and resource (the Redfin account a signed-in session belongs to), and explains the keying by `account_identity` plus the returned `session_id`. It implicitly distinguishes itself from `redfin_set_active_session` by noting that `mark_active: true` folds that action into the same call, but no sibling is named explicitly.

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

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

Provides clear context for when this is the right call: re-registering the same identity updates the existing entry, and the registry is a label only that does not change which account requests use. However, it never names an alternative tool or states an explicit when-not condition, 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, 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?

Annotations declare readOnlyHint=false and idempotentHint=true, and the description adds genuinely non-obvious context beyond them: the registry is a label only and does not change which account requests use, plus the bridge-extension tab behavior. This is valuable disclosure, though it omits return/error behavior and any auth prerequisites.

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 the action, then the clarifying caveat and the alternative. Every sentence earns its place; the caveat prevents a costly misconception and is not padding.

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

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

For a single-parameter bookkeeping tool with no output schema, the description is nearly complete: purpose, the important label-only nuance, and the alternative are all covered. Only minor gaps remain (what a successful call returns or errors on an unknown id), which are low-stakes here.

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% for the single parameter, so baseline is 3. The description adds meaning beyond the schema by specifying the id must be 'previously registered', tying it to the registration workflow, which is a useful constraint not present in the schema text 'Session id to make active.'

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

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

The description states a specific verb and resource: 'Mark a previously registered `session_id` as the current account label.' It goes further by clarifying the scope ('for your own bookkeeping across a conversation'), which cleanly separates it from siblings like redfin_register_session and redfin_get_session_context without needing to open their schemas.

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

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

It gives clear context for use ('for your own bookkeeping across a conversation') and an alternative path for a related goal ('to read a different account, sign that tab into it'). It does not, however, explicitly state when to prefer this over redfin_register_session or redfin_get_session_context, so it falls just 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?

Discloses a lot beyond the annotations: the 350-home API cap, recursive quartering, local dedupe by property_id, local re-application of filters, sequential requests with a delay, region-drift omissions, and refusal to overwrite an existing output file. It also resolves the readOnlyHint=false annotation by stating the only write is the optional local file, so there is 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?

Front-loaded with the purpose and the cap/recursion rationale, then mode selection, then output handling. It is a long paragraph, but nearly every clause carries operational information; a bit of it repeats (ZIP-as-capped restates cap logic already given).

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 the full calling picture for a 12-parameter, no-output-schema tool: how the sweep behaves, what it returns (completeness summary plus inline listings), and how to divert results to a file. Nothing essential is left to the schema.

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

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

Schema coverage is only 58%, but the description compensates for the key gaps: zips vs bounds as alternative sweep modes, what the completeness summary counts, and the semantics of output_path (new file only, inline by default). Filters like beds_min/price_min and home_types get no direct explanation, though 're-applies the caller's filters locally' hints at their behavior.

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 precise verb+resource ('Enumerate EVERY for-sale Redfin listing inside a bounding box') plus the defining quality (no silent truncation) that separates it from a normal search tool. The mechanism sentences make the tool's identity unambiguous even against the large sibling list.

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 when to use ZIP mode vs map polygons ('when Redfin ignores drawn-map polygons') and when to pass output_path ('for large areas'). It does not directly name redfin_search_properties as the non-exhaustive alternative, which is the one routing decision an agent still has to infer.

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