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?

The description discloses critical behavioral constraints beyond the annotations: the need for explicit consent, sharing details with a third-party advisor, and requiring international phone format. It emphasizes 'never assume consent' and 'Only call with consent=true after they say yes.' This adds significant context that annotations (readOnlyHint=false, openWorldHint=true) do not cover.

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 well-structured and every sentence earns its place. It starts with the core purpose, then provides usage guidance, prerequisites, and consent handling. The use of caps for key directives ('OFFER THIS ONLY', 'MUST ask', 'Never assume') improves scannability without being verbose.

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 with 10 parameters and no output schema, the description covers the essential invocation context: when to call, what to collect, and the consent gate. It does not describe the return value or post-call behavior, but these are not always required. The missing piece is a brief note on what happens after the request is registered (e.g., 'the advisor will contact them'), which 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?

The input schema has 100% parameter description coverage, so each parameter is already documented. The tool description reinforces the consent and phone format requirements but does not add new semantic meaning beyond what the schema provides. Baseline 3 is appropriate since the schema carries the heavy lifting.

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 purpose: 'Register a buyer's request to be contacted by a local Portuguese property advisor.' It uses a specific verb ('register') and identifies the resource (advisor contact request). This distinguishes it from siblings like get_property_contact, which likely returns contact info, and search_properties, which is for searching.

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 explicit when-to-use ('when the user signals intent to move forward') and when-not-to-use ('Do NOT offer it while they are still just browsing or comparing') guidance. It also lists prerequisites (ask for name, email, phone, consent). However, it does not explicitly name alternative tools for comparison, so it stops short of a full 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.