Bulk fetch Redfin property records

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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses substantial behavior: per-target error capture, ~6 in-flight server-side concurrency, retry-once-on-timeout, a hard deadline, and retryable pending status rows. This gives the agent accurate expectations about failure modes and partial results.

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

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

The description is dense but every sentence earns its place: capability, target forms, output relation, error behavior, concurrency, timeout semantics, and usage guidance are all covered without filler. The most important facts are front-loaded.

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

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

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

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

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

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

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

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

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

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

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

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

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