PropertyList: Spanish Property MLS

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

The description goes far beyond the annotations by disclosing concrete failure behavior (location_not_found, no nationwide fallback), unit semantics per search type, sales-only metric constraints, oracle.verified requirements, notarial source conditions, and sub-area rollup logic. No statements contradict annotation readOnly/idempotent/destructive hints.

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

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

The description is longer than most, but every block earns its space because it covers caveats that would otherwise be unseen (error behaviours, oracle trust conditions, municipality rollup). It is front-loaded with purpose and usage, then stacks internal logic. It could be tightened slightly, but the density justifies most of the length.

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

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

For a tool that includes an output schema and has this many edge cases, the description gives almost everything the agent needs: output purpose, parameter effects, error shapes, data provenance, source verification, price-unit rules, and sub-area resolution. The presence of an output schema plus this level of behavioural detail makes the definition contextually complete.

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 documents location and available property_type slugs. The description adds meaningful semantics where the schema is thin: search_type controls price units (total, per month, per week), prices are labelled, and median_price_per_sqm applies only to sales. Location behavior on unknown names is also clarified, though semantics for property_type could go a bit deeper.

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

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

The description opens with a specific verb and resource ('Return aggregate market context') and lists highly concrete outputs (active listings, median/mean price, median €/m², bedroom bands). It also names the filter dimensions, making the tool distinct from sibling listing/property tools like search_properties and get_property.

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 when to use this tool: 'before recommending a price or commenting on whether a listing is good value.' It does not identify conflicting sibling tools by name, so an agent might still need to infer why not to use verified_valuation or search_properties, but the contextual trigger is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying the maximum number of matches (10), the fields returned (id, name, parent province/city), and the purpose of resolving place names. It doesn't mention edge cases like no matches or error handling, but the added context is valuable and doesn't contradict annotations.

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

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

The description is concise and well-structured. It front-loads the core function, then provides output details, and finally gives usage guidance with examples. Every sentence earns its place, and there is no redundant information. The length is appropriate for the tool's complexity.

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

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

The description is complete for a read-only lookup tool. It covers the purpose, output, and usage context. The output schema is absent, but the description explicitly states what the tool returns (up to 10 matches with id, name, parent province/city), which compensates. It doesn't mention pagination or error cases, but for a simple autocomplete tool, this is sufficient. The annotations cover safety, so the description doesn't need to repeat that.

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 both parameters ('query' and 'provinces'). The description adds context about the 'query' parameter by giving examples of free-text place names, but it doesn't add significant meaning beyond the schema. The 'provinces' parameter is not elaborated in the description, but the schema's description is sufficient. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: looking up Spanish property areas by free-text name, with a specific verb ('Look up'), a resource ('Spanish property areas'), and a defined output (up to 10 matches with id, name, parent province/city). It distinguishes itself from siblings by explicitly mentioning its role in resolving place names before calling search_properties, which is a clear differentiator.

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

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

The description explicitly states when to use this tool: 'Use this to resolve place names before calling search_properties'. It also provides concrete examples of common spelling variations ('Nueva Andalucia' vs 'Nueva Andalucía') and 'Marbella old town', which helps an agent understand the intended use case. It doesn't explicitly mention when not to use it, but the context and examples make the usage clear.

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

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

Annotations are all false and provide minimal signal, so the description carries the burden. It discloses deduplication by email (returns existing contact), creation as unassigned, flagging for attention, and the requirement of an agency API key. These go well beyond annotations, though it doesn't specify the return format for a new contact.

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

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

Three sentences, each carrying distinct value: purpose, dedup behavior, and side effects/requirements. No fluff, front-loaded with the core action. Efficiently 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?

The description covers most operational context: purpose, dedup, post-creation state, and auth requirement. The only notable gap is the lack of a clear statement about the return value for a fresh creation (it only mentions 'returned' in the case of duplicate). Given no output schema, a bit more explicit return description would make it fully complete.

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

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

Schema description coverage is 100%, so all parameters are already described in the schema. The description adds no parameter-specific meaning beyond what the schema provides (e.g., email is for dedup is already in the schema). Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Add') and resource ('contact to YOUR agency's CRM'), and clarifies the types of persons (buyer, owner, enquirer). It is clearly distinguished from sibling tools like find_contacts (search) and create_listing (different resource).

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

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

