Socials Homes

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

Annotations already declare read-only, idempotent, non-destructive and closed-world, so the safety profile is covered; the description still adds genuinely new behavior: the ~10-minute cache refresh and the explicit failure semantics ('says plainly when live counts are unavailable instead of reporting zero'). That staleness and error-handling context is exactly the kind of detail annotations cannot express.

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 core action and scope, then the conditional parameter behavior, then the cache/fallback note. Every sentence carries information an agent needs; nothing is padding.

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, return values need no explanation, and the description still covers the two things an agent cannot infer: the freshness window of the count and the explicit 'unavailable rather than zero' semantics. Nothing needed to call 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 coverage is 100% (both params fully described with ranges and slug/name formats), so the baseline is 3. The description adds interpretation the schema does not: the budget is an inclusive threshold ('at or under it') applied to the live count, and city must be 'supported'. Modest but real added value.

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 and resource ('count the live rental listings ... in a supported city') plus the conditional budget behavior, which no sibling (get_plans, list_cities, start_home_search) covers. An agent can distinguish this counting tool from the search and listing tools 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?

Usage is implied by the conditional budget clause ('if a monthly budget in EUR is given'), and 'supported city' hints at a prerequisite, but there is no explicit when-to-use statement and no routing to alternatives such as start_home_search when the user wants individual listings rather than a count.

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, non-destructive, and closed-world, so the safety profile is covered. The description still adds real value by disclosing the breadth of returned content (billing behavior, renewal, cancellation mechanics, guarantee conditions and a terms link), which tells the agent how much it can answer without follow-up calls.

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 core purpose ('Get the ... plans with prices in EUR') followed by a comma-delimited scope list. Every clause corresponds to a distinct piece of returned information, though the single run-on sentence is dense and could be broken up for easier scanning.

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 return values need not be explained in prose — yet the description redundantly enumerates them, which is harmless but slightly wasteful. Nothing an agent needs in order to invoke a zero-parameter, read-only lookup is missing; only sibling positioning is absent.

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 tool takes zero parameters, so per the rubric the baseline is 4. The description correctly spends no space on parameter syntax and instead describes the response content, which is the only thing an agent could need guidance on here.

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 ('Get') and resource ('the Socials Homes plans') and goes further by enumerating the exact scope: prices in EUR, billing, auto-renewal, inclusions, cancellation, and the VIP Keys Pass guarantee. It is unmistakably a pricing/plan catalog lookup, though it never contrasts itself with the sibling tools (which are unrelated city/search tools, so this matters little).

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?

There is no explicit when-to-use statement, no prerequisites, and no named alternatives. Usage is only implied by the content list — an agent infers it should call this when a user asks about plan pricing or cancellation terms. Adequate but leaves routing to inference.

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 read-only, idempotent, non-destructive, closed-world semantics, so the safety profile is covered. The description adds real value beyond that: it identifies this as a reference/lookup tool and explains the chaining contract (slug feeds other tools), which is behavioral context an agent needs.

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 tight sentences: the first front-loads what is listed and what is returned, the second covers the filter and downstream usage. No filler or repetition.

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 return values need no further explanation, and the description still covers scope, filtering, and tool chaining. For a single optional-parameter list tool, nothing an agent needs to call 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 already documents the ISO code vs English name duality with examples. The description repeats the country-filter semantics ('NL' or 'Netherlands') without adding syntax or edge-case detail beyond the schema, so 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?

States a specific verb (list) and resource (cities where rental listing alerts are sent), plus the exact fields returned (slug, name, country). This is clearly distinguishable from siblings like get_plans or start_home_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?

Explains the optional country filter and, more usefully, tells the agent to use the returned slug with check_city_supply and start_home_search, establishing downstream workflow context. It does not explicitly state when-not to use this tool or contrast it with get_plans, 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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real value by spelling out the absence of side effects ('does not create an account, save anything or send any message') and by describing the human-in-the-loop follow-up, which 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 action and its result are front-loaded in the first clause, with the non-side-effect disclaimer following. It is compact with no filler, though the single long opening sentence packs three ideas together rather than separating them.

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 return values need not be described, and the description sensibly fills the gap an agent would otherwise have about the signup-link flow. Nothing critical is missing, though the relationship to sibling lookup tools is left unstated.

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% — city, move_in and budget_max_eur are all documented with valid slug/name formats and constraints in the schema itself. The description adds no parameter-level detail (e.g. how budget_max_eur or move_in affect the returned link), so the 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 gives a specific verb and resource: 'Check that a city is supported and return the Socials Homes signup link for it.' It also corrects the potentially misleading name by clarifying that no account/search is actually created, which is strong disambiguation, though it never names the sibling tools (check_city_supply, list_cities) it could be confused with.

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?

Usage is implied rather than stated: it explains what the tool returns and what happens next, so an agent can infer this is the entry point after picking a city from list_cities. However, it never says when to use this versus check_city_supply or get_plans, and gives no exclusion conditions.

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