PropertyList: Spanish Property MLS

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

The description discloses extensive behavior beyond the annotations, including location resolution failures, ambiguity handling, price-unit semantics, oracle verification rules, sub-area roll-up behavior, and commercial-property restrictions. These are precisely the operational details an agent needs to avoid misrepresenting the returned figures.

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

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

The description is long, but it is front-loaded with purpose, metrics, filters, and usage before moving into edge cases. Most sentences carry operational value, though the length is near the upper bound for a tool description and could be tightened in places 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?

Given the tool's complexity, the description is complete: it covers metric semantics, location-resolution outcomes, oracle caveats, sub-area behavior, and commercial-versus-residential separation. An output schema and annotations also exist, but the description still supplies the interpretation rules an agent needs to use the tool 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?

Although schema coverage is already 80%, the description adds substantial meaning: it explains how search_type affects price units, how location_id takes precedence after ambiguous matches, and how property_types separates homes from commercial figures. The schema alone would not make those behavioral consequences clear.

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

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

The description opens with a precise verb and resource: return aggregate market context for a Spanish area, listing the exact metrics provided. It also clarifies that this is a market-context tool rather than a listing search or individual valuation, which differentiates it from siblings such as search_properties and verified_valuation.

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

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

It gives a clear usage context: use this before recommending a price or commenting on whether a listing is good value. However, it does not explicitly state when to prefer a sibling tool, such as verified_valuation for a specific property valuation, or when not to use 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 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 cover readOnly/idempotent/openWorld safety, and the description adds genuine behavior beyond them: max 10 results, ordering 'biggest first', the rule that a group covering a region precedes a same-named city, the exact-name matching rule for country/region queries, and municipality-based disambiguation of duplicate names. These ranking and matching semantics are not derivable from annotations or schema.

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

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

Front-loaded with purpose and return shape, then usage, then routing guidance — good ordering. Some sentences (the two disambiguation examples) overlap in intent and could be trimmed slightly, but each 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?

Output schema exists so return-field enumeration is optional, and annotations cover the safety profile; the description still supplies the ordering rules, matching behavior, and downstream integration with search_properties that an agent needs to call and use the tool correctly. 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; the description adds that the count and ranking depend on the market, which implicitly explains the meaning of search_type, and clarifies query as a place name rather than a free-form search string. It does not elaborate on the provinces parameter, so it falls short of full semantic 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?

States a specific verb and resource — looking up property areas (city, suburb, urbanisation, region/coast groups) by free-text name — and defines the scope, including the different area types returned. An agent can immediately distinguish this resolver from search_properties in the sibling list.

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

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

Explicitly says when to use it: resolve place names before calling search_properties, pass the chosen id as location_id, and calls out common spelling cases ('Nueva Andalucia' vs 'Nueva Andalucía'). The alternative tool and the hand-off contract are both named.

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?

Beyond the annotations, it discloses important behavior: the result is only a draft, it never appears on the portal, the response includes a direct link, and a linked PropertyList account or agency API key is required. It also explains that location is resolved against the real area tree and that commercial facts are validated as the CRM validates them.

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

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

The description is front-loaded with the core action and usage condition, then moves to draft behavior and commercial-specific rules. Despite its length, each paragraph addresses useful context for a 25-parameter tool and contains no obvious 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?

Given the tool's complexity and the presence of an output schema, the description is complete enough to guide invocation. It covers the create-draft scope, account requirement, location resolution, publication behavior, and commercial-property validation rules.

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 already 92%, so the schema does most parameter-level work. The description still adds meaningful guidance by explaining that commercial premises take a commercial property_type, no bedrooms, and their own facts such as usable area, activity licence, tenure, rent, and lease terms.

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: starts a new property listing draft in the agency CRM from a description. It clearly distinguishes this from publishing tools by saying the listing is created as a draft and is never published or shown on the portal from here.

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

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

It gives a clear usage condition: use when the agent has taken on a property and wants it in the system. It also clarifies the downstream workflow, where the agent adds photos and the energy rating and publishes separately. It does not name explicit alternatives or when-not-to-use cases, 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 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 cover the safety profile (read-only, idempotent, non-destructive), so the description's job is to add operational detail — and it does: result ordering, the per-listing return fields, the location_not_found error contract, and the exclusion of price-on-application listings. It doesn't mention corpus freshness or pagination, but the essential behaviors are disclosed.

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 defining sentence, then example queries, then filter/error/exclusion notes. Slightly dense and the line breaks are odd, but every sentence carries 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 needn't be explained — and yet the description still names the key fields, which helps. The filter model is delegated to a sibling and the error contract is stated, leaving only minor gaps around defaults and result caps.

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

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

The schema covers 67% of parameters, and the description adds the useful rule that filters behave like search_properties and that an unknown location returns an error. However, it says nothing about days, limit, language, or min_percent beyond the schema, and those undocumented parameters remain undocumented in both places.

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 resource and a specific cut of the data: live listings with a reduced asking price, sorted biggest reduction first. This is clearly distinguishable from search_properties, which it explicitly references only for filter semantics.

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 two concrete use cases ('what has dropped in price in Estepona this month?' and spotting motivated sellers) and points to search_properties for the general filter model. It doesn't explicitly say when not to use this tool (e.g. for unsold inventory without a cut), but the intent is clear enough.

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

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

