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 provide readOnlyHint and idempotentHint, and the description adds valuable behavioral context: 'No network — pure local math' and reference to a canonical shared engine. This reassures the agent that invocation has no side effects or external dependencies. No contradiction with annotations.

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

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

The description is three tight sentences: purpose, inputs, outputs, then behavioral context. Every sentence earns its place, and the most decision-relevant information is front-loaded.

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

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

With 10 parameters and no output schema, the description needs to be self-sufficient. It covers outputs and most inputs, but it does not state units for interest_rate or property_tax_rate, nor does it mention the DTI override parameters. An agent could still make incorrect assumptions about exact call format.

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 0%, so the description must carry the parameter-meaning burden. It names most parameters in plain language, adds examples like 'car/student loans' for monthly_debts, and flags optionality for tax/insurance/HOA/loan term. However, it omits the custom front_end_dti/back_end_dti override parameters and does not specify rate units, leaving some semantic gaps.

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 clear action and resource: 'Solve for the maximum home price you can afford.' It further specifies the standard 28/36 DTI rule and enumerates inputs and outputs, making it easy to distinguish from sibling tools like redfin_calculate_mortgage.

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 intended use case is clear: computing a maximum affordable home price under a standard DTI rule. It does not explicitly name sibling alternatives or state when not to use this tool, but the scope is specific enough that an agent can infer 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 declare readOnlyHint and idempotentHint, and the description goes further by saying 'No network call — fully deterministic,' explaining PMI auto-application at LTV > 80%, the 20% down payment default, and property tax input alternatives. No contradiction with annotations.

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

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

Four sentences, front-loaded with scope and output, no filler. Every sentence contributes a distinct piece of information: local behavior, return value, input alternatives, and PMI rule.

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

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

For a 10-parameter tool with no output schema, the description covers the return contents, defaults, parameter selection rules, and conditional PMI behavior. An agent has enough information to select and invoke the tool correctly using the schema plus this description.

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 only 40%, but the description compensates for the key ambiguities: 'either down_payment OR down_payment_percent; defaults to 20%', property tax as annual amount or rate, and the pmi_rate condition. It does not document every parameter, but the omitted ones are either self-explanatory or covered by schema descriptions.

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

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

The description states a specific verb and resource: a 'Local-only mortgage payment calculator' that 'Returns a full PITI breakdown' plus total interest. This clearly separates it from data-fetching siblings like redfin_search_properties or redfin_calculate_affordability.

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 frames when to use it: 'safe to use for scenario comparison without burning a fetch' and labels it as local-only. It does not name sibling alternatives or state when NOT to use it, so there is minor room for improvement.

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=true and idempotentHint=true, and the description reinforces this with 'Read-only; safe to call repeatedly.' It goes beyond annotations by disclosing the return shape of each metric and the behavioral caveat that neighborhoods typically return empty data. This gives an agent useful expectations before invoking.

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, each earning its place: the first defines scope and outputs, the second gives parameter routing guidance, and the third communicates return structure plus safety. The most actionable usage instruction follows immediately after the purpose statement.

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 0 required parameters and no output schema, the description covers everything needed: the metric object structure, two region-specification modes, the property-type default, a location quality caveat, and read-only/idempotent safety. An agent can call the tool correctly without additional inference.

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% since all four parameters have descriptions. The description adds meaning above the schema by explaining how `location` resolves via autocomplete, contrasting it with the direct `region_id`+`region_type` path, and stating the `property_type` default value.

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

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

The description states a specific resource ('market report for a Redfin region') and enumerates the exact metrics returned, including median list/sold prices, $/sqft, sale-to-list ratio, and change-over-time figures. This clearly distinguishes it from sibling tools 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?

It provides explicit invocation guidance: use either `location` (free-text via autocomplete, best with city names; neighborhoods typically return empty data) or `region_id` + `region_type` directly, and mentions the `property_type` default. It does not name sibling alternatives, but the market-report scope and metric list make the intended use clear.

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

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

Annotations already declare 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?

The description adds detail about the empty-session edge case (sessions empty, active_session_id null), which goes beyond the readOnlyHint annotation. It clearly aligns with the read-only and idempotent annotations without contradiction, and the added null-case disclosure provides useful behavioral context.

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 exactly two sentences, each earning its place. The main action is front-loaded, and there is zero fluff or repetition of schema/annotation details.

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 zero-parameter tool with no output schema, the description adequately describes the return value (sessions list and active_session_id) and the edge case when no sessions exist. 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?

There are zero parameters, so the schema coverage is trivially 100%. The description doesn't need to explain parameters; a baseline of 4 applies for a parameterless tool, and the description adds no unnecessary information.

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 'Return the full set of registered sessions plus the current active_session_id.' This is a specific verb-resource pair that distinguishes it from sibling tools like redfin_set_active_session or redfin_register_session.

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

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

The description does not explicitly state when to use this tool versus alternatives like redfin_set_active_session. However, the purpose is so specific that usage is implied—one would call this to inspect current sessions. There is no explicit 'when not to use' or mention of alternatives, so it only reaches 'implied usage'.

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. The description adds value beyond them: no auth required, an external network round-trip, and the diagnostic categories (bridge role, extension link state, failure classification). No contradiction with annotations.

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

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

