Heart Homes — Dubai property data

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile, so the bar is lower. The description adds genuinely useful context beyond that: a 12-month weighted calculation window and the three computed metrics. It does not explain edge cases like sparse rental data or how the gross rental yield is derived, making it adequate but not 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?

A single 28-word sentence that front-loads the action ('Compare buying vs renting'), immediately lists the metrics, and closes with the optional filter. Every clause earns its place with zero filler or repetition of the 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 no output schema present, the description carries the burden of describing return values, and it does so by enumerating the three metrics an agent will receive. For a read-only, two-parameter tool this is nearly complete; the only gaps are minor presentation details such as currency, units, and yield formatting.

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%: slug is documented as the location slug returned by search_locations, and propertyClass carries a full enum. The description's 'one community or area' echoes slug's semantics and 'Optionally filter to one property class' reaffirms the schema's optionality, adding modest confirmation but no new meaning beyond what the schema already provides.

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, 'Compare buying vs renting in one community or area,' and enumerates the exact metrics computed: 12-month weighted median sale price, median annual rent, and implied gross rental yield. Among the siblings (get_market_overview, get_price_history, rank_communities, etc.), this is the only tool producing a buy-vs-rent comparison with rental yield, so it is clearly distinguishable.

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 context: it is scoped to one community or area and optionally filterable to one property class, so an agent knows this is the tool for a localized buy-vs-rent analysis. It stops short of a 5 because it never names alternatives or states when-not-to-use conditions, such as when a broader market overview or price-history trend is the better fit.

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 readOnlyHint and openWorldHint annotations, the description adds useful conditional behavior: rent statistics are included only when rent contracts can be attributed to the building, and the per-bedroom breakdown appears only when enough contracts resolve a bedroom. This helps the agent set expectations about partial or conditional outputs.

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 single sentence that front-loads the core purpose and lists the returned metrics efficiently. The conditional rent clauses add necessary nuance without excessive 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?

There is no output schema, so the description serves as the return contract. It enumerates the main data categories and explains conditions under which rent fields are present, which is sufficient for an agent to invoke the tool and interpret results. Minor details like exact date ranges of 'recent' are not specified but do not block correct usage.

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 provides only type and length constraints, so the description carries the full burden. It explains that both communitySlug and buildingSlug are required to identify a building and that they come as a pair from search_locations, which is meaningful guidance beyond the bare schema.

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

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

The description names a specific resource (a single building) and enumerates the concrete statistics returned: 12-month sales, median price, trend, recent sales, property-type mix, and rent data. It clearly separates this from broader location or market tools by scoping to one building.

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 by stating that it takes the communitySlug and buildingSlug pair returned by search_locations, establishing both a precondition and an input source. It does not explicitly name alternative tools or when not to use it, but the single-building scope makes the intended context obvious.

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 provide readOnlyHint and openWorldHint. The description adds meaningful behavioral detail: partial rent-bedroom coverage, the requirement to report it as approximate using rentBedroomCoveragePct and rentBedroomNote, and the building-level unavailability. 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?

Three sentences: the first front-loads the core return content, the second explains conditional behavior, and the third adds a caveat. No filler or repetition of schema details.

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

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

There is no output schema, so the description carries the return-shape burden; it lists the headline metrics, the property-class mix, and the conditional breakdowns. It also includes reporting instructions and a limitation. Nothing essential for invoking the tool 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 value beyond the schema by clarifying that propertyClass breakdowns apply to communities and by flagging the per-building rent limitation, which helps an agent choose valid parameter values.

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 identifies a specific resource ('one community or area slug') and enumerates the headline stats returned, making the tool's purpose unmistakable. It is clear enough to be distinguished from building-specific siblings, but it never explicitly names an alternative tool such as get_building_stats.

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 conveys that the tool is for community/area slugs and warns that per-bedroom rent is not available for a single building, which implies limits. However, it does not explicitly state when to prefer get_location_stats over siblings like get_building_stats or get_market_overview, so routing 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 declare readOnlyHint=true, so the safety profile is known. The description adds useful behavioral context: a 12-month rolling window, aggregate KPIs, and data freshness, which tells the agent what kind of data to expect without 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 two compact sentences with no filler. The first sentence front-loads the metric scope and the second gives actionable usage guidance, so every part 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?

With no parameters and no output schema, the description adequately covers what the tool returns and when to call it. It specifies the KPIs, the time window, geographical scope, and data-freshness inclusion, which is enough for an agent to decide and invoke 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?

The tool has zero parameters, so there are no parameter semantics to clarify. The schema fully covers the parameter surface, and the description's mention of city-wide scope and time window is sufficient contextual orientation.

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 names a specific verb and resource ('City-wide Dubai sales KPIs') and enumerates the exact metrics returned. This clearly distinguishes it from location-, building-, and trend-specific sibling tools.

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?

