Huisly

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, so the bar is lower. The description adds genuinely useful behavior beyond them: it discloses the payload shape (summary, outline, short excerpt, FAQs, cited sources) and crucially that only an excerpt is returned, with a link out to the full article on huisly.nl. It omits error behavior for a bad slug.

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: verb and resource first, then the returned fields, then the outbound link. Dense but every clause carries information; the enumerated return list is slightly heavy for one sentence but does not waste words.

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 must describe the return value, and it does so adequately (summary, outline, excerpt, FAQs, sources, link). The main gap is the undocumented 'kind' parameter, which matters for a tool whose sole required input is a slug that could belong to either content type.

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 only 33% (only 'language' is documented in-schema). The description adds real meaning for the required 'slug' by tying it to search_guides, but says nothing about the 'kind' enum (blog vs moving_guide) or how it interacts with slug — an agent must guess whether kind is a disambiguator or a filter.

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 ('Get one Huisly guide by slug') and immediately names the sibling that produces the slug ('from search_guides'), so an agent can distinguish it from search_guides without opening either schema. The clause listing what is returned nails down scope.

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 parenthetical '(from search_guides)' encodes the intended workflow: search first, then fetch by slug. However, it never says when-not to use this tool, nor what happens if a slug is unknown or stale, so it falls short of explicit alternatives/exclusions.

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?

Goes well beyond the readOnly/idempotent annotations: caps the window at 168 hours, discloses that an empty result is reported explicitly rather than silently, that each call returns a refreshed search_token, and that tokens expire after 30 days of disuse. Those are exactly the operational facts an agent needs for a scheduled polling loop.

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, front-loaded with the return contract, then usage context, then token lifecycle. No filler and nothing repeated for its own sake.

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 and only three parameters, the description carries the return-value burden and does so adequately: it says what the results are, what happens when there are none, and that a token comes back. It stops short of describing the listing payload or result-size/pagination behavior, which is the main remaining gap.

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%, so window_hours bounds, default, enum values and the token's provenance are already documented in the schema. The description largely restates the 168-hour cap and the token source; the genuinely new facts (token refresh, 30-day expiry) are behavioral rather than parameter-level.

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 precise verb, resource and filter: return only listings *first seen* within window_hours for a given search_token. The word "only" plus the token-scoped scope cleanly separates it from search_listings, which is named as the source of the token.

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?

"Built for scheduled checks that the user sets up, for example daily or every few hours" gives clear usage context and implies this is a follow-up tool rather than an initial search. It routes implicitly to search_listings for token creation, but never states an explicit when-not-to-use condition (e.g. don't call this first, don't poll more often than X).

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, closed-world and non-destructive, so safety is covered. The description adds genuine behavioral context beyond that: results are unopinionated (no scoring or ranking), each figure carries its period and comparison baseline, and source attribution is included. It says nothing about caching, rate limits, or what happens when a place name is ambiguous.

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 resource and output shape, then input routing, then the neutrality caveat — a sensible order with little padding. The parenthetical category list plus 'and more' is slightly loose but earns its place by signalling breadth.

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?

No output schema exists, so the description carries the return-value burden and does it well: headline figures, per-category figures, periods, comparison areas, and attribution. Remaining gaps are minor — no note on error behavior for unknown places or on how many figures to expect per category.

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?

With only 60% schema description coverage, the description compensates meaningfully by explaining the two input modes (a bare place name versus a type + slug pair sourced from resolve_place), which the schema alone leaves implicit for the undocumented slug/type properties. It does not explain the interaction or precedence when both place and slug/type are supplied.

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 (neutral CBS figures for a Dutch municipality, district or neighbourhood), names the exact figure families returned, and clarifies it does not score or rank areas. An agent can distinguish it from get_property or search_listings without opening any 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 concrete input routing: 'Pass a place name, or type and slug from resolve_place', which explicitly ties it to the resolve_place sibling. It does not state exclusions (e.g. when a property-level tool would be better), so it stops short of full when-not 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 already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds useful scope detail by naming external sources (source websites and the RVO/EP-Online registry) and the Dutch market limitation. It does not disclose behavior when neither identifier is supplied (both parameters are optional) or what happens for an unknown slug, leaving the failure modes unexplained.

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, front-loaded with the payload inventory and then the identifier routing. The enumeration of return fields is dense but each item earns its place by telling the agent what it can rely on. Minor cost: the long first sentence is heavily packed and could be split for scanability.

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?

