Research U.S. markets and prospects conversationally using PropertyRadar's property and people data. Resolve an address, inspect Property details, transactions, comparable sales, ownership and contact information, discover supported Criteria and fields, search for matching Properties, and save selected results as a dynamic Audience. PropertyRadar accesses only the data available to your connected account.
Scored across 15 tools
Most tools target clearly distinct resources (comps, transactions, persons, phones/emails/relatives, address resolution, search). The main hazard is get_property_details vs get_properties_details (differ by one letter) and get_property_details vs get_property_summary, both covering single-property fields. Descriptions work hard to disambiguate these with explicit 'do not use X for Y' guidance, so it stays mostly distinct.
Every tool follows a consistent verb_noun snake_case pattern (get_criteria, get_person_emails, search_properties, resolve_address, create_dynamic_audience). No mixed conventions or casing. The deliberate singular/plural split (get_property_ vs get_properties_) is the only subtle naming hazard but it is still consistent and intentional.
15 tools is well-scoped for a property-data platform spanning discovery, search, single/bulk record fetch, comps, transactions, persons, contact channels, and audience creation. Each tool earns its place with a distinct resource or billing behavior; nothing appears redundant.
Read/lifecycle coverage for property search, record fetch, comps, transactions, persons, and contact data is thorough. Gaps exist in audience lifecycle (only create_dynamic_audience; no list/get/update/delete) and in insights tooling, which is referenced (get_properties_insights, get_property_insights) but not actually present. These are workable but real dead ends.
Create a saved dynamic Audience only after the user confirms both the criteria and name. Required: criteria (an array of {"name","value"} objects) and name (maximum 50 characters). Optional: monitored (default false). Never bills or purchases property data. Before setting monitored=true, explain that monitoring also enables Insights and Automations, that a monitored Audience stops growing when it reaches the package limit, and get explicit confirmation. Each criterion accepts at most 500 values. Returns audience_id, the stored name, total_count, effective monitored state, and related_tools[].
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| criteria | Yes | ||
| monitored | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare a non-read-only, non-idempotent, non-destructive write operation, and the description adds substantial behavioral context: no billing/purchase of property data, monitored Audiences stop growing at the package limit, and monitoring enables Insights and Automations. 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?
Front-loads the core action and confirmation requirement, then packs constraints and return details without filler. Every sentence earns its place by adding operational or safety information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a sparse schema with no output schema, the description covers required and optional parameters, confirmation workflow, monitoring consequences, capacity limits, and return fields. 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?
Schema description coverage is 0%, so the description carries the full burden. It specifies criteria as an array of {name,value} objects, name maximum length, monitored default false, and a per-criterion value limit, which fully compensates for the bare 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?
States a specific verb and resource: create a saved dynamic Audience. The description clearly distinguishes this write operation from the read/search-oriented sibling tools by naming the artifact and its saved nature.
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 requires user confirmation of both criteria and name before creation, and mandates a specific explanation plus explicit confirmation before setting monitored=true. These are concrete when-and-how guidelines rather than vague context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover property search criteria ids, types, and example values before calling search_properties. PropertyRadar covers all 50 US states and DC nationwide. Call this tool at least once before your first search_properties in a workflow; make one scoped discovery call for the filters currently requested and do not repeat discovery for criteria already established in the conversation. Default (no params) returns a lightweight groups[] index with criteria_ids[] per group and subgroup plus upgrade_criteria_ids[] — not the full catalog. Scope with groups (an array of group names, or names prefixed "-" to exclude; never a bare string), criteria_ids (an array of exact catalog ids), and/or query (one literal substring across titles, descriptions, enumerations, and MCP usage guidance; not a space-separated multi-keyword search). Params compose in one call; every scoped call returns full matching criteria[] detail with included, description, criteria_type, optional criteria_example, enumeration[], and optional usage_guidance. Every success includes related_tools[] for search_properties, optional get_suggestions, and audience/insights paths. Suggestion-backed criteria include suggestion_field. County names always require get_suggestions to resolve the positive integer FIPS before search; complete City or Subdivision values can be passed directly. Never bills.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| groups | No | ||
| criteria_ids | No |
| Name | Required | Description |
|---|---|---|
| groups | No | |
| criteria | Yes | |
| related_tools | Yes | |
| upgrade_criteria_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld=false/destructive=false, and the description adds substantial context beyond them: the default call returns a lightweight groups[] index rather than the full catalog, scoped calls return full criteria[] detail, every success includes related_tools[], suggestion-backed criteria carry suggestion_field, and 'Never bills.' These are genuine behavioral disclosures.
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 purpose and the 'call before search_properties' directive are front-loaded, and the dense sentences each add usable detail. It is on the long side and could be tightened, but almost every clause earns its place rather than 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 3-param discovery tool with a 0%-coverage schema, the description fully specifies parameter behavior, call cadence, default vs scoped output shape, and the hand-off to search_properties/get_suggestions. Despite an output schema existing, it even outlines the return shape, leaving no material gap for an agent.
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 0%, so the description must carry the load and does: query is one literal substring across titles/descriptions/enumerations/usage guidance and explicitly NOT a space-separated multi-keyword search; groups is an array of names or '-'-prefixed exclusions and 'never a bare string'; criteria_ids are exact catalog ids. It also notes params compose in a single call.
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 (discover property search criteria ids, types, and example values) and names the exact downstream tool it precedes (search_properties). It is immediately distinguishable from siblings like get_suggestions, get_fields, and 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 when-to-use (call at least once before the first search_properties), when-not (do not repeat discovery for criteria already established), how-many (one scoped call for the filters currently requested), and names the alternative path (county names require get_suggestions). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover exact output field ids for a consuming MCP record tool. Never bills and returns catalog metadata only. Required: tool; supports get_property_details, get_properties_details, get_property_summary, get_property_comps, get_property_transactions, get_property_persons, get_person_phones, get_person_emails, and get_person_relatives. With tool only, returns compact fieldsets[], groups[], and upgrade_field_ids[] indexes without full metadata rows. Add groups, field_ids, or query to return MCP-shaped fields[] with id, group, title, short_title, description, and included; those scopes are composable. Property record tools expose Standard (80) and All (200 shippable, including eight computed loan fields) fieldsets for get_property_details and get_properties_details. For get_property_summary, fieldset Standard or All returns full metadata for entitled members and both bundles have identical registered membership. For get_property_comps, Standard contains 19 available ids and All contains 24 available ids spanning sales and listings; CompDistance and ZipFive remain Product requirements. The billable comps tool omits fields that do not apply to the requested comp_type. For get_property_transactions, seven fieldsets register 94 available ids; the remaining unavailable field stays visible with included=unavailable. For get_property_persons, Standard exposes all 22 registered ids and All exposes all 33 registered ids; tool_status remains partial while primary_only is unavailable. For get_person_phones, get_person_emails, and get_person_relatives, Standard and All are identical within each tool and the catalog reports current Partial constraints. Fieldset cannot combine with other scopes. Summary accepts no fields argument itself; use this catalog to understand its fixed results. Do not call this tool to identify the owner; use get_property_persons for persons and contact channels. Use get_criteria for search filters. Other consuming tools are unsupported.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | Yes | ||
| query | No | ||
| groups | No | ||
| fieldset | No | ||
| field_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover safety (readOnlyHint, non-destructive, closed-world); the description adds behavior they don't: 'Never bills and returns catalog metadata only', which is critical for an agent worried about cost. It also explains the distinct return shapes per call mode (compact indexes vs. full fields[] rows) and the composability constraint on scopes.
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 and usage are front-loaded, which is good, but the middle bloats into per-tool fieldset inventories ('Standard contains 19 available ids and All contains 24...', 'seven fieldsets register 94 available ids') that are exactly the data this tool returns and will go stale. Those counts don't help an agent select or invoke the tool, so a meaningful share of the text doesn't earn 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 steps up and describes return shapes: compact fieldsets[]/groups[]/upgrade_field_ids[] with tool only, and MCP-shaped fields[] with id, group, title, short_title, description, included when scopes are added. It also notes the Summary tool takes no fields argument and that unavailable ids appear with included=unavailable, so an agent knows what to expect from every call mode.
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 0%, so the description must carry the params, and it largely does: tool is required with nine supported values, fieldset accepts Standard or All, groups and field_ids compose, and 'Fieldset cannot combine with other scopes' documents a real cross-parameter constraint. The query parameter, however, gets only a passing mention and its matching/filtering behavior is never explained, leaving one 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 opening states a specific verb and resource: 'Discover exact output field ids for a consuming MCP record tool', immediately separating this catalog tool from the record tools it describes. It reinforces the distinction by naming sibling tools (get_property_persons, get_criteria) that should be used for other jobs. An agent can tell at a glance that this is a metadata lookup, not a data-fetch tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('Discover exact output field ids'), when-to-scope (add groups, field_ids, or query for full MCP-shaped rows), and when-not-to-use ('Do not call this tool to identify the owner; use get_property_persons... Use get_criteria for search filters'). It also enumerates the nine supported consuming tools and warns that 'Other consuming tools are unsupported'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Acquire or re-fetch billable email contact data for one Person by person_id (same string as REST PersonKey, e.g. p4290). PropertyRadar covers all 50 US states and DC nationwide. Required: person_id. Optional: fields (default Standard; Standard and All return the same four Product email ids; comma-separated ids from get_fields are also accepted). Returns email contact data in results[] with data_acquisition_status (acquired, my_data, or unavailable). Bills one fixed billable hit when contact data is newly acquired; my_data and unavailable are non-billable (total_cost=0). No count_only quote on this tool. Typical chain: get_property_persons → take PersonID from a row → get_person_emails when the user wants emails only. Use get_person_phones or get_person_relatives for other contact data. User outreach compliance remains the subscriber responsibility.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | ||
| personId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description goes far beyond that by disclosing billing semantics (one fixed billable hit when newly acquired; my_data and unavailable are total_cost=0), the return-status enum values, the absence of a count_only quote, and subscriber compliance responsibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and required parameter, and nearly every sentence carries operational value (billing, statuses, chain). The nationwide coverage line is the one near-filler sentence, and the text is dense enough that it approaches a wall of facts rather than scannable 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 2-param billable tool with no output schema and no annotation coverage of billing, the description supplies everything an agent needs: input format, default field set, billing outcome per status, and the upstream chain. No meaningful 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 description coverage is 0%, so the description carries the full burden and does: person_id is documented as the REST PersonKey string with an example, and fields is documented with its default (Standard), the fact that Standard and All return the same four Product email ids, and that comma-separated ids from get_fields are accepted.
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 (acquire/re-fetch billable email contact data for one Person) plus the exact key format (person_id, e.g. p4290). It explicitly contrasts itself with get_person_phones and get_person_relatives, so the agent can distinguish it from siblings without opening 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?
Gives an explicit trigger condition ('when the user wants emails only') and names the two alternative tools for other contact data. It also supplies the typical call chain get_property_persons → PersonID → get_person_emails, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Acquire or re-fetch billable phone contact data for one Person by person_id (same string as REST PersonKey, e.g. p4290). PropertyRadar covers all 50 US states and DC nationwide. Required: person_id. Optional: fields (default Standard; Standard and All return the same five Product phone ids). Returns phone contact data in results[] with data_acquisition_status (acquired, my_data, or unavailable). Bills one fixed billable hit when contact data is newly acquired; my_data and unavailable are non-billable (total_cost=0). No count_only quote on this tool. Typical chain: get_property_persons → take PersonID from a row → get_person_phones when the user wants phones only. Sibling contact data tools: get_person_emails, get_person_relatives. Not for property-scoped person fetch (use get_property_persons). User outreach compliance (TCPA/CCPA) remains the subscriber responsibility.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | ||
| personId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations by disclosing the billing model: a fixed billable hit only when contact data is newly acquired, with my_data and unavailable non-billable (total_cost=0), plus 'No count_only quote on this tool'. With readOnlyHint=false this billing/mutation side effect is exactly the context an agent needs 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?
Front-loads the core action and required param, then layers billing, return shape, chain, siblings, and exclusion in compact sentences. Densely packed with no filler despite its 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?
No output schema exists, yet the description describes the return payload (results[] with data_acquisition_status of acquired/my_data/unavailable) and the billing consequences per status, plus the compliance caveat. Nothing essential 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 0%, so the description must compensate: it pins person_id to the REST PersonKey format with an example (p4290) and explains the fields default (Standard), noting Standard and All return the same five phone ids. Strong compensation, though the exact set of five product ids is left unnamed.
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+scope: 'Acquire or re-fetch billable phone contact data for one Person by person_id', and explicitly names sibling contact tools (get_person_emails, get_person_relatives) and the wrong-scope alternative (get_property_persons). An agent can distinguish it from all siblings without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit chain (get_property_persons → take PersonID → get_person_phones when the user wants phones only), names alternatives, and adds an exclusion ('Not for property-scoped person fetch'). When/when-not/alternatives are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Acquire or re-fetch billable relative data for one Person by person_id (same string as REST PersonKey, e.g. p4290). PropertyRadar covers all 50 US states and DC nationwide. Required: person_id. Optional: fields (default Standard; Standard and All return the same 13 Product relative ids; comma-separated ids from get_fields are also accepted). Returns at most five relative rows in API acquisition order with data_acquisition_status (acquired, my_data, or unavailable). Bills one fixed hit only when data is newly acquired; my_data and unavailable are non-billable (total_cost=0). No count_only quote on this tool. Typical chain: get_property_persons → take PersonID from a row → get_person_relatives. Each result has an mp-prefixed RelatedPersonID that can be passed as person_id to get_person_phones; owned relative email data may remain unavailable through get_person_emails.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | ||
| personId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: discloses billing semantics ('one fixed hit only when data is newly acquired'), which statuses are free (my_data, unavailable, total_cost=0), the 'at most five relative rows in API acquisition order' cap, the data_acquisition_status values, and that there is no count_only quote here. This is exactly the side-effect context annotations cannot convey.
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 every sentence earns its place — billing, identifiers, row cap, and chaining each add actionable information with no filler. It is a single long paragraph rather than clearly bulleted/segmented, which slightly hurts scannability but not substance.
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 and 0% parameter coverage, the description still covers what comes back (relative rows, RelatedPersonID format, data_acquisition_status), cost behavior, cardinality, and the chaining prerequisite. 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 0%, so the description carries the full burden, and it does so well: person_id is explained via the PersonKey format with an example (p4290), and fields is explained with its default (Standard), the note that Standard/All return the same 13 ids, and that comma-separated ids from get_fields are accepted. Only minor gaps remain (no field id enumeration), so a 4 rather than a 5.
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 ('Acquire or re-fetch billable relative data for one Person'), the identifier format (person_id / REST PersonKey, e.g. p4290), and the coverage scope (all 50 US states and DC). An agent can distinguish it from siblings like get_property_persons or get_person_phones without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit 'Typical chain: get_property_persons → take PersonID from a row → get_person_relatives' plus a downstream pointer to get_person_phones and a caveat about get_person_emails. It does not state an explicit when-not-to-use or name a direct alternative tool for the same data, so it falls 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.
Fetch billable property rows for a property set matching criteria. PropertyRadar covers all 50 US states and DC nationwide. Required: criteria (JSON-encoded array, same shape as search_properties). Optional: count_only (true returns total_result_count and estimated_cost with empty results[], non-billable — recommend before purchase); fields (default Standard fieldset per get_fields; comma-separated field ids allowed); limit (default 100, max 1000); start for paging; sort (e.g. AVM:desc). Saved Audience uses InList inside criteria — no audience_id parameter. Bills per row returned on purchase; usage is non-refundable — use count_only and search_properties before large sets. Each row is flat scalars only (no transaction/comp/person arrays or Contacts-group fields); use get_property_details, get_property_transactions, get_property_comps, or get_property_persons for depth. Not for a single RadarID (use get_property_details). Every success includes related_tools[].
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | ||
| limit | No | ||
| start | No | ||
| fields | No | ||
| criteria | Yes | ||
| countOnly | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only give the safety triad; the description adds the economically critical behavior the annotations cannot convey: billing is per row on purchase, usage is non-refundable, count_only returns estimated_cost and is non-billable, and each row is flat scalars only (no arrays or Contacts groups). This is exactly the operational context an agent needs before spending money.
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 verb and billing warning, then organizes details by parameter; nearly every clause carries actionable information. It is dense enough to feel like a semicolon-chained run-on, but little is genuinely 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?
No output schema exists, yet the description explains return shape (flat scalar rows), what count_only returns (total_result_count, estimated_cost, empty results[]), billing implications, and the related_tools[] envelope. Nothing material 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?
With 0% schema description coverage, the description carries the full burden and largely succeeds: criteria shape (JSON array like search_properties), count_only semantics, fields defaulting to the Standard fieldset per get_fields, limit default 100/max 1000, start for paging, and sort format (e.g. AVM:desc) are all explained. Minor gap: it never defines what 'Standard fieldset' contains and the prose says 'count_only' while the schema property is 'countOnly'.
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 ('Fetch billable property rows for a property set matching criteria') and explicitly distinguishes itself from siblings by naming get_property_details for single RadarIDs, plus get_property_transactions, get_property_comps, and get_property_persons for depth. An agent can tell exactly what this returns versus its neighbors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use (bulk property rows from criteria), when-not (not for a single RadarID), and a recommended workflow: use count_only and search_properties before large/billable sets. It also clarifies that Saved Audience is handled via InList inside criteria rather than an audience_id parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch billable comparable Property rows for one subject Property by RadarID. PropertyRadar covers all 50 US states and DC nationwide. Required: radar_id. Optional: comp_type sales (default) or listings (for-sale only); limit defaults to 10 and must be 1–50; fields defaults to the currently available 19-id Standard fieldset and also accepts the 24-id All fieldset or validated comma-separated field ids; fieldsets span both comp kinds and ids not applicable to the active kind are omitted; CompDistance and ZipFive remain Product requirements with accepted engineering deferral to v2; subject overrides PType, Beds, Baths, Units, SqFt, LotSize, and YearBuilt; transfer_types is sales-only and listing_types is listings-only. Bills per returned comp row; subject_property is non-billable. Returns ranked results[], symmetric subject_property, returned_count, total_cost, radar_id, comp_type, fields, and related_tools[]. Never returns retired/raw comparables ids or REST debug keys. Do not loop this tool across many RadarIDs unless the user explicitly intends the multiplied per-row cost. Use get_property_details for scalar subject fields and get_property_transactions for recorder history.
| Name | Required | Description | Default |
|---|---|---|---|
| beds | No | ||
| sqFt | No | ||
| baths | No | ||
| limit | No | ||
| pType | No | ||
| units | No | ||
| fields | No | ||
| lotSize | No | ||
| radarId | Yes | ||
| compType | No | sales | |
| yearBuilt | No | ||
| listingTypes | No | ||
| transferTypes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal, and the description carries the full behavioral burden: bills per returned row while subject_property is non-billable, lists exactly what is returned, and states what is never returned (retired/raw ids, REST debug keys). The cost/loop warning is exactly the kind of side-effect disclosure an agent needs and cannot get from 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?
Purpose and required cost caveat are front-loaded, but it is a dense single paragraph mixing product-roadmap notes (CompDistance/ZipFive 'accepted engineering deferral to v2') that do not help an agent select or invoke the tool. That internal detail dilutes otherwise useful 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?
Despite no output schema, the description enumerates the return shape (results[], subject_property, returned_count, total_cost, radar_id, comp_type, fields, related_tools[]) and covers cost, defaults, and alternatives. For a 13-parameter billed tool, nothing material an agent needs 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?
With 0% schema description coverage the description must compensate, and it does for most params: comp_type semantics (sales default vs listings), limit default 10 with 1-50 bound, fields fieldset ids and default, transfer_types sales-only / listing_types listings-only, and the subject-override params. It leaves the exact semantics of beds/baths/sqFt/lotSize/yearBuilt overrides thin and uses snake_case names that do not exactly match the camelCase schema keys.
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 ('Fetch billable comparable Property rows for one subject Property by RadarID') and its scope. An agent can distinguish it from get_property_details (scalar subject fields) and get_property_transactions (recorder history) without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes to siblings ('Use get_property_details... and get_property_transactions...') and states a when-not condition ('Do not loop this tool across many RadarIDs unless the user explicitly intends the multiplied per-row cost'). Nothing is left to inference about when this is the right call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch authoritative scalar property fields from PropertyRadar by RadarID. PropertyRadar covers all 50 US states and DC nationwide; RadarIDs are issued for properties in any state. This is the billable property-record path and bills per API terms. Use after resolve_address or get_property_summary when the user needs exact fields beyond the summary bands — DistressScore, equity detail, or assessor/tax scalars. Do not use this tool to identify an owner; use get_property_persons after get_property_summary. Never returns nested arrays or person-extracted contact data; route phone/email to get_property_persons. The fields argument selects the Standard fieldset by default or a comma-separated list of field ids from get_fields. Contacts-group field ids are rejected.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | ||
| radarId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, which conflicts with a read-only fetch operation — but the description's billing context ('billable property-record path and bills per API terms') may justify the false readOnly flag. The description adds important behavioral context: it never returns nested arrays or person contact data, rejects Contacts-group field ids, and is a billable path. It does not explain the readOnlyHint=false discrepancy, leaving potential ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then usage conditions, exclusions, and parameter details. Every sentence adds value, though the billing note and state coverage could be more tightly integrated. Slightly verbose but well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters, no output schema, and sparse annotations, the description covers purpose, usage, exclusions, billing, and parameter behavior thoroughly. It adequately compensates for the lack of output schema by describing return character (scalar fields, no nested arrays, no contacts). Missing only details like error handling or rate limits, which are minor.
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 compensate. It explains the 'fields' argument semantics well: defaults to Standard fieldset, accepts comma-separated field ids from get_fields, and Contacts-group ids are rejected. The 'radarId' parameter is described indirectly via context (issued for properties in any state), but its format is not specified. Good compensation overall.
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+resource ('Fetch authoritative scalar property fields from PropertyRadar by RadarID') and clearly distinguishes itself from siblings like get_property_summary, get_property_persons, and resolve_address by specifying what it returns (scalar fields, not nested data) and what it doesn't (contacts).
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 use it ('after resolve_address or get_property_summary when the user needs exact fields beyond the summary bands') and when not to use it ('Do not use this tool to identify an owner; use get_property_persons'). Names alternative tools with conditions, covering routing to get_fields and get_property_persons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch billable person records associated with one Property by RadarID — owners, principals, trustees, and entities (not skip-trace parity). PropertyRadar covers all 50 US states and DC nationwide. Required: radar_id. Optional: count_only (true returns result_count and estimated_cost with empty results[], non-billable — use before purchase); fields (default Standard fieldset per get_fields(tool="get_property_persons"); comma-separated Product field ids allowed). Bills one billable unit per top-level person record retrieved. When the user asks who owns a resolved property, call this after get_property_summary; do not use get_fields or get_property_details for ownership alone. Returns priority-ordered flat scalar rows (primary contact first) with RecordStatus on every row and PersonID for contact-data follow-up. Phones, emails, and relatives are Phase 2 via get_person_phones, get_person_emails, and get_person_relatives (PersonID-scoped) — not on person rows. Not for property field export (use get_property_details). User outreach compliance (TCPA/CCPA) remains the subscriber responsibility.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | ||
| radarId | Yes | ||
| countOnly | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses billing semantics ('Bills one billable unit per top-level person record retrieved'), the non-billable count_only mode, the exclusion of phones/emails/relatives from person rows, the return shape (priority-ordered flat scalar rows with RecordStatus and PersonID), and compliance responsibility. These are substantive behavioral details beyond the sparse 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 purpose and key routing instructions are front-loaded, and nearly every sentence adds needed information. The single dense paragraph is effective but could be slightly more scannable; no sentence is clearly wasteful.
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 billing side effect, multi-tool routing, and absence of an output schema, the description covers everything an agent needs: purpose, prerequisites, alternatives, billing, return shape, and exclusions. Nothing material 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?
With 0% schema description coverage, the description fully compensates: it marks radar_id as required, explains count_only's return fields (result_count, estimated_cost, empty results[]) and billing status, and clarifies fields' default Standard fieldset and comma-separated Product field id format.
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 ('Fetch billable person records associated with one Property by RadarID') and enumerates the record types (owners, principals, trustees, entities). It explicitly distinguishes the tool from siblings by naming what it is not (skip-trace parity, property field export) and routes to 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?
Gives explicit when-to-use guidance: 'When the user asks who owns a resolved property, call this after get_property_summary; do not use get_fields or get_property_details for ownership alone.' It also instructs using count_only before purchase and names the Phase 2 tools for contact data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a model-safe summary of one Property by RadarID for single-property Q&A — not for bulk scoring, market sweeps, or looping across many RadarIDs. PropertyRadar covers all 50 US states and DC nationwide. Use after resolve_address when resolved is true, or when the user already has a RadarID. Never bills. Returns radar_id, provided_by, description, results with the fixed 14-field get_fields allowlist in registered order (city/state placement only — no street address or ZIP in results or description), optional field_notes for DistressBand and EquityBand, and related_tools[] pointing to billable depth (get_property_details, get_property_transactions, get_property_comps, get_property_persons). When the user asks who owns the Property, call get_property_persons next; do not call get_fields or get_property_details for ownership alone. Bands are coarse triage only — do not use summary for exact DistressScore, EquityPercent, distress signal types, owner contact, comps, sale history, building age, street address, or transaction rows; call the related billable tools instead. For market-level distress or equity characterization use search_properties (and get_properties_details when the user needs rows). This tool is distinct from future get_property_insights and is not for CSV/export workflows.
| Name | Required | Description | Default |
|---|---|---|---|
| radarId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, non-destructive, closed-world, but the description adds substantial behavior: 'Never bills', the exact return shape (radar_id, provided_by, description, results), the fixed 14-field allowlist, the deliberate omission of street address/ZIP, optional field_notes for DistressBand/EquityBand, and related_tools[] pointers to billable depth. It also flags the bands as coarse triage only.
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 purpose and scope, and nearly every clause carries routing or behavioral information. It is on the long side with some repetition of the exclusion set (bands as triage, no CSV/export, distinct from get_property_insights), which keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description enumerates the return payload, the fixed field allowlist, the deliberate omission of address/ZIP, and the related_tools pointers, so an agent knows exactly what comes back. Combined with annotations covering safety and a single documented parameter, nothing needed 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 coverage is 0% and the single parameter has no schema description, so the description carries the burden. It explains that radarId is a PropertyRadar identifier obtained via resolve_address or already known to the user, which meaningfully disambiguates the parameter beyond the bare 'radarId' string type.
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 ('Return a model-safe summary of one Property by RadarID') and immediately scopes it against siblings ('not for bulk scoring, market sweeps, or looping across many RadarIDs'). It also names what it is distinct from ('future get_property_insights') and rules out CSV/export workflows, so an agent can place it without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit preconditions ('use after resolve_address when resolved is true, or when the user already has a RadarID') and explicit exclusions (bulk scoring, market sweeps, looping). It routes specific intents to alternatives: ownership to get_property_persons, exact distress/equity/comps/history to the related billable tools, and market-level characterization to search_properties/get_properties_details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch billable recorder history (title chain) for one Property by RadarID — deeds, loans, liens, notices, releases, and child documents. PropertyRadar covers all 50 US states and DC nationwide. Status: Partial until isNewConstruction is available. Required: radar_id. Optional: count_only (true returns result_count and estimated_cost with empty results[], non-billable — recommend before purchase when chain size is unknown); limit (default 100, max rows on purchase); fields (default Standard; seven Product fieldsets plus comma-separated field ids via get_fields — API Fields cap is 500 ids per request); document_id (scope to one row; omitted fields defaults to All when document_id is set); document_group (csv of Mortgage, Deed, Foreclosure, Lien, Notice, Release, Other — server-side instrument-class filter; preferred over document_type for intent such as all foreclosures or all loans); document_type (raw DocType codes, server-side filter; AND with document_group when both set); date_range (YYYY-MM-DD,YYYY-MM-DD inclusive recording bounds, server-side RecDate filter); current_owner_only (Filter=CurrentOwner). Returns flat results[] with RecordStatus on every row. Bills one billable unit per row returned. Use get_fields(tool="get_property_transactions") before first purchase. Not for scalar property record (use get_property_details).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| fields | No | ||
| radarId | Yes | ||
| countOnly | No | ||
| dateRange | No | ||
| documentId | No | ||
| documentType | No | ||
| documentGroup | No | ||
| currentOwnerOnly | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, and the description explains why this is not a benign read: it 'Bills one billable unit per row returned,' while count_only is explicitly non-billable. It also discloses a status caveat ('Partial until isNewConstruction is available'), the return shape ('flat results[] with RecordStatus on every row'), and field-selection limits (500 ids cap) — all beyond what annotations 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?
Front-loaded with the purpose before the dense parameter rundown, and nearly every clause carries distinct information. However, the parameter block is a single semicolon-chained paragraph that is harder to scan than a short structured list would be.
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 9-parameter, billable, no-output-schema tool this covers everything an agent needs: prerequisites (get_fields), cost-safety path (count_only), status caveat, return shape, and per-parameter filtering behavior. Nothing material is left undocumented.
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 0%, so the description must carry the full burden and does: limit default 100 with purchase semantics, fields default Standard plus the 500-id cap, documentId scoping and its effect on fields defaulting, documentGroup csv vocabulary and its AND relationship with documentType, and dateRange's exact YYYY-MM-DD inclusive RecDate 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?
States a specific verb+resource+scope: 'Fetch billable recorder history (title chain) for one Property by RadarID,' then enumerates the document classes returned. It explicitly differentiates from a sibling ('Not for scalar property record (use get_property_details)'), so an agent can route without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives actionable when-to-use guidance: 'recommend before purchase when chain size is unknown' for count_only, and 'Use get_fields(tool="get_property_transactions") before first purchase.' It also names the exclusion (get_property_details for scalar records) and specifies document_group is preferred over document_type for intent-based filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Non-billable value lookup before search_properties. Required for every County name so the agent uses the returned positive integer FIPS criteria fragment; optional for an incomplete or ambiguous City or Subdivision. PropertyRadar covers all 50 US states and DC nationwide. Do not call for a complete City paired with a two-letter State because those values can be passed directly to search_properties. Required: suggestion_field (City, County, or Subdivision) and query (prefix/typeahead). Optional: criteria (API-format scope array, e.g. State before City or County) and limit. Returns results[] with label and criteria fragments exactly as the Suggestions API returns them — merge into search_properties without reformatting. Every success includes related_tools[] for get_criteria, search_properties, and create_dynamic_audience. Empty prefix matches return results: []. SiteAddress and other address fields are not supported — use resolve_address. Never bills.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| criteria | No | ||
| suggestion_field | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, but the description adds materially more: it is never billed, it echoes the Suggestions API payload shape verbatim, empty prefix matches return results: [], and every success carries related_tools[]. Those are behavioral facts an agent cannot derive from 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-loaded with the core purpose and requirement, then usage rules, then return shape — a sensible ordering with no filler sentences. It is dense and runs long for what is a four-parameter lookup, with a couple of clauses that could be tightened, but every sentence still carries actionable 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?
There is no output schema, yet the description specifies the return contract (results[] with label and criteria fragments as the Suggestions API returns them, plus related_tools[]) and the empty-match case. Combined with the required/optional parameter split and the sibling routing, nothing an agent needs to call this 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 0%, so the description carries the full burden and does so: suggestion_field is enumerated (City, County, or Subdivision), query is described as prefix/typeahead, criteria is an API-format scope array with an example (State before City or County), and limit is identified as optional. This adds meaning well beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (non-billable value lookup / suggestion resolution) and immediately scopes it as a pre-step before search_properties. It distinguishes itself from siblings by naming search_properties and resolve_address as the alternatives, so an agent can route without opening another 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?
Explicitly states when the call is required (every County name), when it is optional (incomplete/ambiguous City or Subdivision), and when NOT to call it (a complete City paired with a two-letter State, which goes straight to search_properties). It also excludes address fields and points to resolve_address, covering alternatives rather than leaving them to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a US street address to Property RadarIDs for disambiguation before single-property tools. PropertyRadar has nationwide coverage of all 50 US states and DC; do not skip this tool based on the state or region in the address. Returns a JSON envelope with query (echo of input), resolved (true only when exactly one suggestion), message (when resolved is false, truncated, or no match), suggestions[] (max 20; each row has non-null radar_id and full normalized address label with city, state, and ZIP when available), and total_match_count when multiple properties match or the list is truncated. This tool never bills. For model-safe Q&A without UI, call get_property_summary. If the user asks who owns the property, then call get_property_persons; do not call get_fields or get_property_details for ownership alone. Call get_property_details only when the user needs exact billable property scalars or distress indicators. When resolved is false, confirm the user's pick from suggestions[] before downstream tools; if truncated or many units match, add a unit number or use search_properties for the full property set.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only/non-destructive profile; the description adds substantial context beyond them—'never bills', the exact response envelope semantics (resolved only when exactly one suggestion), max 20 suggestions, truncation behavior, and the requirement to confirm the user's pick when resolved is false.
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: purpose, coverage caveat, return envelope, then routing guidance. Every sentence carries operational weight, though the sentence count is on the higher side for a single-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description supplies the full return shape (query, resolved, message, suggestions[], total_match_count) and the downstream confirmation workflow. Nothing an agent needs to invoke or follow up 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?
Only one parameter at 0% schema description coverage, so the description must carry the load—it specifies the input is a US street address, notes nationwide coverage, and describes the query echo. It stops short of stating format/length constraints, but adds clear meaning beyond the bare 'address: string' 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?
States a specific verb and resource ('resolve a US street address to Property RadarIDs') plus the goal (disambiguation before single-property tools), which clearly separates it from siblings like search_properties and get_property_details.
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 routes the agent: use this before single-property tools, do not skip based on state, call get_property_summary for model-safe Q&A, get_property_persons for ownership, get_property_details only for billable scalars, and search_properties when truncated. Names alternatives and exclusions directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Non-billable property set characterization for all 50 US states and DC nationwide. Required: criteria, a JSON-encoded array of {"name","value"} objects. Call get_criteria to discover criterion names and value shapes; this description intentionally does not enumerate them. Optional: includeFacets. Every success returns total_result_count, the criteria echo, purchase: 0, and related_tools rows. When includeFacets is true, signals contains flat facet-label counts when total_result_count is at least 25 with no upper cap, and is empty below that privacy floor. Never returns property rows, RadarIDs, addresses, criteria catalog data, or an applet handoff. Never bills. After a satisfactory search, recommend create_dynamic_audience to save the property set; marketing flows must not default to get_properties_details. Use get_properties_details with count_only before purchasing billable rows. Use get_properties_insights for grouped, tab-depth characterization beyond flat signals; that tool accepts only 25 through 100,000 results.
| Name | Required | Description | Default |
|---|---|---|---|
| criteria | Yes | JSON array of {"name","value"} objects using criterion ids and value shapes returned by get_criteria. | |
| includeFacets | No | Request flat aggregate signals. The API request uses Limit=0 because this tool never returns rows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare read-safe/open-world flags, so the description carries the rest and delivers: never bills, purchase: 0, never returns property rows/RadarIDs/addresses/criteria catalog/applet handoff, and a 25-result privacy floor that empties facets below it. These are non-obvious operational traits an agent could not infer from annotations or 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?
Purpose, required param, and return-shape facts are front-loaded before the routing advice. It is dense and slightly run-on in the return/edge-case sentences, but essentially every clause carries distinct operational information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param, no-output-schema tool, the description covers inputs (criteria source, includeFacets), guaranteed returns (total_result_count, criteria echo, purchase: 0, related_tools), suppression rules, and downstream tool routing. Nothing an agent needs to invoke it correctly is omitted.
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 value beyond it: criteria is explicitly a JSON-encoded {"name","value"} array sourced from get_criteria (session state the schema alone can't convey), and includeFacets triggers Limit=0 with privacy-floor semantics. Only minor added meaning missing (no value-shape examples, deliberately).
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 opening sentence states a specific scope (non-billable property set characterization, all 50 states + DC), and the name/behavior pairing makes the search operation unambiguous. It doesn't sharply contrast against get_properties_details or get_properties_insights in the first line, but later sentences do that work.
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 names prerequisites (call get_criteria first), alternatives and their conditions (get_properties_insights for grouped/tab-depth characterization at 25–100,000 results; get_properties_details with count_only before purchasing billable rows), and an explicit prohibition (marketing flows must not default to get_properties_details). This is textbook when/when-not/alternatives routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