'Good first call for broad questions' gives clear guidance on when to use the tool. It does not explicitly mention alternatives, but the city-wide scope implies that more specific questions should use sibling tools like get_building_stats or get_location_stats.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond annotations — the clarification that rent medians are annual contract values in AED/year prevents unit misinterpretation. However, it doesn't disclose response format, data recency, or month coverage, and with no output schema the return shape is left unspecified.

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

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

Two tight sentences with zero waste. The core data product and scope are front-loaded, and the second sentence earns its place with the critical unit clarification for rent medians. Every word 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?

For a read-only query tool with no output schema, the description covers the essentials: what data is returned, how to scope it, the sale/rent distinction, the optional property-class filter, and units. The main gap is the absence of response-format detail, but the declared outputs (transaction counts and median prices) largely imply the shape, and annotations cover the safety profile.

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 75% — kind, slug, and propertyClass are already described, and months carries numeric constraints (default 24, min 3, max 60). The description adds marginal value: the AED/year unit tied to rent kind and the 'one property class' limitation, but it largely restates the schema. The months parameter has no semantic description anywhere.

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 data product — monthly transaction counts and median prices — with scope (community/area slug or city-wide), transaction kind (sales/rents), and an optional property-class filter. This is clear and specific enough to convey what the tool does, but it stops short of explicitly distinguishing itself from overlapping siblings like get_market_overview or get_trends_movers.

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 clear scope conditions: use for a community/area slug or city-wide, for sales or rents, optionally filtered to one property class. The when-to-use context is evident, but there are no explicit exclusions or alternative routing ('use X instead when...'), so an agent must infer when a sibling tool is the better fit.

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; the description adds the 12-month window, the metrics returned, and a semantic warning not to present off-plan figures as resale/flipping. It does not detail response shape or empty-data behavior, but the key behavioral risk is addressed.

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

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

The purpose is front-loaded in the first sentence, and each subsequent sentence adds definitions or usage guidance. It is slightly repetitive around 'ready/resale/secondary-market' but remains dense and relevant.

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 tool with no output schema, the description covers scope, time window, metrics, terminology, and an optional filter. It stops short of stating the output structure explicitly beyond 'ready row', but enough is present 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 both slug and propertyClass are already documented. The description repeats the optional property-class filter and the one-community/area scope but adds no syntax or format details 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?

The description names a specific verb and resource: a sales split between secondary/ready and off-plan markets, scoped to one community or area over 12 months, with concrete metrics. It also defines 'ready' and 'off-plan' distinctly, which separates this from siblings like get_market_overview or list_recent_transactions.

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

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

It gives explicit category guidance: flipping/reselling/resale questions should use the ready row rather than off-plan figures. However, it does not name sibling tools or state when to use another tool instead, so it stops short of full alternative routing.

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 safe-read profile (readOnlyHint=true), so the description need not restate that. It adds genuine behavioral context: the 12-month window, the riser/faller semantics, and especially the 30+ sales filter with its rationale ('thin-volume noise is excluded'), which explains why certain communities may be absent. It doesn't disclose result ordering or return structure, but those are minor for a read-only list.

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

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

Two sentences of about 30 words total. The core resource-and-metric statement is front-loaded, the direction semantics follow immediately, and the volume filter closes with a justification. No filler or repetition of schema content.

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

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

For a simple 2-parameter read tool with readOnlyHint and no nested objects, the description covers the essentials: what is returned, the metric, the direction choices, and the data-quality filter. Gaps are minor: no explicit result ordering (e.g., sorted by magnitude) and no return-shape details, which matter more because there is no output schema. Sibling differentiation could also be stronger.

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

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

With 0% schema description coverage, the description must compensate. It does explain the required parameter direction ('up' = risers, 'down' = fallers), which carries real semantics the enum values alone lack. However, the limit parameter is never mentioned; it is only structurally constrained in the schema (min 1, max 10, default 5). Partial compensation only.

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 (communities) and metric (biggest 12-month price moves), with direction semantics spelled out ('up' = risers, 'down' = fallers). The 30+ sales threshold adds precision. It doesn't explicitly differentiate from the sibling rank_communities, which could overlap, so it stops short of a 5.

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 implied: call this when you want communities ranked by 12-month price movement, and the direction field tells the agent which list to request. However, with 11 siblings including rank_communities and get_price_history, there is no explicit when-to-use or when-not-to guidance, leaving the choice 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 indicate readOnlyHint=true, so the description's additional disclosure that these are 'registered' and 'real records' adds useful context about data provenance and ordering beyond the structured annotation. It clarifies that results are factual recent contracts, not estimates or forecasts.

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?