No output schema exists, so the description must carry the return contract and it does, listing the fact categories and source links. Combined with the annotation coverage and the identifier routing, an agent has enough to call this correctly and interpret the result. The only residual gap, error behavior, is secondary for a read-only lookup.

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 33%, with just the language enum documented. The description compensates well for the two undocumented identifiers by explaining where property_slug comes from and what listing_id is for. The language parameter is left to the schema, which is acceptable since the schema covers it.

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 ('Get the facts of one Dutch home') and then enumerates what those facts are: address, size, building, current listings with source links, history summary, and EP-Online energy label. This is clearly distinguishable from siblings like get_place_insights or search_listings, which operate on areas and result sets rather than a single property.

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 concrete routing guidance: pass property_slug from search_listings or resolve_place, or listing_id for a listing without a property page. The upstream tools that produce the identifier are named explicitly. It stops short of saying when to prefer this over get_place_insights or what to do if an agent has neither identifier.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered by structured data. The description contributes the return contract (a slug) and its consumers, but says nothing about no-match behavior, partial matches, or whether multiple candidates can come back for an ambiguous name such as a street that exists in several towns.

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, both earning their place: the first defines scope and output, the second defines downstream consumption. The most important information, what the tool returns, is front-loaded rather than buried.

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 carries the return-value burden and discharges it by naming the slug as the output. What remains missing is resolution behavior for ambiguous or failed lookups, which matters for a resolver that can match many entity types across a whole country.

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 both parameters are documented in-schema, including examples for query and the enum/default for language. The description adds no formatting rules, postcode syntax, or address-ordering conventions beyond what the schema already states, so this lands at the baseline.

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 ('Look up') and enumerates the resource types it resolves (municipality, town, district, neighbourhood, postcode, street, address), then states the concrete payload: a Huisly slug. That is enough for an agent to distinguish it from siblings like search_listings or get_place_insights 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?

It explicitly routes the agent forward: the returned slug feeds search_listings (location), get_place_insights (type and slug), or get_property (property_slug) for addresses. It stops short of stating when NOT to call it (e.g. when a slug is already known) or what to do when the query is ambiguous, but the downstream mapping is genuinely actionable.

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 and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the return shape ('summaries with links') and the topical breadth, though it says nothing about result limits or empty-result behavior (limit is capped at 5 in 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?

Two sentences, front-loaded with purpose and domain, second sentence covering return shape and the sibling handoff. No filler or 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?

With no output schema, the description usefully states that results are summaries with links, and the get_guide handoff defines the depth boundary. Minor gaps: the undocumented limit parameter and no note on how many results to expect by default, but nothing that would cause a mis-call.

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 67%: query and language are already documented in the schema, while limit (default 5, max 5) is undocumented anywhere. The topic examples in the description implicitly clarify what a good query looks like, but the description adds nothing about limit or the effect of language beyond what the schema states. 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?

States a specific verb (search) and a clearly scoped resource: Huisly's own editorial guides, not listings or place data. The parenthetical topic list (rental contracts, deposits, transfer tax, mortgages, city moving guides) makes the content domain unmistakable and separates it from search_listings.

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 routes the agent to the sibling get_guide when it needs the outline, FAQs and official sources of a single guide, which is exactly the right next-step guidance. It stops short of stating when to prefer search_listings or get_place_insights over this tool, so the exclusion set is only partially drawn.

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 and closed-world, so the safety profile is covered. The description adds real behavioral value beyond them: at most 10 results, facts only, newest-first ordering unless sorted by price, plus total match count, a huisly.nl link and a reusable search_token. It does not mention any auth or rate-limit behavior, which keeps it short of a 5.

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, front-loaded with the search scope, then return behavior, then the follow-up workflow. Every clause carries information and nothing is padded.

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 13-parameter tool with a nested location object and no output schema, the description does the important work: it describes what comes back and how the search_token chains to get_new_listings. The residual gaps are the place/location input relationship, which the schema partly covers via 'A place from resolve_place'.

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 62%, and the description only summarizes filters as 'price, size, room and property-type' — a restatement of what the schema already names. It adds ordering semantics for sort ('newest first unless sorted by price') but says nothing about min_rooms versus min_bedrooms, the language parameter, or the place-versus-location choice, leaving the competing location inputs unclear.

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 verb+resource ('Search current Dutch rental or for-sale listings') is specific, and the description names the domain scope and the two listing types the required enum accepts. An agent can distinguish this from get_property or get_new_listings without opening 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?

It explicitly routes the agent forward: pass search_token to get_new_listings to see only new matches, with the scheduled-task use case called out. It gives no guidance on when to use this versus get_property or get_place_insights, and no mention that the location object must come from resolve_place, so it is clear but incomplete on alternatives.

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