Annotations cover safety (readOnly, non-destructive, idempotent) but the description adds the traits that matter operationally: a daily free allowance without an API key, that empty results don't consume it, the specific error when exhausted, a cap of 9 listings, and that commercial premises are never mixed with homes. That is real behavioral disclosure 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-loaded with the purpose and the qualifying brief type before mechanism and quota details. It runs long, and the commercial-premises sentence and the parenthetical quota note are slightly tangential, but nearly every sentence carries information an agent needs.

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-format explanation is not required, and the description still covers scope, ranking, quota, and failure behavior. The one real hole is the undescribed language parameter, which leaves the agent guessing about a non-default input.

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%: 'brief' is documented in the schema, but the 'language' enum parameter has no description anywhere. The description never mentions language handling, so it fails to compensate for the gap, and its notes on features-as-filters describe matching behavior rather than parameter syntax.

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 (match Spanish properties from a free-form description) plus the mechanism (translate into 1-3 parallel structured searches over the full MLS, merge and rank). It also implicitly differentiates from search_properties by naming that sibling as the structured alternative, so an agent can pick 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?

Explicitly says when to use it (vague, conditional, lifestyle-heavy briefs, with a concrete example) and names the alternative for the other case: search_properties for structured queries. The fallback when the allowance is exhausted is stated, so the agent knows exactly what to do when this tool errors.

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 read-only/idempotent safety, and the description adds genuinely new behavior: the ~25% price tolerance, the matching dimensions, the 'closest in price first' ordering, and the presence of oracle_verified/oracle_attestation_url on results. It does not discuss result-count behavior or what happens when few matches exist, which is the main remaining gap.

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 core similarity rule and ranking are front-loaded in one dense sentence, followed by usage examples and a short note on result fields. No filler, though the trailing oracle paragraph is a slight afterthought that could be tighter.

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 shape need not be explained, yet the description still flags the oracle fields. The matching heuristic is exactly what an agent needs to interpret why certain listings appear, and only the limit default/cap is left implicit.

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%: reference and language are documented in the schema, but limit is undocumented in both places. The description's matching criteria describe filtering behavior, not the parameters, so it adds no meaning about limit or language. Baseline 3 for mid coverage 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 ('listings similar to one property') and enumerates the similarity axes — market, town, property type, bedrooms, price band. An agent can distinguish this from search_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?

Provides two concrete trigger phrases ('show me alternatives to PL12345', 'anything like this but cheaper?') that map directly to intent. It stops short of explicitly naming search_properties as the alternative or stating when not to use this tool, 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 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 establish that this is a read-only, idempotent, non-destructive, open-world tool. The description adds meaningful behavioral context beyond annotations: how to handle last_reviewed, what to do when truncated is true, and the legal-information disclaimer.

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 four compact sentences with no wasted text, and the core purpose is front-loaded before the handling instructions. Each sentence carries operational value for correct invocation or interpretation.

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 rich schema coverage, existing output schema, and annotations, the description is complete enough for an agent to call and use the tool correctly. It covers pagination continuation, review-date handling, and the legal disclaimer without redundantly restating schema details.

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 url, offset, and max_chars. The description reinforces the offset continuation semantics but does not mention max_chars, so it adds only modest value beyond the structured schema.

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

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

The description states a specific verb and resource: "Read one PropertyList guide." The word "one" clearly distinguishes this tool from the sibling search_guides tool, so an agent can identify its role 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?

The description gives clear usage context and explicitly tells the agent how to continue when a page is truncated via offset and next_offset. It does not explicitly name search_guides as the alternative for discovering guides, but the schema's url description supplies that routing context.

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, openWorld), and the description adds real value: a ranking rule, a nullable `url` edge case for agencies with no page, and a language-dependent link. The only blemish is 'Returns up to 10 agencies', which sits awkwardly against a `limit` parameter that allows up to 25.

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 ranking rule, and every sentence carries information. Slightly long for a three-parameter read tool, and the described 10-result cap duplicates and muddies the `limit` parameter.

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 enumerated, yet the description still summarizes the main fields and the null case. For a read-only, single-required-parameter lookup this is essentially complete; only the `limit` semantics remain unaddressed.

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% – `location` and `language` are documented, `limit` is not. The description clarifies that `language` controls the language of the linked agency page and that `url` may be null, but it never explains `limit` or reconciles it with the stated cap of 10, so it neither compensates for the gap nor misleads badly.

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 agencies in an area), the ranking basis (active listing count), and the payload returned (name, location, listing count, url). An agent can distinguish this from area_market_summary 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 situational trigger: use it after a buyer has narrowed in on an area and wants to know which agencies dominate it. It does not name a competing sibling (e.g. area_market_summary) or state when not to use it, so it stops 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 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?

