minha-morada

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 goes beyond by disclosing the estimation method: 'Based on straight-line distance with typical speeds,' which is crucial for setting accuracy expectations. This adds context that annotations cannot convey.

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

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

The description is exactly two sentences, front-loaded with the core purpose, and includes no filler. Every sentence earns its place: purpose, output scope, and estimation method.

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?

Without an output schema, the description conveys the return content ('times for all transport modes') but not the exact format or units. It also covers the key caveat (straight-line approximation) and origin alternatives. For a moderately complex tool, this is mostly complete, though explicit output structure would improve 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 description coverage is 100%, so each parameter is already described meaningfully. The description adds the relationship between from_lat/from_lng and property_id ('between a property and a location'), but the schema already notes property_id as an alternative to coordinates. Thus the description adds minimal extra value 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 clearly states the tool's function with a specific verb and resource: 'Calculate estimated commute time between two points or between a property and a location.' It also mentions the output scope (all transport modes), distinguishing it from sibling property tools like search_properties or market_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 gives clear context for when to use the tool (between two points or between property and location) but does not explicitly mention alternatives or exclusions. The uniqueness among siblings makes the usage context implicit, but no direct 'when-not-to-use' guidance is provided.

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, covering the safety profile. The description adds that the tool returns a 'url' field that must be cited and linked, and specifies its position in the workflow after search_properties, providing useful behavioral context beyond the annotations.

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

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

The description is three sentences: one for purpose, one for return contents, one for usage instruction. No filler words, each sentence serves a distinct function.

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, the description steps up by listing the key return fields (description, all photos, energy certificate, condition, floor) and the required url citation. It also covers the dependency on search_properties, making it adequately complete for a read-only tool with well-documented parameters.

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 parameters are fully documented in the schema. The description doesn't add new parameter semantics beyond what's in the schema; it only restates that property_id is the minhamorada.pt code, which is also in the schema.

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

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

The description opens with 'Get full details for a specific property by its minhamorada.pt code,' which is a specific verb and resource. It distinguishes itself from siblings like search_properties by specifying that it retrieves details for an already identified property, and lists return fields like photos and energy certificate.

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 'Use after search_properties,' giving clear usage ordering. This implies the tool is for obtaining detailed information after a property has been selected, differentiating it from broader search or contact-specific tools.

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 idempotentHint=true, so the safety profile is known. The description adds behavioral context by specifying that it returns an outbound listing URL, and that the link is for contacting the agency or opening the original listing. This goes beyond the 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?

Two sentences, zero filler. The first sentence states the action and resource; the second gives the conditional usage and return value. Every word contributes value.

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 tool is simple: one parameter, no output schema, and clear annotations. The description covers the purpose, input, when to use, and what is returned. This is complete for the tool's complexity.

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%, with the property_id parameter well-described in the schema. The description only restates that the input is a minhamorada.pt code, adding no additional meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly states the verb 'Get' and the resource 'outbound contact/listing link for a property', further specifying the input by minhamorada.pt code. It distinguishes itself from sibling tools like get_property by focusing on the contact/listing link specifically.

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 explicit when-to-use guidance: 'Call this ONLY when the user explicitly wants to contact the agency or open the original listing.' This implies when not to use it, though it doesn't name alternative tools. The return value is also mentioned, which helps the agent understand the outcome.

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 known. The description adds value by listing return contents (total property count, average prices, breakdown by typology, data sources) and the geographical scope. No contradictions.

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 sentences, front-loaded with the main purpose, and includes a concrete example. All words are informative with no redundancy.

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 purpose, example usage, and the enumerated return payload. While it doesn't detail the exact JSON structure, the lack of an output schema is partially compensated by the list of return items. Sibling context and annotations complete the picture.

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 district and price_type having descriptions. The description's example implies filtering but adds no new syntax or semantics beyond the schema, so 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 function as 'Get aggregate market statistics for the Portuguese real estate market' and enumerates specific outputs. This distinguishes it from sibling tools like search_properties and get_property, which focus on individual listings rather than aggregate 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 provides a concrete use case ('What's the average rent in Porto?') that indicates when to use this tool for market-level questions. However, it does not explicitly name alternatives or state when not to use, 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 and destructiveHint=false, so safety is covered. The description adds meaningful context: returns prices, locations, and a minhamorada.pt link, plus a mandatory citation/linking behavior. No contradictions 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?

Tight two-sentence structure: the first sentence states function and output, the second gives usage and citation rule. Every phrase earns its place with no waste.

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 19-parameter search tool, the description covers scope, return fields, and usage guidance. It omits pagination/sorting defaults, but those are specified in the schema, and openWorldHint in annotations helps set expectations. Reasonably 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 covers all 19 parameters with descriptions (100% coverage). The description mentions districts, budgets, and locations, aligning with district, price_min/max, and near_lat/lng, but adds no new syntax or examples 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?

Description opens with 'Search for properties (apartments, houses) for sale or rent in Portugal,' clearly identifying the verb, resource, and geographic scope. It distinguishes from siblings like get_property by focusing on multi-result search across Portugal.

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 'Use this to help users find real estate in specific Portuguese districts, with specific budgets, or near specific locations,' giving clear context. However, it does not mention when to prefer alternatives like get_property for single listing details.

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