PropertyList: Spanish Property MLS

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

Annotations already cover read-only/idempotent safety, but the description adds substantial behavior: location_not_found error shape, explicit refusal to fall back to nationwide figures, price_unit semantics per search type, oracle.verified gating rules, sub-area municipality roll-up, and commercial listing handling. These are exactly the details an agent cannot infer from structured fields.

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

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

Five paragraphs is long, but it is front-loaded with purpose and each subsequent block covers a distinct edge case (location miss, price units, oracle verification, sub-area roll-up, commercial). Dense but not padded; the length is proportionate to the behavioral surface.

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 though an output schema exists (so return values need not be spelled out), the description covers error modes, verification caveats, and the commercial/homes split thoroughly. Nothing an agent needs to call this correctly appears to be 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 75%, and the description adds real meaning beyond it — property_types commercial families drive a completely different response path (asking prices, no oracle block) and search_type drives the price_unit labelling. It does not revisit the tenure (traspaso) parameter, but overall it meaningfully enriches enum interpretation.

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 aggregate market context for a Spanish area') and enumerates the exact outputs (active listing count, median price, mean price, median €/m², bedroom-band counts). This is distinguishable from valuation-oriented siblings like verified_valuation or listing_health 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 a clear triggering condition: 'Use this before recommending a price or commenting on whether a listing is good value.' It does not name an alternative (e.g. verified_valuation) or state when not to use it, so the when-vs-what-else routing is left implicit.

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

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

Annotations only give the generic false/true flags; the description adds substantial context: this is a staged mutation that changes nothing until confirm_action, it returns a preview plus an action_id, and it requires a linked PropertyList account because the change executes under the agent's own CRM permissions. These are exactly the behavioral facts 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?

Front-loaded with the staging behavior and the confirm dependency before the permission and account preconditions. Sentences are dense and each carries information, though the final account-requirement sentence is slightly parenthetical and could be trimmed.

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?

An output schema exists, so return-shape explanation is unnecessary, and the description still supplies everything else an agent needs: the staging/confirm lifecycle, the permission gates, and the account prerequisite. Nothing relevant to 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning for 'colleague' — supply the name as it appears in the CRM, and ambiguous matches are surfaced as a list rather than resolved silently. 'reference' is not elaborated beyond the schema, which holds it back from 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?