A dense first sentence front-loads the core behavior, and every diagnostic field listed earns its place. Slightly long, but justified by the number of outputs a health-check tool must describe.

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 discharges it thoroughly: role, port, version, extension link states, elapsed RTT, and plain-English failure hints. Auth and side effects are addressed; nothing an agent needs to invoke this zero-parameter tool is missing.

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

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

Zero parameters, so the empty schema is vacuously complete at 100% coverage; baseline 4 applies. The description's lack of parameter detail is harmless since there is nothing to document.

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: round-trips /robots.txt through the fetchproxy bridge. Clearly distinguishes this diagnostic tool from the 19 data-retrieval siblings, and the closing sentence identifies its troubleshooting role (which hop broke).

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 to call it: 'Call this when a real tool fails and you want to know which hop broke.' Provides clear context, though it does not name alternatives or 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?

The description adds behavioral detail beyond annotations: re-registering the same account_identity updates the existing session instead of duplicating it, which expands on idempotentHint=true. It also discloses the default-active behavior and the effect of mark_active, giving an agent a clearer model of side effects.

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

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

The description is three tight sentences with no filler. It front-loads the core mutating action, then explains update semantics, return value, and activation behavior in a logical order. 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 low-complexity tool with 3 parameters and no output schema, the description covers the essential behavior, return value, and active-session semantics. It could also mention what happens when no session is active and mark_active is false, but the first-registered-becomes-default rule largely covers that edge case.

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 semantic value by identifying account_identity as the idempotency key and by explaining the effect of mark_active on session activation, going slightly beyond the schema's property 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 names a specific action ('Register (or refresh) an authenticated Redfin session') and a precise resource ('a session keyed by signed-in account identity'). It clearly differs from sibling tools like redfin_set_active_session and redfin_get_session_context by framing this as the registration/refresh entry point that returns a session_id.

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

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

The description gives clear context on how to use the tool: register the first session to become default, pass mark_active to set it active, and use the returned session_id for routing per-tool calls. It does not explicitly name excluded cases or alternatives, but the intended usage is strongly implied.

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?

Beyond readOnlyHint/idempotentHint, it discloses the autocomplete-to-gis flow, the street-address short-circuit, the meaning of resolved_as and coverage values, result_cap_hit semantics, and loud errors on cross-continent ZIP fallback. It also explicitly confirms read-only safety, consistent with the annotations. No contradiction.

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

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

The description is long but dense, front-loading the core action and packing each distinct behavior into its own sentence. A small amount of redundancy with the status schema and the readOnly annotations keeps it from being perfectly lean.

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 of explaining return values, and it does: price, beds/baths, sqft, year built, address, URL, plus resolved_as, coverage, and result_cap_hit. It covers error cases, limits, and sibling alternatives, so an agent has everything needed 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?

The schema already documents location, limit, status, and home_types; the description adds operational meaning for those by explaining autocomplete resolution, limit clamping to 350, and the status error behavior. The numeric filter parameters (beds_min, baths_min, price_min, price_max) lack schema descriptions and are only hinted at via 'narrow with price/beds filters,' which is a modest 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 opens with a specific verb and resource ('Search Redfin listings by location...') and details the resolution pipeline, return fields, and envelope semantics. It explicitly distinguishes itself from redfin_get_by_address for per-property lookups and names rental/sold alternatives, so an agent can tell it apart from the 20 sibling 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?

It states exactly when to use the tool (location-based listing searches) and when not to: sold/for_rent statuses return errors and should use redfin_get_comparable_rentals or redfin_get_market_report, and profile_only coverage should use redfin_get_by_address. It also gives operational guidance around result_cap_hit and ZIP fallback failures.

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

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

The description discloses that the tool changes default routing state for subsequent calls, which goes beyond the annotations (readOnlyHint=false, idempotentHint=true). It also notes the override behavior. It does not describe failure behavior for invalid/unregistered session IDs, but the core stateful effect is transparent and does not contradict the annotations.

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

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

Two sentences, each earning its place: the first states the primary action and effect, the second provides the prerequisite and the override behavior. No filler or repetition of schema details.

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 state-setting tool with one parameter and no output schema, the description is complete: it defines the action, the prerequisite for the parameter, and how the default interacts with explicit session_id parameters. No critical information needed for calling 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% and the schema describes session_id as 'Session id to make active.' The description adds important semantic meaning by requiring that the session_id was previously returned by redfin_register_session, which is not in the schema. This helps the agent understand the provenance requirement.

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 ('Switch') and resource ('registered session') and clarifies that this sets the default routing for subsequent tool calls. It clearly distinguishes this tool from siblings like redfin_register_session (which creates sessions) and redfin_get_session_context (which reads session info).

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 to pass a session_id previously returned by redfin_register_session, giving a clear prerequisite. It also explains that tools accepting an explicit session_id override this default per-call, which tells the agent when the default applies and how to bypass it. It does not explicitly name alternative tools, but the guidance is sufficient for correct usage.

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