Goes well beyond the readOnly/idempotent annotations: it discloses the result ordering (own listings first, then shared MLS, newest first), a per-listing ownership flag, the no-search behavior (explanation, not a guess), and the auth prerequisite (linked PropertyList account or agency API key). Only missing detail is what happens with the limit cap and whether partial results are common.

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?

Well front-loaded with scope and ordering in the first sentence, then prerequisites and fallbacks in descending priority. Slightly verbose in places ('the same search the CRM runs for that client' repeats the prior clause), but every paragraph 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?

With an output schema present, the description correctly omits return-value structure while still covering ordering, ownership flagging, and auth requirements. The only real gap is the limit parameter's effect on result completeness.

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 description only adds sourcing guidance for contact_id ('from find_contacts'). The limit parameter (default 5, max 20) is not explained in either the schema or the description, so truncation behavior is left implicit.

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 ('listings that fit one client's search') and pins the scope to the caller's agency CRM with an explicit ordering rule. It is clearly distinguishable from match_inventory_to_buyers (reverse direction) and search_properties (used when no saved search exists).

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 saved-search input, the fallback to the latest debrief, and the exact failure mode when neither exists, with the named alternative (search_properties) to use instead. Also routes the agent to find_contacts for contact_id and get_contact to check sending history.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail about Spanish-language queries requiring accents, though it does not discuss ranking, result volume, or error behavior.

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 compact and front-loaded: it establishes the guide corpus, lists relevant question types, names the follow-up tool, and ends with the accent rule. Every sentence contributes useful selection or invocation guidance.

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

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

An output schema exists, annotations cover safety and openness, and the description supplies the topic scope, intended question types, next-step tool, and language-query nuance. Nothing essential for selecting or calling this tool 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 67%, and the schema already explains query keyword guidance and the language enum. The description adds meaningful query semantics by noting that Spanish words need accents, with examples like tributación and tasación, compensating for the remaining 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?

The description states a specific verb and resource: searching PropertyList's Spain property guides. It also names concrete covered topics (ITP, IBI, NIE, buying process, laws, area guides), making it easy to distinguish from generic property search siblings.

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

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

It explicitly says to use this for how-to, cost, and legal questions, then call get_guide for the page. That gives both the appropriate use case and the follow-up alternative, leaving little 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?

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?

Beyond annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false) it reveals what technically happens downstream (enquiry lands in the agency's CRM, agency follows up), the rate-limit model for anonymous vs account vs API-key callers, and that the action cannot be recalled. This is substantive context an agent could not derive from annotations alone.

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

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

Purpose is front-loaded and the paragraphs each cover a distinct concern (what, when, limits, params, consent). It is slightly longer than needed, with the phone-number guidance repeated from the schema, which keeps it from a 5.

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

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

With an output schema present, return values need no explanation, and the description fills the remaining gaps: consent, irreversibility, rate limits, API-key behavior, and which parameter values to supply. Nothing an agent needs to call this destructive tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, and the description largely restates the phone/email guidance. It adds only marginal value, such as noting the `reference` comes from search results and the message can mention a viewing, which is why it sits at the baseline rather than above it.

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 first sentence states a specific verb (submit), a specific resource (enquiry/lead), and the exact object it concerns ('about a specific listing on behalf of a prospective buyer or tenant'). This lets an agent distinguish it from siblings like create_contact or schedule_viewing 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?

It explicitly states the trigger condition ('once the user has chosen a property and wants the agency to contact them') and rules out alternatives by noting that direct phone or email details are not exposed by other tools. The consent/irreversibility note functions as an additional when-to-use guard.

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: what `verified` actually gates, why transaction_backed is false outside Spain, that only two segment attestations exist per municipality, that commercial requests return reason=commercial. It does not state rate limits or latency, so it stops short of a 5, but the disclosure of failure modes and data provenance is unusually rich.

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 decision rule ('Check `verified` before citing') before the country and rollup details, and each paragraph covers one concern. It runs long, and the sub-area enumeration (Sotogrande, Puerto Banus, Nueva Andalucia, Orihuela Costa) is illustrative padding that 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-key explanation was optional — yet the description still explains the fields that determine correct downstream wording (verified, transaction_backed, source_label, rollup_note, requested_area, indicative_band_pct). For a multi-country, zero-required-param estimation tool, nothing an agent needs to call it or cite it responsibly 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 baseline is 3, and the description still adds real meaning: build_sqm triggers an indicative price, reference reuses the listing's municipality/type/size (and location is ignored), and property_type resolves to the nearest attested segment with a requested_property_type echo. Minor tension: the schema lists 'plot' as a valid slug while the text says only homes are priced, which leaves plot handling slightly ambiguous.

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

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

Specific verb ('Estimate the market price') plus resource (property or area) plus explicit scope (Spain, Portugal, Cyprus) and source qualifier ('recorded market data, not asking prices'). The closing pointer to area_market_summary for asking-price stats distinguishes it from the most confusable sibling without either schema being opened.

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

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

Explicitly routes the agent: use area_market_summary when no attestation exists, check `verified` before citing, never describe index-based PT/CY figures as notary-verified, never quote a rolled-up figure as the sub-area's own price. When-not conditions and alternatives are both named.

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