Avecindar rental search

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

Beyond readOnlyHint/openWorldHint, it reveals availability.confirmed semantics ('confirmed within the last seven days'), states that imported listings are unverified third-party content, and clarifies that unknown costs are null rather than zero. These caveats materially change how an agent should interpret 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 sentences with no filler; the primary action is in the first sentence, followed by high-value caveats about availability, provenance, and null semantics. Every 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?

Given no output schema, the description still tells the agent what data categories to expect and how to interpret ambiguous values. Availability freshness, source provenance, and null cost semantics are the likely failure points and are all addressed. No critical behavioral information appears 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?

The schema only defines id as a string with maxLength 100, and the description reinforces that the id must identify a publicly displayed rental home. Since it is a single self-explanatory parameter, the lack of additional parameter prose does not hurt usability.

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 'Read one publicly displayed rental home by its id' – a specific verb, a clear resource, and a unique retrieval mode. It also enumerates the returned content (costs, conditions, areas, photos, provenance), which distinguishes it from sibling list/search 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?

It clearly communicates that the tool is for fetching a single known rental home by id, implying it is not for discovery or browsing. It does not explicitly name search_homes or exclude alternatives, but the by-id target is unambiguous 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 read-only, non-destructive, and idempotent behavior. The description adds meaningful selection context by specifying that only reviewed neighbourhoods are returned, and it exposes the relationship to search_homes.neighbourhoods. This is useful beyond the structured 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?

Two short sentences with no filler: the first states the action and scope, the second gives an immediate cross-tool usage hint. The most important information 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 one-parameter list tool, the description is nearly complete: it states what is listed, the scoping market, and how the output relates to search_homes. It does not explicitly describe the response shape, but the presence of ids/names is implied by the search_homes reference.

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

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

Schema description coverage is 0%, so the description should compensate. "Inside one market" clarifies that the market parameter selects the containing market, but it does not describe the enum values or expected format. The single-parameter schema and self-explanatory enum limit the gap, making this minimally adequate.

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 and object: "List reviewed neighbourhoods (barrios/localidades) inside one market." It clearly scopes the tool to neighbourhood-level data for a single market, which differentiates it from sibling tools like get_home, list_markets, and search_homes.

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: call this to get reviewed neighbourhoods for a market and use the resulting ids/names in search_homes.neighbourhoods. It does not explicitly state when not to use it or compare it to an alternative, but the integration hint is concrete and useful.

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 context by noting that only 'active' departments are returned and by listing output fields, but it does not reveal additional behavioral details such as data freshness or any pagination 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?

A single sentence carries the verb, resource, scope, and output attributes with no filler or redundancy. The key information is front-loaded and every word contributes 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 parameterless list operation, the description is nearly complete: it names the domain and enumerates the returned fields. Since there is no output schema, the explicit field list compensates for that absence, though it could add slightly more context about how 'active' is determined.

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 and the schema description coverage is 100%, so there are no input semantics to document. The baseline for zero-parameter tools is 4, and nothing in the description is needed to clarify 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 uses a specific verb ('List') and names a concrete resource ('the active departments Avecindar covers') with its returned attributes. It is clear, though it does not explicitly distinguish itself from the sibling list_areas, so it falls short of full sibling differentiation.

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?

No guidance is given about when to use this tool versus get_home, list_areas, or search_homes. The intended use case is only implied by the name and title, and no exclusions or alternative conditions are stated.

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 this as a safe, idempotent read, and the description goes well beyond them by disclosing pagination (12 summaries plus opaque nextCursor), freshness semantics for availability.confirmed, the third-party nature of imported listing content, and null-not-zero cost encoding. These are valuable behavioral traits an agent cannot infer from the 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?

Four sentences, each carrying a distinct fact: scope, pagination, availability reliability, content provenance, and cost encoding. The most functionally important scoping sentence leads; there is 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?

The description covers caveats that would otherwise be invisible (availability confirmation window, third-party content, null costs) and enough of the return shape to select the tool, but with 17 parameters and no output schema an agent still lacks details on result fields and default filter behavior. It is adequate but not fully complete for a tool this complex.

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 47%, and the free-text description provides little parameter-level guidance: it clarifies that unknown costs are null rather than zero, which touches cost filters, and mentions the opaque nextCursor that the schema already documents. With 17 parameters and roughly half undocumented, the description does not compensate for the coverage gap.

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

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

The description names a specific verb ('Search') and resource ('Avecindar's public catalogue of rental homes') with explicit geographic scope. It clearly reads as the list/search entry point, distinct from the sibling get_home (single listing) and list_areas/list_markets (reference data).

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 implies when to use it: any time you need to discover rental homes matching criteria. However, it never names alternatives like get_home for full-detail retrieval or list_areas for neighbourhood codes, so the routing logic 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.