Explicitly states when to use the tool: 'Use when the agent wants to save a person'. It does not explicitly list alternatives or conditions to avoid, but the guidance is clear and the dedup behavior is called out. Missing explicit 'when not to use' prevents 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?

The description adds far more than the annotations: it creates a DRAFT that is never published, shows that the user, not this tool, is responsible for publishing, includes a direct link in the response, resolves the location against a real area tree, and mentions the agency API key requirement. These are exactly the behaviours an agent needs to set expectations and act accordingly.

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: the very first sentence states the core action and target system, followed by the relevant when-to-use context, the DRAFT caveat, and the key technical side (link, area-tree resolution, API key). Every sentence earns its place with no fluff.

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

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

For a create tool with 11 parameters and no output schema, the description covers almost all procedural essentials: the draft state, the link, the auth, and the area-tree tolerance. It leaves out edge cases like validation failures or further required fields, but with 82% schema description coverage and a clear intent statement, the agent has enough to decide when and how to invoke it.

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 82%, so the description doesn't need to re-list parameters. It goes beyond the baseline by clarifying that location is matched loosely against the real area tree, thus allowing town names. It also implies that the same free-form description drives the creation, hinting that many optional fields may get filled from 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?

States a specific verb ('start'), a specific resource ('a new property listing'), and a source/frame ('in YOUR agency's CRM from a description'). This clearly distinguishes it from sibling tools like create_contact or search_properties, and the 'draft' notice further pins down what it is that is created.

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 'Use when the agent is describing a property they have taken on and wants it in the system' supplies a clear trigger context. The 'never published / on the portal' statement provides a strong boundary. It does not name a specific alternative tool, but the usage context is explicit 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 already declare readOnly, idempotent, non-destructive. The description adds valuable context: it requires an agency API key and only searches the calling agency's contacts, which explains scope and authorization. This goes beyond the annotations without contradiction.

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

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

Three concise sentences. The primary purpose is front-loaded, followed by usage guidance and constraints. No unnecessary words or repetition.

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

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

For a simple search tool, the description adequately covers the core invocation: query string, auth, and scope. However, it does not explain the 'limit' parameter (though schema gives default/max) nor describe the return format or potential result behavior, which an agent might want to know. Given no output schema, these are minor gaps but still leave the description slightly incomplete.

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%: only 'query' has a description, and the tool description repeats that query accepts name, company, email, or phone. The 'limit' parameter is completely omitted from both schema and description, so the description fails to compensate for the missing documentation on a parameter with constraints and a default.

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

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

The description clearly states the action ('Search'), the resource ('YOUR agency's CRM contacts'), and the searchable fields (name, company, email, phone). It is distinct from sibling tools like find_properties_by_description by focusing on contacts, but does not explicitly name that alternative.

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

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

Provides specific use cases: 'before logging a note' and 'to check if they're already in the CRM', which gives context on when to call. It also notes the prerequisite of an agency API key. However, it does not explicitly state when not to use it or mention alternative tools like create_contact or search_properties.

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

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

Annotations already mark it read-only/idempotent/non-destructive, and the description adds real behavior beyond that: it breaks the brief into 'one to three parallel structured searches', merges and ranks results, returns 'up to 9 listings with match scores', and discloses interpretation limitations ('what couldn't be resolved'). This is substantial, non-obvious 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?

Three sentences with no filler: the purpose, the ideal input profile, and the processing/output contract. The example is illustrative but compact, and all sentences add information.

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

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

Given the output schema and annotations, the description covers input, interpretation mechanics, and return shape. It is slightly incomplete because it never conditions this tool against search_properties for structured queries, and the language parameter is left unexplained.

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 enriches the 'brief' parameter by characterizing acceptable input as vague, conditional, or lifestyle-heavy, but it does not discuss the 'language' parameter at all. Schema coverage is exactly 50%: brief has a description, language only has an enum/default, so the description only partially compensates for that gap.

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

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

The description opens with a specific verb and resource: 'Match Spanish properties from a free-form description of what the user wants.' The example and mention of 'PropertyList's full MLS' ground what it acts on. It is clearly distinguishable from the sibling search_properties because it targets vague, lifestyle-heavy briefs rather than structured queries.

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

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

It states when to use it: 'Best for vague, conditional, or lifestyle-heavy briefs' and gives a concrete example. It does not explicitly name an alternative for structured queries or state when not to use it, but the positive guidance 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 provide readOnly/idempotent hint, but the description adds meaningful behavioral detail: works without an API key up to a daily per-IP allowance and is raised with a key. It also explains tricky response semantics: `city` is the filing tier, `municipality` is never guessed, and coordinates are absent rather than 0,0 when unavailable. No annotation contradiction.

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

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

All sentences add value: purpose, sibling alternative, API-key behavior, then two dense field-semantics caveats. Front-loaded; no filler.

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

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

Despite no output schema, the description flags the non-obvious fields an agent would otherwise misread (municipality null semantics, latitude/longitude absent, precision tiers) and the authentication/rate-limit context. Enough to call 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?

reference is described in schema; description reinforces with example. The language parameter receives no description beyond enum names + default. With 50% schema coverage, the description does not fill the gap, but language as an enum of locale codes is low-risk. Score 3.

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 object: 'Fetch the full record for one PropertyList listing by its reference code.' It precisely identifies the input ('human-readable id like 'PLE-12345''), distinguishes this from search tools by saying it is used after the user has settled on a listing, and names sibling `submit_enquiry` as the alternative for contact details. Clear and unambiguous.

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

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

Explicitly says when to use: once the user has settled on a listing from search_properties or find_properties_by_description and wants details/photos. It also routes the contact case to submit_enquiryable and notes the API-key/rate-limit context, giving the agent enough to choose between siblings.

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, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context: ranking by active listings, returning up to 10 agencies, and including a public URL. It doesn't mention pagination or sorting details beyond ranking, but the added context is meaningful and non-contradictory.

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 concise and well-structured: it states the purpose, the ranking logic, the return fields, and the usage context in three sentences. Every sentence earns its place, and the most important information (what it does) is front-loaded.

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

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

For a read-only list tool with two parameters and no output schema, the description is largely complete. It covers what the tool returns (name, location, listing count, URL), the ranking criterion, and the usage context. The only minor gap is the lack of explicit mention of the 'limit' parameter's behavior, but the description's 'up to 10' partially covers it. Given the tool's simplicity, this is adequate.

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%: 'location' is described in the schema, but 'limit' is not. The description mentions 'up to 10 agencies' which implies the limit parameter's effect, but doesn't explicitly explain the limit parameter or its default/maximum. The description adds some meaning beyond the schema (ranking, return fields) but doesn't fully compensate for the undocumented 'limit' parameter.

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

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

The description clearly states the tool's function: finding PropertyList agencies in a Spanish area, ranked by active listing count. It specifies the resource (agencies), the action (list/find), and the context (Spanish area), which distinguishes it from sibling tools like search_properties or find_contacts.

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

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

The description provides clear usage context: 'Use this after a buyer has narrowed in on an area and wants to know which agencies dominate it.' This implies when to use it, though it doesn't explicitly mention alternatives or when not to use it. The context is strong enough for an agent to select it appropriately.

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 marking this as non-read-only, the description adds meaningful behavioral detail: the note appears on the contact/listing timeline and an agency API key is required. This goes beyond the schema and annotations without contradicting them.

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

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

Every sentence earns its place: purpose, required inputs, attachment behavior, and authentication requirement. The description is short, front-loaded, and immediately actionable.

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 key operational facts an agent needs: target type, input source, result of the action, and authentication. It does not describe return values or error cases, but for a simple logging action with a clear input schema, the description is sufficiently complete.

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?

Input schema coverage is essentially complete for all parametersley, so the baseline applies. The description adds modest value by clarifying that contact_id comes from find_contacts and that the target can be a contact and/or property, but it does not significantly extend the schema semantics.

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.' The examples (call outcome, viewing) and attachment targets make the tool's purpose immediately clear and distinguish it from sibling tools that create contacts/listings or submit enquiries.

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 on when to use the tool and what inputs it needs, including that contact_id should come from find_contacts and that either a contact_id or property_reference can be used. It does not explicitly exclude alternatives or state when not to use this tool, but the context is strong 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 already establish the safety profile (readOnlyHint, idempotentHint, destructiveHint), and the description adds valuable non-obvious behavior: it requires an agency API key, only ever returns the calling agency's own leads, lists enquiry sources, and explains the move from inbox to pipeline. This goes well beyond what annotations alone 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?

The main purpose is front-loaded in the first sentence, followed by clear usage guidance and a genuinely important empty-inbox clarification. Every sentence earns its place; the length is justified by the need to prevent false negatives and sibling confusion.

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?

The description covers auth scoping, ownership, ordering, sources, and the pipeline distinction, which is a strong level of context. However, with no output schema present, it does not describe the shape or fields of a returned lead, nor any pagination behavior beyond the limit parameter, leaving a small completeness gap.

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

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

The schema already documents 'since' and 'property_reference', and 'limit' has useful defaults and bounds. The description adds 'newest first' and 'what came in today' context, which helps interpret the ordering and recency, but it does not substantially explain parameter semantics beyond what the schema provides. With 67% schema coverage, the description neither fully compensates nor is redundant.

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

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

The description states a clear verb and resource: 'List recent enquiries (leads) for YOUR agency's CRM - newest first.' It also distinguishes itself from my_pipeline by defining the inbox versus pipeline lifecycle, so an agent can confidently tell these siblings apart.

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

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

It explicitly says when to use the tool: when the agent asks what has just come in, e.g. 'what came in today?'. It also gives an exclusion and alternative ('for those, use my_pipeline') and clarifies that an empty inbox is not equivalent to having no leads, preventing a common misinterpretation.

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?

Though annotations already mark it read-only and idempotent, the description adds key behavior: it requires an agency API key, returns only own properties, orders newest first, and clarifies status semantics (e.g., 'draft' includes new + in review). This goes beyond the annotations and gives necessary context for correct invocation.

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

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

The description is a compact two-sentence statement that integrates purpose, usage, auth, and scope without redundancy. The ordering constraint and filtering options are front-loaded, making it easy for an agent to parse quickly.

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 listing tool, all needed information is present: auth requirement, scope, ordering, and filter options. The default limit is in the schema, and no output schema is required for a list operation. Nothing critical 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?

Status and reference have explicit descriptions, and the enum values with explanations (especially 'draft' and 'all') are helpful. The limit parameter lacks a prose description, but its minimum, maximum, and default are self-explanatory from the schema. Overall, parameter meaning is clear despite 67% coverage.

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

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

The description clearly states the tool lists the calling agency's own property listings, newest first, with optional status/reference filters. This is distinct from siblings like search_properties (general search) and get_property (single property), and the scope is explicitly limited to own listings.

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

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

The description provides concrete usage examples ('show my listings', 'is reference X still online?') and notes the agency API key requirement, which implies it is for agency-specific queries. It does not explicitly name alternatives or say when not to use it, but the scope statement effectively excludes general searches.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds critical behavioral context beyond that: it returns the whole agency's boards (not one agent's), requires an agency API key, only ever exposes the calling agency's data, and stage names are custom so they must be read from the reply. This is exactly the kind of context that helps an agent avoid misinterpreting results.

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

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

The description is longer than strictly necessary, but every sentence earns its place – there is no filler. The core action is front-loaded, and the structure (scope → usage → alternatives → behavior) is logical. It loses a point only for not being as tight as the two-sentence ideal.

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 no output schema and three optional parameters, the description covers all necessary aspects: what is returned (board names, stage counts, cards), ordering, scoping to the calling agency, authentication, and alternatives. An agent has everything it needs to invoke this 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?

Even though schema coverage is 100%, the description enriches every parameter. It clarifies that limit only caps cards per stage while counts are full totals, that stage matching is case-insensitive and can target closed stages by name, and that omitting pipeline yields a summary. These are non-obvious behaviors that materially change how an agent should set parameters.

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

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

The description opens with a specific verb-resource pair ('List the cards on YOUR agency's CRM pipeline boards') and enumerates the exact boards, making the tool's function immediately unambiguous. It also explicitly differentiates itself from the sibling my_leads, so an agent can tell them apart without inspecting 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?

Usage is spelled out: call with no pipeline for a per-board summary, with a pipeline for a specific board's cards, and 'newest activity first' is noted. The description explicitly routes to my_leads for unworked enquiries, giving a clear when-to-use versus when-not-to-use.

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 and idempotency, and the description goes well beyond them by revealing exact failure behavior for unknown locations, the guarantee not to substitute listings, coordinate-omission rules, and the meaning of coordinates_precision. It adds rich context rather than contradicting 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?

The description is front-loaded with purpose, then use guidance, then behavioral expectations. Every sentence earns its place: error semantics and coordinate precision are dense but directly relevant, with no filler or restatement of structured fields.

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

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

For a complex read-only search tool, the description covers the key behaviors an agent needs: pagination, location-not-found behavior, oracle verification, municipality resolution nuance, and coordinate precision. Since an output schema exists, return-shape details do not need to be repeated here.

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 55% schema coverage, the description compensates by mapping filter categories to actual parameters and by explaining subtle location semantics such as city tier, municipality resolution, and coordinate presence. It does not restate every schema field, but it adds meaningful guidance beyond the bare schema, especially for location behavior.

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: 'Search PropertyList's full Spanish property MLS by structured filters.' It also distinguishes itself from find_properties_by_description by explicitly naming the sibling for free-form queries, so an agent can select correctly 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?

The description gives clear when-to-use guidance: structured filters such as bedrooms, bathrooms, price, type, and area; and an explicit when-not-to-use with the alternative: 'For free-form briefs use find_properties_by_description instead.' This is direct and actionable.

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 indicate a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds significant behavioral context: the enquiry goes to the agency's CRM, there is a per-IP daily allowance without an API key, and it sends personal details to a real estate agency, requiring consent. No contradiction with annotations.

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

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

The description is structured in clear paragraphs, front-loading the core purpose and then adding usage conditions and rate-limit context. It is somewhat verbose but each sentence contributes essential information; it could be tightened but is not wasteful.

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

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

For a submission tool with 6 parameters and no output schema, the description covers the essential aspects: purpose, when to use, side effects, consent, and rate limits. It does not describe the return value or error handling, but those are not critical for correct invocation.

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

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

Schema coverage is 100%, so all parameters have descriptions. The description adds minor context by specifying that the 'reference' comes from search results and that contact details are needed, but this largely reiterates the schema. It meets the baseline for full schema coverage but does not add substantial new meaning.

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

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

The description clearly states the action ('Submit an enquiry'), the resource ('a specific listing'), and the context ('on behalf of a prospective buyer or tenant'). It also distinguishes itself from siblings by noting this is the supported way to contact a listing agency, unlike other tools that don't expose direct contact details.

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

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

It provides explicit when-to-use guidance ('once the user has chosen a property and wants the agency to contact them') and a critical condition ('Only submit with the person's clear intent and consent'). It also implies an alternative path by stating that direct phone/email details are not exposed by other tools, making this the appropriate route.

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

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

The description adds rich behavioral context beyond the readOnly/idempotent annotations: the meaning of 'verified', the distinction between notarial and index-based sources, the rollup behavior for sub-areas, the segment fallback, and the field-level caveats. It clearly explains what users must check before citing the result. This is far more than the annotations alone provide.

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

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

The description is long but organized in clear thematic paragraphs and front-loads the core purpose. Every paragraph carries an actionable caveat, and the density is justified by the tool's complexity. It is not minimal, but it avoids redundancy and each sentence earns its place.

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

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

The description covers all essential aspects of the tool: data source, verification semantics, geographic aggregation, segment fallback, alternative tool, and error/fallback behavior. Given the rich output schema and read-only annotations, nothing an agent needs to call the tool correctly or interpret its results 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 a 3, but the description adds meaning beyond the schema by explaining how parameters affect the result: build_sqm produces an indicative valuation, reference values a listing, property_type resolves to the nearest attested segment, and sub-area locations roll up to the containing municipality. These behavioral details are not inferable from the schema alone.

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

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

The description opens with a specific verb and resource: 'Get a valuation for a property or area from recorded market data, not asking prices.' It clearly distinguishes itself from the sibling area_market_summary by noting that asking-price statistics belong to that tool. The tool's scope and output are stated 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?

The description explains when the tool is appropriate ('recorded market data, not asking prices') and gives an explicit alternative: 'use area_market_summary for asking-price stats instead.' It also warns against quoting rolled-up or unverified figures, giving concrete conditions for when the data can and cannot be used.

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