minhamorada.pt

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

With no annotations provided, the description carries the full disclosure burden and succeeds by specifying that it 'Returns times for all transport modes' (output structure) and crucially disclosing the estimation methodology ('Based on straight-line distance with typical speeds'). This warns users about accuracy limitations, though it could further clarify traffic handling or failure modes.

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, zero waste. The first establishes purpose, the second covers output behavior, and the third discloses estimation methodology. Information is front-loaded and 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?

Despite lacking an output schema, the description adequately covers what the tool returns (transport modes) and the calculation caveat. Given the 100% schema coverage and the conditional parameter logic (property_id vs. coordinates), the description provides sufficient context, though explicitly stating the mutual exclusivity of start-point parameters would strengthen 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 100%, establishing a baseline of 3. The description adds value by mapping the high-level concepts ('two points' vs. 'property') to the parameter groups (coordinates vs. property_id), helping users understand the mutual exclusivity of the starting point inputs, though it does not elaborate on formats or validation rules 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 calculates 'estimated commute time' using specific verbs and identifies the two main usage patterns (point-to-point vs. property-to-location). It implicitly distinguishes from siblings like get_property and search_properties by focusing on temporal/distance calculations rather than property metadata or search.

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 outlines the two input alternatives ('between two points or between a property') which guides parameter selection, but lacks explicit when-not-to-use guidance or comparisons to sibling tools that might also involve location data.

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?

No annotations provided, so description carries full burden. Discloses return payload contents ('description, all photos, energy certificate...') which is valuable behavioral context. However, lacks operational details: does not explain that optional lat/lng trigger commute calculations, omits error handling (e.g., invalid ID), caching, or rate limits.

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 tightly constructed sentences with zero redundancy: (1) core action, (2) return payload specifics, (3) usage workflow. Front-loaded structure puts the essential verb ('Get') and resource ('property') immediately.

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?

Strong coverage given constraints: no output schema exists, so description appropriately lists return fields. Acknowledges sibling relationship (search_properties → get_property). Minor gap: does not mention commute calculation behavior implied by optional coordinates.

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%, establishing baseline 3. Description references 'by ID' reinforcing property_id purpose, but adds no semantic value for near_lat/near_lng beyond what schema already documents ('Latitude to calculate commute times from'). No penalties required since schema is comprehensive.

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?

Excellent specificity: 'Get full details for a specific property by ID' provides exact verb, resource, scope, and identifier. Naturally distinguishes from search_properties (search vs. retrieve) and calculate_commute (different function entirely).

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?

Explicit workflow guidance: 'Use after search_properties to show detailed info' establishes clear sequencing with sibling tool. Lacks explicit negative guidance (e.g., 'do not use for searching') but provides strong positive context for when to invoke.

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?

No annotations provided, so description carries full burden. It discloses return structure ('total property count, average prices by district...') which compensates for missing output schema, but omits operational details like data freshness, rate limits, or authentication requirements.

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 earning its place: action+scope, return values, and example usage. Front-loaded with the core verb, no redundancy, appropriate length for tool 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?

Given 2 optional parameters with full schema documentation, the description adequately covers the tool's function and return values. Minor gap: does not explicitly note that both parameters are optional (allParams optional), which would help the agent know it can call this with no arguments for nationwide stats.

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 clear descriptions ('Filter stats to a specific district', 'Filter to sale or rent only'), establishing baseline 3. The description adds an example question suggesting usage but doesn't add parameter syntax, formatting rules, or constraints 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?

Clear verb-resource combination ('Get aggregate market statistics') with specific geographic scope ('Portuguese real estate market'). Implicitly distinguishes from siblings: calculate_commute (travel times), get_property (specific listing), and search_properties (individual properties) by focusing on 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?

Provides a concrete example use case ('What's the average rent in Porto?') which hints at when to use it, but lacks explicit guidance contrasting it with siblings or stating when NOT to use it (e.g., for individual property details).

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?

No annotations provided, so description carries full burden. Discloses return values ('prices, locations, and links') but omits pagination behavior, result limits, or safety classification (though 'search' implies read-only).

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 well-structured sentences: purpose statement, return value disclosure, and usage guidance. No redundancy, front-loaded with core action.

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 19 parameters and no output schema, description compensates by describing return format. Could improve by noting all parameters are optional (required: 0) or result pagination behavior, but adequately covers the complex search domain.

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%, but description adds valuable semantic bridging by mapping user concepts ('Portuguese districts', 'budgets', 'near specific locations') to parameter groups, helping agents understand which parameters to populate for user requests.

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?

Clear specific verb 'Search' with resource 'properties (apartments, houses)' and scope 'Portugal'. Implicitly distinguishes from sibling get_property (single fetch) by emphasizing search/filter functionality for finding real estate.

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 usage context ('Use this to help users find real estate...') mapping to specific parameter categories (districts, budgets, locations), but lacks explicit when-not-to-use guidance or comparison to siblings like get_property or market_stats.

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