MyPorta

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is fully covered structurally. The description adds real context on what the comparison surfaces (price, rooms, schools with Ofsted grades, stations, amenities, agent), which helps an agent predict the payoff of calling it. It omits anything about the freshness/limitations of the underlying listing data.

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 front-loaded sentence: trigger condition first, then the comparison dimensions, then the input in a short closing clause. No filler, no 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?

An output schema exists, so the description is not obliged to enumerate return values, yet it still orients the agent on comparison dimensions. Trigger, scope, source of ids and read-only nature are all covered; nothing needed to invoke it correctly 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 description coverage is 100% and the schema itself declares minItems=2/maxItems=4, so the parameter is already fully documented. The description's "Takes the homes' ids" and "two to four homes" only restate that constraint without adding syntax, ordering or error-handling meaning. 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?

Specific verb (compare) plus resource (homes) with explicit scope: two to four homes, side by side, on named dimensions. It is immediately distinguishable from search_homes (find listings) and get_home (single home detail).

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?

"Use this when the user wants to compare..." gives a clear triggering condition and ties the source to search_homes results, which is genuine routing guidance. It does not, however, state when not to use it (e.g. single-home lookups should use get_home) or what to do if the user hasn't searched yet.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety bar is low. The description usefully adds that the response is a summary with a link to the full overview, clarifying the scope of what is returned without explaining pagination or empty-result 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?

Two sentences, no filler: the first front-loads the usage trigger, the second states the return. Every clause 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 single-parameter, read-only tool with full annotations and an output schema, the description covers what is needed to call it. The only minor gap is how it behaves when no overview exists for a place or when the name is ambiguous.

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% and documents 'place' as 'Town, village or neighbourhood name.' The description adds a real constraint the schema lacks: the geographic scope is UK-only, and the accepted place types are implied by the trigger sentence, so it contributes meaning 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 states a specific resource (MyPorta's Area Overview for a UK town/village/neighbourhood) and what it returns (a summary plus a link to the full overview). The area-vs-home resource distinction separates it cleanly from siblings compare_homes, get_home and search_homes, though it never names them.

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 an explicit, concrete trigger: 'Use this when the user asks what a UK town, village or neighbourhood is like to live in.' That is a clear use condition, but it offers no exclusions or pointers to alternative tools (e.g. what to call for individual home 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorld=false, so the safety profile is fully covered by structured data. The description adds the useful link that the id must come from search_homes, but says nothing about latency, rate limits, or error behavior for a missing id; with an output schema present, further behavioral detail is largely unnecessary.

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?

One sentence, front-loaded with the triggering condition followed by the returned-field list. It is dense but every clause maps to a real capability; the long enumeration is the only slight strain on readability.

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 a rich annotation set and an output schema, the description is complete enough for correct invocation — it identifies the trigger, the required input, and the source of that input. The field enumeration partially duplicates what the output schema presumably documents, but nothing an agent needs 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% for the single home_id parameter and the schema already says 'The id from search_homes.' The description repeats that constraint ('Takes the home's id') without adding format or validity details, so it lands at the baseline for a well-documented single-parameter 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?

States a specific verb and resource and enumerates the exact fields returned (advert, rooms, tenure, EPC, schools, etc.), which is far more informative than the title. It also anchors the tool relative to search_homes results, so an agent can distinguish it from siblings without opening a schema.

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?

Gives explicit usage context: 'Use this when the user asks about one home from search_homes results,' which cleanly separates it from the bulk search case. It does not name when-not to use it or explicitly route to compare_homes/get_area_guide, so it falls one step short of full guidance.

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 cover the safety profile (readOnly, idempotent, non-destructive); the description adds real behavioral substance: homes are ranked by fit with a 0-100 match score plus evidence (station/school distances, advertised features), capped at 10 results, and must_haves are matched word-for-word against adverts. This is exactly the kind of ranking/matching semantics 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?

Front-loaded with the use condition, then dense guidance on how to fill the fuzzy parameters, and finally the return shape. It is long but every clause carries information; the embedded parenthetical examples make some sentences heavy, which keeps it short of a 5.

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 an output schema present, describing the return payload (price, bedrooms, agent, link, nearby schools/Ofsted, station, park, GP, supermarket, broadband) is optional but helpful. The one required param (place) and the ranking params are covered; remaining minor params are left to the schema.

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 64%, and the description compensates where it matters most by explaining the tricky distinction between `wishes` (lifestyle/area, own words) and `must_haves` (physical features an advert states verbatim), with examples for both. It adds nothing for sort, bed bounds or property_type, but those are enum/range-constrained 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?

States a specific verb and resource with explicit geographic scope: find homes for sale or to rent in the UK. The scope (search, ranked results, nearby evidence) is distinct from get_home and compare_homes without the agent needing to open the schema.

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?

"Use this when the user wants to find homes for sale or to rent" gives a clear triggering condition, and it instructs how to translate user input into place/budget/bedrooms/type. It does not explicitly name when to prefer get_home or compare_homes instead, so it falls short of a full routing rule.

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