A single, tightly written sentence front-loads the core purpose and immediately conveys the data source and intended use. There is no redundant phrasing or filler.

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

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

For a simple read-only list tool with three parameters and no output schema, the description gives enough context about purpose, data source, and usage intent. It does not describe the return shape, but the absence of an output schema makes that a minor gap given the straightforward nature of the 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?

The schema already documents 'kind' and 'slug' well, and the description reinforces that 'sale' means DLD sales and 'rent' means Ejari contracts. However, the 'limit' parameter lacks a description in both schema and tool description, so the coverage gap is not fully compensated.

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 a specific action and resource: listing the most recent DLD sales or Ejari rent contracts for a location slug. It conveys the factual, record-based nature of the data, which helps separate it from analytic siblings like get_market_overview or get_price_history, though it does not explicitly name a differentiating sibling.

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 implied rather than explicit: the phrase 'real records to ground price talk in' suggests when this tool is useful (when concrete recent transactions are needed). However, it does not state when to prefer it over alternatives such as get_price_history or get_market_overview, nor does it give exclusion criteria.

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 readOnlyHint annotation, the description discloses important behavioral caveats: the 12-month median window, partial rent coverage due to Ejari records lacking building names, and exclusion of buildings with fewer than 5 records. This materially helps the agent set expectations.

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 with no filler. The core purpose is front-loaded, and each caveat sentence earns its place by explaining data limitations and filtering rules.

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 scope, metrics, ordering, and data caveats, which is enough for correct tool selection and invocation. It does not describe the exact return shape, but with no output schema the title and core sentence sufficiently imply a ranked list of buildings.

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 25%, but the description adds meaning for 'metric' (sale price vs annual rent) and 'order' (cheapest/most expensive). 'communitySlug' is already explained in the schema, while 'limit' remains schema-only, so the compensation is strong but not complete.

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 ('rank') and resource ('buildings in one community'), and clarifies the exact question it answers: 'cheapest/most expensive buildings in X'. This clearly differentiates it from sibling tools like rank_communities or get_building_stats.

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 a clear usage context by mapping the tool to a specific user question. It does not explicitly name alternative tools or state 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, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the 30+ transaction minimum, the default exclusion of whole-building leases and land deals, and the 12-month median window. These are exactly the kind of filtering behaviors an agent needs to know to interpret results correctly.

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

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

Two sentences, both dense with useful information. The first sentence front-loads the core purpose and user intents; the second adds the critical filtering caveats. No wasted words, no repetition of schema details.

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 ranking tool with no output schema, the description covers the key decision factors: what metric is used, what the default scope is, and the minimum transaction threshold. It doesn't describe the return format or whether results include the median values, but the absence of an output schema and the read-only annotation make this a minor gap rather than a critical one.

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%, with metric and propertyClass having descriptions. The description adds meaning by explaining the default propertyClass behavior (residential only) and clarifying that metric values map to 'sale prices' or 'annual rents'. It doesn't detail the limit or order parameters, but those are self-explanatory from their names and enums, so the description compensates well for the coverage gap.

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

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

The description states a specific verb ('rank'), a resource ('communities'), and the two ranking metrics (12-month median sale price or median annual rent). It also explicitly ties the tool to user intents like 'cheapest areas' and 'most expensive communities', which makes its purpose unmistakable and distinguishes it from siblings like rank_buildings.

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 context on when to use this tool: when the user wants the direct answer to cheapest/most expensive/most affordable areas. It also explains the default behavior (residential classes only without propertyClass filter) and the 30+ transaction threshold, which helps an agent decide whether this tool is appropriate versus alternatives like get_market_overview or rank_buildings.

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 and openWorldHint=false, covering the safety profile. The description adds valuable behavioral context: it returns canonical slugs and is the mandatory first step before sibling tools, which is meaningful beyond the structured fields.

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

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

Two dense sentences with no filler. The core action and output are front-loaded, and the critical usage rule is delivered in the second sentence. Every word 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?

For a simple, read-only resolver, the description covers purpose, outputs, and usage sequencing. While there is no output schema and the description does not address ambiguity or empty-result behavior, the canonical-slug statement and strong usage rule make this adequately complete for an agent.

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

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

Schema description coverage is 100%, with both 'query' and 'kind' already documented. The description adds the 'free-text' notion and clarifies that output feeds other tools, but it mostly restates the enum values from the schema rather than adding deep new parameter 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?

The description uses a specific verb ('Resolve') and resource ('free-text Dubai location name ... to canonical slugs'), clearly distinguishing this lookup tool from the analytics siblings. It also states the exact role of the tool in the workflow, so an agent can identify it instantly.

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 instructs 'Always call this first when the user names a place' and explains that other tools depend on the returned slugs. This gives a strong, unambiguous usage rule and implies when not to use it (for analytics directly).

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