The opening sentence states a specific verb and resource with scope ('Stage assigning one of YOUR agency's listings to a colleague'), and the second sentence distinguishes it from the confirmation step by naming confirm_action. An agent can separate this from siblings like set_listing_status or move_pipeline_stage 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?

It spells out the two-step workflow (stage now, confirm_action later after the agent says yes) and enumerates who is permitted to invoke it: agency admins, anyone who can edit every listing, or the current assignee; unassigned listings are open to anyone with listing-edit rights. The alternative (confirm_action) and the gating condition are 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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description still adds real behavioral detail beyond that: result cap (10), ordering rule (biggest first), and the tie-break that a region group precedes a same-named city. It does not mention truncation or empty-result behavior, so it falls just short of 5.

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 that are front-loaded with the resource and followed by the routing guidance; every clause carries information. Slightly dense parenthetical enumerations of area types, but 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?

With an output schema present the description need not detail return values, yet it still summarizes them (id, name, type, parent, listing count, ranking). Inputs, ranking semantics, and the downstream call are all covered, 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?

Schema description coverage is 100%, so all three parameters (query, provinces, search_type) are already documented in the schema. The description adds only indirect meaning, e.g. that ranking and counts depend on the market implied by search_type, which is largely restated from the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb (look up) and resource (property areas: city, suburb, urbanisation, region/coast group), naming the accepted input (free-text name). It is clearly distinguishable from siblings like search_properties, which it explicitly feeds into.

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 when to use it ('resolve place names before calling search_properties'), covers the tricky case with concrete examples ('Nueva Andalucia' vs 'Nueva Andalucía', 'Marbella old town'), and specifies the handoff ('pass the chosen id to search_properties as location_id'). No inference required.

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

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

Goes well beyond the annotations: it states that nothing in the CRM changes, that the action_id becomes unconfirmable, that unconfirmed previews auto-lapse after 30 minutes, and that a linked account with the agent's own CRM permissions is required. This is meaningful behavioral and auth context the structured fields do not carry, and it is consistent with destructiveHint=false and idempotentHint=true.

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

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

Three sentences, front-loaded with the core effect, then the auto-lapse rule, then the auth prerequisite. The 'and the agent does not want' clause is slightly awkward but every sentence carries information; minor trimming would help.

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?

An output schema exists, so return values need not be described, and the annotations already cover the safety profile. What remains for a mutate-ish tool — whether anything changes, what happens to the id, expiry, and auth requirements — is all stated. 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 100% and the single action_id parameter is already documented ('The action_id from the preview'). The description reinforces that the id relates to a preview but adds no new format or syntax detail, so the baseline 3 applies.

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

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

States a specific verb ('Drop') and resource ('a change you staged'), and the phrase 'can no longer be confirmed' implicitly draws the boundary against the sibling confirm_action. An agent can tell what this does and which operation it is the inverse of.

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

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

Gives a clear when-to-use condition ('a change you staged and the agent does not want') plus a prerequisite (linked PropertyList account, agency API key alone insufficient). It also notes that an unconfirmed preview lapses after 30 minutes, implying cancellation is unnecessary then. It stops short of explicitly naming confirm_action as the 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?

Annotations already declare destructive/openWorld/non-idempotent, but the description adds material context beyond them: it can charge credits and send email, it re-validates client/listing/stage and silently no-ops with an explanation, previews expire after 30 minutes, each preview is single-use, and a linked PropertyList account with CRM permissions is required. That is exactly the extra behavioral disclosure the annotations cannot carry.

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 the gating rule, then the re-validation/expiry/auth caveats. Four short paragraphs with no filler, though the expiration and single-use rules could be tightened into one sentence without losing meaning.

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 destructive, credit-charging commit tool with an output schema already present, the description covers the safety gate, failure semantics, idempotency/expiry, and auth requirements. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100% and the single action_id parameter is fully documented as 'from the preview.' The description adds only the framing that the id originates from a staged preview, which the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource ('make a change you staged') and enumerates the exact staging siblings (move_pipeline_stage, qualify_lead, assign_listing, etc.) whose previews it commits. An agent can distinguish this from cancel_action and from the staging tools 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 gating condition: 'Call it ONLY after showing the agent the preview and hearing them say yes.' That is a clear when-to-use rule, and the sibling enumeration establishes the when-not (you stage with those tools, you commit with this one).

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

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

With annotations already declaring readOnlyHint=false, destructiveHint=false and openWorldHint=false, the description still adds real value: email-based de-duplication (existing contact returned instead of a duplicate created), the created contact's default state (unassigned, flagged as needing attention), and an auth prerequisite. Note the de-dup wording reads as effectively idempotent-by-email while idempotentHint=false; this is a nuance rather than a direct contradiction, but it is the one point where the two sources need reconciling.

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

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

Four short sentences, front-loaded with the core action and scope, then usage trigger, dedup behavior, and prerequisite. No padding or repetition of the schema, though the final prerequisite sentence could be folded more tightly.

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?

An output schema exists, so return shape need not be explained. For a create tool with clean annotations, the description covers action, trigger, side effects, de-duplication, default state and auth prerequisite — everything an agent needs 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 100% across all 5 parameters, so the schema already documents name, email, phone, surname and company_name. The description adds only that email drives de-duplication, which is already stated in the email field's schema description, so the baseline 3 applies.

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

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

States a specific verb+resource and scope: 'Add a new contact to YOUR agency's CRM', with a clarifying list of the entities involved (buyer, owner, enquirer). It is readily distinguishable from the read-side sibling find_contacts, though no sibling is named explicitly.

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

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

'Use when the agent wants to save a person (buyer, owner, enquirer)' gives a clear trigger condition, and the prerequisite of a linked PropertyList account or agency API key is stated. It does not name alternatives (e.g. submit_enquiry, log_note) or exclusion cases, so it falls short of a full when/when-not routing rule.

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 annotations: discloses the output is a DRAFT, never published, never on portal, requires agent follow-up in CRM, response includes a direct link, requires linked PropertyList account or API key, and location is resolved against a real area tree. Annotations only say non-readonly, non-idempotent, non-destructive; description adds the critical publishing 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?

Front-loads the draft-never-published constraint, a crucial disclosure. The commercial-properties paragraph is denser but earns its place given 24 params. Slightly long but well-organized into distinct concerns.

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 24 params, output schema present, and the high-stakes nature of listing creation, the description covers the key gaps: draft status, account requirements, location resolution, and the commercial variant rules. Nothing critical is missing for correct 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 coverage is 92% so baseline is high, but description adds substantive commercial-property semantics: commercial types need no bedrooms and specific facts, tenure/traspaso explanation, and location-resolves-by-name behavior. Adds meaning beyond raw enum lists 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?

States a specific verb (create) and resource (property listing draft) with explicit scope: 'in YOUR agency's CRM'. Clearly distinguished from siblings like my_listings (read) and set_listing_status (mutate existing).

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

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

Gives a clear triggering context: 'when the agent is describing a property they have taken on and wants it in the system.' Doesn't explicitly name alternatives or exclusions, but the context is unambiguous enough to route correctly.

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 readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the auth requirement (linked account or API key) and the strict tenancy scoping ('only ever searches the calling agency's own contacts'), which materially changes how an agent should interpret empty 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?

Three tight sentences that lead with what the tool does, then when to use it, then the auth/scoping constraint. No filler, no redundancy; each sentence carries distinct 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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. The description covers purpose, usage trigger, auth prerequisites, and tenancy scoping — everything an agent needs to decide when to call it and how to read the result boundary.

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 50%: the query parameter is documented in-schema, but limit is only constrained structurally (default 20, max 50) with no prose. The description restates the query semantics (name/company/email/phone) but says nothing about limiting result count, so it neither compensates for the gap nor adds meaning beyond 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?

States a precise verb+resource+scope: search the calling agency's own CRM contacts, with the searchable fields (name, company, email, phone) enumerated. This clearly distinguishes it from siblings like create_contact, my_leads, and find_properties_by_description without needing to open 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 concrete when-to-use context ('look a person up before logging a note or to check if they're already in the CRM') and names a prerequisite (linked PropertyList account or agency API key). It does not explicitly name create_contact as the write-side alternative, so the routing guidance is strong but not 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 readOnly/idempotent/non-destructive, so the safety profile is covered. Beyond that, the description adds real behavior: sort order, fields carried per listing, the location_not_found error surfaced as zero results, and exclusion of 'price on application' listings. Some of this (returned fields) overlaps the output schema, so it is not a 5.

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 definition, then ordering, then usage, then filter/edge-case behavior. Every sentence carries information, though the 'Each listing carries...' enumeration leans slightly verbose given an output schema exists.

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, zero-required read tool with annotations and an output schema, the description covers purpose, ordering, usage, filter inheritance, and key edge cases (location_not_found, P.O.A. exclusion). Nothing critical is missing, though pagination/limit behavior is left entirely to the schema.

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

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

At 67% schema coverage, the schema documents days/limit/min_percent/search_type but the description adds a useful cross-reference ('filters work as in search_properties') tying location/type/bedrooms/price semantics to a sibling tool, plus the location_not_found edge case. It does not add syntax detail, so it stays above baseline without being exhaustive.

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: 'Live listings whose asking price has been reduced recently', plus the display ordering ('biggest reduction first'). An agent can immediately distinguish this from search_properties or find_similar_properties without opening any schema.

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

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

Provides concrete use-case framing ('what has dropped in price in Estepona this month?', 'to spot motivated sellers') and notes filters behave as in search_properties. It stops short of naming a sibling to prefer instead or stating explicit when-not-to-use conditions, so it is strong context but not 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 only cover the read-only/idempotent safe-read profile; the description goes far beyond them, disclosing the quota model (daily allowance without a key, larger with a key, briefs that find nothing don't count), the exact failure mode when exhausted, the result cap (up to 9 listings with scores and an interpretation explanation), and that commercial premises are never mixed with homes.

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

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

Front-loaded with the core purpose and the when-to-use condition before quota mechanics, and nearly every clause carries new information. The parenthetical marketing example and the feature list are slightly padded, but nothing is wasted or buried.

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

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

For an open-ended semantic-search tool with an output schema already describing the return payload, the description covers everything the agent needs: invocation form, quota and error behavior, result cap, interpretation feedback, and residential/commercial separation. No material 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 50%: 'brief' is documented in the schema, while the 15-value 'language' enum has no description at all and is not addressed in the tool description. The description does compensate well for 'brief' — explaining what a brief can contain, that features like pool/sea view act as filters, and that vague conditional phrasing is supported — but the language parameter remains undocumented.

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 (match) and resource (Spanish properties) from a free-form brief, and names the sibling it contrasts with (search_properties for structured queries). An agent can distinguish it from search_properties and find_similar_properties 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?

'Best for vague, conditional, or lifestyle-heavy briefs' gives clear selection context with an example, and the closing sentence routes structured queries to search_properties. It never states an explicit 'do not use this when...' exclusion, so it falls just short of the top band.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for adding ordering semantics ('closest in price first') and the matching rules that determine results. It also flags that returned properties carry oracle_verified and oracle_attestation_url, useful output enrichment beyond the annotations.

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

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

Front-loads the core similarity definition and the use cases, with the oracle field note placed last. Two tight sentences plus a short caveat; the trailing note is slightly tangential but relevant to what comes back.

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?

An output schema exists so return values need not be explained, and the description covers matching logic, ordering, and a data-freshness/verification flag. Adequate for an agent to call correctly, with only minor gaps around limit/language semantics.

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 67%, with limit undocumented in the schema. The description compensates partially by defining what 'similar' means, which governs how the required reference parameter is interpreted, and by clarifying price ordering. It still doesn't explain the limit or language parameters directly.

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

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

States a specific verb and resource (find listings similar to one property) and enumerates the exact similarity dimensions: same market, town, home type, bedroom count, price within ~25%. This distinguishes it clearly from siblings like search_properties, find_price_reductions, and find_properties_by_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?

Provides concrete trigger examples ('show me alternatives to PL12345', 'anything like this but cheaper?') so the agent knows the intent that selects this tool. It does not explicitly name a competing sibling to route away from, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is well covered. The description adds meaningful context beyond that: it requires a linked PropertyList account (or agency API key), it only ever reads the calling agency's own contacts, and it is scoped to those the caller may see in the CRM. That permission/auth disclosure is real value over 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 full content picture, then the workflow guidance (where to get the ID and when to call). The long facet list is informative but borders on verbose; still, every clause maps to a returned field, so it earns its place. Slightly dense 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?

For a single-param read tool with an output schema, the description covers purpose, prerequisites, workflow position, and access/permission constraints. The output schema handles return values, so no return-format detail is needed. Nothing material is missing for correct 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% and the single parameter contact_id is already documented in the schema with its origin (find_contacts or my_pipeline). The description reinforces the same source, which is redundant but not harmful. Baseline 3 applies when the schema does the heavy lifting; the description adds no new syntax or format 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 (get) and resource (contact), and enumerates the returned facets (contact details, pipeline position, agents, saved searches, enquiries, notes, viewings, listings sent, last contact, next booking). This clearly distinguishes it from find_contacts/my_pipeline, which are search tools that locate IDs rather than retrieve the full record.

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 tells the agent where to get contact_id (find_contacts or my_pipeline) and when to call it: 'before advising an agent on a client, and before match_buyer_to_inventory, so you know what has already been sent.' This names the prerequisite and the downstream consumer, which is exactly the routing guidance needed.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavior: truncation handling via next_offset, the meaning of last_reviewed being set vs null, and a scope disclaimer that this is general information, not legal/tax advice.

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

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

Four short sentences, each carrying a distinct instruction (what to read, how to answer, truncation follow-up, disclaimer), with the core purpose front-loaded. 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?

With an output schema and full annotations present, the description only needs to cover interpretation and edge cases, which it does (truncation loop, review-date wording, disclaimer). An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining the offset/next_offset continuation contract and tying last_reviewed to output interpretation. This adds meaning beyond the raw schema property 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?

"Read one PropertyList guide" gives a specific verb and resource, and "one" implicitly contrasts with the sibling search_guides (plural/search). It's clear what the tool does, though it never names the alternative explicitly.

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

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

It gives concrete follow-up rules (if truncated is true, call again with offset set to next_offset) and instructs how to present last_reviewed. It stops short of stating when to use this vs search_guides to obtain the URL, which is left to the schema note.

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

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

With annotations already declaring read-only, idempotent, non-destructive, and closed-world behavior, the description adds substantial operational context beyond them. It discloses daily allowance rules, per-IP versus per-account counting, the error-and-limits response when exhausted, photo-tier behavior, and nuanced location/coordinate precision semantics. It also explains commercial-premises return fields and that direct phone/email details are not part of the payload.

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 front-loads the core purpose and then organizes secondary details into paragraphs. Most content earns its place because it clarifies tiered access and return-field semantics beyond the output schema. It could be tightened slightly, but the length is justified by the tool's allowance, photo, location, and commercial nuances.

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 output schema exists, the description does not need to enumerate every return field, yet it supplies critical context for interpreting errors, limits, photo coverage, location.city versus location.municipality, coordinate precision, and commercial premises. It pairs well with the annotations and leaves no significant gap for correct invocation or interpretation.

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 50%: reference is documented in the schema, while language has an enum but no description. The description repeats the reference-code format (e.g., 'PLE-12345') and does not explain the language parameter or its default. With the schema already covering the required parameter and no added semantics for the optional one, this meets the baseline for partial 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: fetch the full record for one PropertyList listing by reference code. It differentiates itself from search_properties and find_properties_by_description by describing the settled-listing use case, and it routes agency-contact needs to submit_enquiry. An agent can identify the tool without opening the schema.

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

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

It gives explicit timing and alternatives: use this once the user has settled on a listing from search_properties or find_properties_by_description and wants details/photos, and use submit_enquiry for agency contact. It also states when the free allowance allows use versus when MCP Pro or an agency feed is required. This covers when to use, when not to use, and which sibling to use instead.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds the ranking behavior (by active listing count) and a result cap, but 'Returns up to 10 agencies' conflicts with the schema's limit maximum of 25, which could mislead an agent about result size.

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

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

Three tight sentences, front-loaded with the core action and ordering, then output fields, then usage. The enumeration of return fields is somewhat padded given an output schema exists, but nothing is genuinely 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?

Safety profile is covered by annotations and return values by the output schema, and the description supplies the domain (Spanish area) and workflow context. The missing piece is any explanation of the limit parameter and the correct resolution of the 10-vs-25 discrepancy.

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 50%: location is documented in the schema, but limit is undocumented in both schema and description. The description never mentions the limit parameter and instead asserts a fixed cap of 10, which the schema contradicts (max 25), so it fails to compensate for the coverage 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?

States a specific verb and resource ('Find PropertyList agencies (estate agents)'), plus scope (a given Spanish area) and ordering (ranked by active listing count). It is clearly about agencies rather than properties or market stats, though it never names a sibling tool to make the boundary explicit.

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

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

Gives a concrete when-to-use situation: 'Use this after a buyer has narrowed in on an area and wants to know which agencies dominate it.' It lacks explicit when-not or named alternatives (e.g., area_market_summary), 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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely useful context beyond them: the account linking/API key requirement and the own-listings-only auth boundary, which an agent must know 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-loaded with the core purpose, then a scannable bulleted breakdown of issue definitions, then scope and prerequisites. Every element earns its place; the multi-line issue definitions are long but are precisely the information that makes the tool callable.

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 an output schema present, return values need not be described, and the description covers purpose, issue semantics, scope defaults, and auth prerequisites. It is essentially complete for a read-only diagnostic tool; only the absence of explicit alternative-routing keeps it out of the top tier.

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 33%, so the description must compensate, and it does: it defines what each 'issue' enum value actually means (90 days online, no enquiry in 60 days, fewer than 5 photos, etc.) and spells out the 'status' semantics. Only 'limit' goes unexplained, but its default and bounds are already 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?

States a specific verb and resource (checks the calling agency's own listings and lists the problematic ones), and enumerates the exact issues detected. It is clearly distinguishable from siblings like my_listings or search_properties, which cover general listing retrieval rather than diagnostic auditing.

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?

Explains the default scope (online listings) and what the 'draft' and 'all' status values select, plus the prerequisite of a linked PropertyList account and the own-listings-only restriction. It does not name a sibling tool as an alternative when this diagnosis is not the right call, so it falls short of the explicit when-not guidance a 5 requires.

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 this is a non-read-only, non-idempotent write. The description adds real value beyond them: the note surfaces on the contact/property timeline, and an auth prerequisite (linked PropertyList account or agency API key) is disclosed. It stops short of noting duplicate-note risk or what the write returns, but the added context is substantive.

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 action and scope, then parameters, then the auth prerequisite. Three short sentences with little waste, though the parenthetical example and the account requirement could be tightened slightly.

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?

An output schema exists, so return values need no explanation. For a simple three-parameter write tool, the description covers purpose, target entities, the parameter relationship, and the account prerequisite — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not enforce: it frames contact_id and property_reference as an 'and/or' pair where at least one is expected, even though the schema marks only 'note' as required. It also reiterates that contact_id comes from find_contacts, aiding correct invocation.

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 ('Log a note against a contact or a listing in YOUR agency's CRM') plus concrete examples of use ('record a call outcome or a viewing'). It also distinguishes itself from the sibling find_contacts by naming it as the source of the contact_id, so an agent can route between them 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 clear context for when the tool applies (recording call outcomes or viewings) and states the prerequisite of a linked PropertyList account or agency API key. It does not name an alternative tool or state when not to use this one, 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.

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

Annotations already declare readOnly/idempotent/non-destructive, and the description layers on behavior the annotations cannot: result ordering, the no-search fallback that returns an explanation, the required linked PropertyList account or agency API key, and the scope limit to the calling agency's visible clients. Return format specifics are absent, but an output schema exists, so this is close to complete.

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 result definition and structured into short paragraphs, but a few clauses are redundant ('the same search the CRM runs for that client') and the auth/scope sentence is dense. Slightly verbose without being 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?

For a read-only lookup with an output schema, the description covers the essentials: what is returned, ordering, fallback behavior, auth prerequisites, and data scope. Minor gaps remain around limit/pagination behavior and what distinguishes 'shared MLS' listings, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 67%. The description adds real value for contact_id (source it from find_contacts or my_pipeline) and implies the limit's meaning via 'listings that fit', but says nothing about limit bounds/default or the language enum, which the schema already documents. This is the baseline 3 for a partially covered 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+resource and scope: the listings matching one client's search within the caller's agency CRM, with explicit ordering (own listings first, then shared MLS, newest first). It is clearly distinguishable from siblings like match_inventory_to_buyers (reverse direction) and search_properties (unsaved-search fallback), which are both named in context.

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 (client with a saved search or described search), when-not (client with no search returns an explanation rather than a guess), and the alternative ('use search_properties instead'). It also names the prerequisite tools (find_contacts for contact_id, get_contact to see what has been sent).

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 readOnly/idempotent/non-destructive/closed-world, and the description layers on genuinely extra behavior: only online listings produce matches, drafts return an explanation instead of matches, output includes assigned agent, pipeline stage and the matched search, plus an auth requirement (linked PropertyList account or agency API key) and a visibility scope constraint.

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 organized into scope, constraints, and requirements. Parenthetical asides add useful detail without derailing, though a sentence or two could be tightened.

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 an output schema present, return values need not be specified, and the description still covers auth, visibility limits, and non-match behavior. The only real gap is the unexplained limit parameter.

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 50% — property_reference is documented in the schema (including the PL12345 example) and the description adds nothing to it, while the limit parameter is undocumented in both schema and description. Given only two parameters and a self-evident numeric bound, this is adequate but not compensating for the 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?

States a specific verb and resource — matching CRM clients whose saved search fits a given listing — and frames the outcome ('who to call about it'). The direction of the match is clear and distinguishable from the sibling match_buyer_to_inventory.

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

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

Gives clear context: works for own listings and shared MLS listings the agency can sell, only online listings are matchable, drafts return an explanation, and get_contact should be used for the full picture. It never explicitly names the reverse-direction sibling match_buyer_to_inventory as the alternative, so it falls short of full when-not 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 only declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds high-value behavior the annotations cannot convey: nothing changes until confirm_action, a preview plus action_id is returned, and a linked PropertyList account is required because the change is made under the agent's own CRM permissions.

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 the staging semantics before the exceptions. The three short paragraphs are dense with distinct information (staging flow, alternatives, auth), though the offer-stage and account-requirement notes could be tightened slightly.

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 non-idempotent mutation gated behind confirmation, the description covers the preview/confirm contract, the auth prerequisite, the sibling routing, and the conditional parameters. An output schema exists for the preview and action_id, so return-value detail is correctly left out.

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 already 80%, but the description adds genuine meaning: the stage value must match the board's own naming (with my_pipeline as the source), and it explains the conditional pairing of offer_amount with an offer stage and property_reference only when the card has no listing yet.

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 ('Stage a move of a client's card to another step on a pipeline board') and immediately scopes it to boards the client is already on. It explicitly distinguishes itself from qualify_lead and from Won/Lost moves done in the CRM, so an agent can separate 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 explicit when-not guidance: adding a client to a board they are not on, or qualifying a lead, is qualify_lead; Won and Lost are done in the CRM. It also documents the required two-step flow (stage, then confirm_action after the agent says yes), which is the single most important usage constraint for this tool.

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 readOnly, idempotent, non-destructive and closed-world, and the description adds context beyond them: an authentication prerequisite (linked PropertyList account or agency API key), tenancy scoping (only ever returns the calling agency's own leads), and result ordering. That is exactly the kind of behavioral detail structured fields cannot carry.

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 action and ordering, then the trigger, then the sibling contrast and the caveat. Slightly longer than strictly necessary (the CRM/inbox framing is repeated), but every sentence carries information and none is filler.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile. Combined with the auth requirement, tenancy scope, ordering, and the inbox-vs-pipeline mental model, an agent has everything needed to call this correctly and to interpret an empty result.

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

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

The description says nothing about limit, since, or property_reference. Schema coverage is a middling 67% – since and property_reference are documented in the schema while limit relies on default/min/max alone – so the schema does most of the work and the description neither compensates for nor extends it. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List recent enquiries (leads) for YOUR agency's CRM') plus ordering ('newest first'), and explicitly distinguishes itself from the sibling my_pipeline. An agent can tell it apart from my_pipeline or my_listings 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 an explicit trigger ('Use when the agent asks what has just come in'), names the alternative tool for the other case (my_pipeline), and adds a genuine exclusion-style caveat: an agency working off boards can have a busy CRM and an empty inbox, which is not the same as no leads. 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.

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

Annotations already establish readOnly, idempotent, closed-world behavior. The description adds genuinely non-structured context: the auth requirement, the agency-only scoping, and newest-first ordering. It stops short of describing result shape or pagination behavior, which is acceptable given an output schema exists.

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

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

Three tight sentences, front-loaded with the core action and scope before the usage examples and prerequisites. No filler, though the parenthetical usage examples add a little bulk.

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 list tool with an output schema, the description covers what an agent needs: scope, ordering, filters, and the account prerequisite. The unmentioned limit parameter and absence of result-shape notes are minor given the output schema.

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

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

Schema coverage is 67% and the status enum is already richly documented in the schema itself. The description only restates that filtering by status or reference is possible and does not explain the limit cap or default, so it adds little beyond the structured fields.

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

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

States a specific verb and resource ('List YOUR agency's own property listings') with ordering ('newest first') and scope ('only ever returns the calling agency's own properties'). This clearly distinguishes it from sibling search_properties, which covers all 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 concrete usage triggers ('show my listings' / 'is reference X still online?') and a prerequisite (linked PropertyList account or agency API key). It implicitly separates itself from the broad search sibling by scoping to the caller's own properties, though it never names the alternative explicitly.

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 readOnly/idempotent/non-destructive, but the description adds context annotations cannot: the tool returns the WHOLE agency's boards rather than one agent's cards, CRM access belongs to the agency not a person, and only the calling agency's own data is ever returned. It also warns that stage names are agency-renamed and must be read from the reply rather than assumed.

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 purpose, then boards/stages, then usage branching, then the sibling alternative, then access scope. Each paragraph carries distinct information with no repetition of the name or title.

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 an output schema present, return values need not be explained, and the description still covers everything else an agent needs: board enumeration, stage-name variability, the summary vs. filtered call pattern, the my_leads alternative, and the account/auth prerequisite. 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?

Schema coverage is 100% so the baseline is 3, but the description adds real semantics beyond the schema: it explains that stage names are user-renamed and should be read from the response, and reinforces the summary-vs-board behavior of omitting pipeline. It does not elaborate further on limit/stage beyond what the schema already states.

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

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

States a specific verb and resource ('List the cards on YOUR agency's CRM pipeline boards (Kanban)') and immediately enumerates the six boards and what each card represents. It clearly distinguishes itself from the sibling my_leads by naming it and the distinct scenario it serves.

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 branching: call without pipeline for a summary of every board (with concrete example questions), call with a pipeline for that board's cards. It also names the alternative tool my_leads and the condition ('enquiries that have just arrived and have not been worked yet') that selects it, plus the prerequisite of a linked PropertyList account or agency API key.

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

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

Goes well beyond the annotations by disclosing the two-phase preview/confirm flow, that NOTHING changes or is charged until confirm_action is called, the cost model (free place or one credit on the Buyer board), and the auth requirement (linked PropertyList account, action taken in the agent's own name with CRM permissions, agency API key alone insufficient). This is exactly the behavioral context annotations cannot carry.

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 the preview/confirm constraint, and each paragraph earns its place (inference rules, search persistence, auth prerequisite). It runs long for three parameters, but the density is high and largely justified rather than padded.

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

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

Covers the mutation's prerequisites (account linkage, permissions), the cost consequence, the confirm gate, and the conditional board/search semantics. An output schema exists, so return-value detail is correctly left out; nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the inference rules for `board` when omitted, that `board` places the client at the board's first step, and that `search` is persisted with the qualification but must not mix residential and commercial premises in one search.

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 (stage qualifying a client) and precisely what happens: tag as buyer/seller/tenant, place on a pipeline board, remove from the Lead board. It also distinguishes itself from siblings like confirm_action and move_pipeline_stage by describing the full board-transition effect.

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?

Explains conditional behavior clearly: without `board` the type is inferred from CRM knowledge (with a fallback of asking for details), and with `board` the client goes to that board's first step. It also names the mandatory follow-up (confirm_action with the returned action_id), giving a clear call sequence, though it never explicitly contrasts with siblings such as move_pipeline_stage.

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?

Adds substantial context beyond the annotations: nothing is persisted until confirm_action is called with the returned action_id, a preview is returned, times default to Europe/Madrid, and a linked account with the agent's CRM permissions is required. These are real behavioral constraints (write staging, auth model, timezone semantics) that the readOnly/destructive/idempotent hints 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?

Front-loaded with the core action and the staged-write caveat, then layered caveats (MLS, timezone, account requirement). Each sentence carries real information, though the prose form is drier and slightly longer than strictly necessary.

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?

An output schema exists, so return values (preview and action_id) need no further explanation. Combined with the account requirement, timezone default, and confirm workflow, an agent has everything needed to invoke this correctly in sequence with confirm_action.

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 60%, and the description compensates by explaining that property_reference may be the agency's own or a shared MLS listing and by clarifying timezone handling for starts_at. It leaves duration_minutes and notes unmentioned, so it adds meaningful but not complete parameter context.

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 ('Stage a viewing in the agent's own CRM diary') plus the scope ('with the client and the listing on it'), and flags the two-phase nature vs. confirm_action. An agent can distinguish this from sibling tools like confirm_action, cancel_action, and submit_enquiry from the text alone.

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

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

Clearly gives the workflow context: stage now, then call confirm_action after the agent agrees, and notes that MLS listings are not contacted. It also states the prerequisite (linked PropertyList account). No explicit when-not guidance or alternative-tool routing beyond confirm_action, so it stops just short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds behavioral value the annotations do not: the accent-sensitivity of Spanish queries and the search-then-fetch workflow with get_guide.

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, tightly front-loaded: scope first, then usage plus the alternative, then the accent caveat. The topic enumeration is dense but directly defines search coverage, so every element 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description still supplies what is genuinely missing: scope, when-to-use, the get_guide follow-up, and the accent requirement.

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 documents query and language but not limit (67% coverage). The description compensates by adding a real semantic constraint on the query parameter — Spanish terms must carry accents or they will not match — which goes beyond the schema's keyword-count guidance.

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 (search) and resource (PropertyList's guides), and enumerates the actual scope: Spanish taxes (ITP, IBI, non-resident income tax), NIE, buying process, laws, area guides. It is clearly distinguishable from get_guide, which it names as the follow-up.

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

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

Explicitly says when to use it ('how-to, cost and legal questions') and what to do next ('then call get_guide for the page'). It also flags a practical usage precondition: Spanish terms need accents to match (tributación, tasación).

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 readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses a daily result allowance, the shape of the exhausted-allowance response (empty plus `error` and `limits`), the strict no-substitution behavior on unknown locations (error: location_not_found), and the meaning of oracle_verified/oracle_attestation_url.

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 purpose, alternative, and licensing before the deep field semantics, and every paragraph carries an actionable detail. It is nonetheless long and some feature text overlaps the schema, so it is dense rather than maximally tight.

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 14-parameter, zero-required search tool with an output schema, the description still covers the edge cases an agent must handle (empty allowance, location_not_found, feature matching, coordinate precision). Nothing needed 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?

Despite 64% schema coverage, the description adds real semantics the schema lacks: private_pool vs communal_pool feed-tagging caveats with a widening strategy, the `location_id` group-id behavior, `location.city` vs administrative `municipality` resolution, and coordinates_precision values. This meaningfully exceeds what the schema documents.

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 ('Search PropertyList's full Spanish property MLS by structured filters') and immediately distinguishes itself from the sibling find_properties_by_description by scope ('queries that translate cleanly to fields' vs 'free-form briefs'). An agent can route between the two search tools 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?

Explicitly names the alternative (find_properties_by_description) and the condition that selects it, then specifies eligibility ('free use... for an assistant answering a person's questions') and when a paid plan is required ('reading listings in bulk, or showing them on a website'). Both when-to-use and when-not-to-use are covered.

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

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

Goes well beyond the annotations by disclosing that it is a two-phase stage-then-confirm operation, that it returns a preview plus action_id, that nothing is sent until confirmed, the 10-listing cap, that it appears on the client's timeline, and that a linked PropertyList account is required so an agency API key alone is insufficient. This is exactly the behavioral context annotations cannot carry.

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 the critical safety constraint (nothing sent until confirm_action). The three-paragraph layout is scannable, though the account-permission paragraph could be tightened.

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?

An output schema exists, yet the description still summarizes the return (address, subject, message, listings, action_id), and it covers the prerequisites, limits, and side effects an agent needs. Nothing essential is missing for a 4-parameter mutation tool.

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

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

Schema coverage is 50%, and the description compensates: it clarifies message is written in the client's language, subject/message are authored by the agent, and property_references are the agency's own or shared MLS listings sourced via match_buyer_to_inventory, capped at 10. The exact reference string format is still left to the schema, so not quite 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 (stage an email with listings attached to a client) and immediately scopes what it is not: nothing is sent until confirm_action. An agent can distinguish it from confirm_action, match_buyer_to_inventory, and the other siblings from the description alone.

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

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

Explicitly states the workflow condition: stage first, then call confirm_action with the returned action_id after the agent has read it and said yes. It also names match_buyer_to_inventory as the way to source listings, giving a clear alternative path.

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 carries rich behavior the annotations cannot: this is a two-phase preview/confirm flow where 'NOTHING changes' until confirm_action, publishing runs CRM-equivalent validation (photos, required details, agency listing limit), private listings incur a credit cost shown in the preview, and a linked PropertyList account is required because the change is made in the agent's name, so an agency API key alone is insufficient. This is exactly the kind of auth, cost, and reversibility context that structured fields omit.

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 the preview/confirm contract, then layers validation and auth details in separate paragraphs. Information-dense with no clearly wasted sentence, though the parenthetical asides make it slightly heavier than necessary.

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 mutation-style tool with an output schema (the preview), the description supplies everything an agent needs to call it correctly and safely: the two-step commit requirement, the downstream confirm_action contract, validation behavior, cost implications, and the account-linking prerequisite.

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 75%, and the description adds real meaning beyond the schema: it clarifies the semantics of each status value (what 'online' actually triggers, when 'sold' is valid) and explains that sale_price is recorded for market statistics unless hide_sale_price is true. It does not, however, add format or range detail for reference.

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 (stage) plus the exact resource and the three target states (online/offline/sold), and distinguishes itself from create_listing by being a status transition on an existing listing ('one of YOUR agency's listings'). An agent can tell immediately what it does.

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?

Explains the context of use (staging a listing online/offline/sold) and routes the agent to the mandatory follow-up sibling, confirm_action, with the action_id. It also constrains 'sold' to a sale listing that is online or offline. It lacks an explicit 'do not use this for X, use create_listing instead' exclusion, 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.

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

Goes well beyond the annotations: it discloses rate limits (small daily allowance per IP/account; 40 per key per 24h), that the agency receives the lead in their CRM and follows up, and requires explicit user intent and consent. The annotations only cover mutation/openWorld/idempotency, so this added context is genuinely valuable.

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 purpose then flows into usage, transport details, limits, and consent. Most sentences carry useful information, though the rate-limit and consent material runs a little long for the core action.

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 mutation tool with an output schema available, the description covers purpose, timing, alternatives, consent prerequisites, and quota behavior. Nothing an agent needs to call it correctly is missing, and return values are delegated to the output schema.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, establishing a baseline of 3. The description adds only marginal value by noting the reference comes 'from search results' and that both reference and contact details are required, without clarifying the optional message or language fields.

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 ('Submit an enquiry (lead) about a specific listing') plus the actor ('on behalf of a prospective buyer or tenant'). It explicitly distinguishes itself from sibling tools by noting it is the only supported contact path, so an agent can tell it apart 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 an explicit trigger ('once the user has chosen a property and wants the agency to contact them') and names the alternative scenario ('direct phone or email details are not exposed by other tools'). The consent precondition further constrains when it should and shouldn't be called.

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

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

Annotations only declare read-only/idempotent safety; the description goes well beyond by disclosing source provenance per country (notarial register vs. INE vs. Cyprus Statistical Service), what `verified`/`transaction_backed`/`source_label` mean, the 10-transaction threshold, band widening with thin evidence, and rollup/segment-resolution behavior. This is exactly the extra context that prevents misuse.

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

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

Long (~350 words), but front-loaded with what it returns before the caveats, and each paragraph carries distinct, non-redundant guidance (verification, rollup, segment resolution, commercial exclusion). Slightly verbose, yet the length is largely justified by the tool's real 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?

For a four-parameter tool with no required params, output schema present, and zero annotation constraints on behavior, the description covers sources, verification semantics, geographic limitations, rollup handling, segment fallbacks, and the sibling alternative — nothing material an agent needs to call or cite it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `reference` pulls municipality/type/size from a listing, `build_sqm` triggers an indicative valuation, `property_type` resolves to the nearest attested segment, and `location` is ignored when a reference is given. Only the enum-free slug semantics are left slightly informal.

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 names a specific verb and resource (valuation for a property or area) and scopes it by geography and data source ('recorded market data, not asking prices'). It also distinguishes itself from area_market_summary, which it names as the asking-price 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?

Explicit routing rules: use area_market_summary when no attestation covers the area, check `verified` before citing, never quote a rolled-up figure as the sub-area's own price, and expect no figure for commercial segments. It states when-not-to-cite conditions 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.