Every Room

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 genuinely new behavior: it reveals exactly which attributes are returned (price, €/m², size, rooms, place, ad age), which matters because there is no output 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?

One sentence, no filler, and the cardinality constraint plus the returned fields are front-loaded so an agent grasps scope 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?

With no output schema, the description usefully compensates by listing the returned columns and the 2-6 id bound. It leaves minor gaps such as ordering of the comparison or behavior on invalid/duplicate ids, but is adequate for this simple read tool.

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 the single parameter is documented there ('Listing ids from search_listings'). The description's 'two to six' restates the schema's minItems/maxItems without adding format or error semantics, 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?

The description states a concrete action (putting listings side by side) and enumerates the compared attributes, which clearly separates it from the single-listing get_listing sibling. It does not name siblings explicitly, so it stops short of a 5.

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 'two to six listings' framing and by the fact that ids come from search_listings, but there is no explicit statement of when to prefer this over get_listing called repeatedly, nor any exclusion criteria.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the sign-in requirement and identifies the source collection for the id, but says nothing about whether the deletion can be undone or what happens on a missing/already-deleted id.

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 short sentences, zero filler, with the core action front-loaded and the precondition trailing. Nothing could be removed without losing information.

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 one-parameter destructive delete with rich annotations and no output schema, the description covers action, target collection, identifier source, and auth. Only the post-deletion / error behavior 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 coverage is 0% and the single id parameter has no schema description, so the description must carry it. It does add meaning by stating the id identifies an entry from my_saved_searches, telling the agent where to obtain the value, though it omits type/format expectations.

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 (delete) and resource (saved search) and scopes it to the caller's saved searches via my_saved_searches, which separates it from the my_saved_searches listing tool and save_search. It stops short of explicitly naming those siblings, but an agent can still tell it apart from the rest of the toolset.

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?

'Needs sign-in' supplies a precondition, and the delete semantics imply when it applies. However, it never says when to prefer this over alternatives (e.g. remove_saved_listing vs delete_saved_search) or that the operation is irreversible in user-facing terms.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior: the return content (slugs plus per-area home counts) and an example showing fuzzy matching behavior ("marina" -> dubai-marina), which matters since there is no output 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, zero waste. The core purpose is front-loaded and the example immediately follows, earning its place by demonstrating the fuzzy-match behavior.

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 burden of describing returns and does so (slugs + counts). It leaves open edge cases such as multiple or zero matches, but everything needed to call it correctly is present.

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 baseline is 3, but the worked example (country "ae", text "marina") concretely demonstrates the expected value formats and matching semantics beyond the schema's terse field descriptions. The deal parameter's effect on counts is left to 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 transformation (place name -> area slugs) and names the sibling it feeds (search_listings), plus the extra payload (home counts per area). An agent can distinguish this from search_listings, get_listing, and list_markets 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?

The phrase "the area slugs search_listings filters on" clearly positions this as the prerequisite step when you have a place name but not a slug. There are no explicit exclusions or named alternatives, but the workflow context is unambiguous.

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, so the bar is lower, and the description adds real value beyond them: it specifies the data scope ('everything public') and calls out a notable exclusion ('Seller contact is not included'), which is exactly the kind of gap an agent would otherwise guess at.

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 compact sentences, zero filler, and the return payload is front-loaded ahead of the caveat. Every clause carries information.

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 burden of describing return content, and it does so by enumerating fields and flagging what is absent (seller contact). For a single-id read tool this is complete enough to call correctly.

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?

One parameter at 100% schema coverage, and the schema already explains that the id comes from search_listings. The description adds no syntax, format, or validity information beyond the schema, 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?

States a specific verb+resource ('Get a listing') and then enumerates the returned payload (title, description, photos, price, size, rooms, place, similar homes), which lets an agent distinguish it from summary-style siblings like search_listings. It stops short of explicitly naming which sibling to use for which need, so it is clear but not sibling-differentiating.

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 only implied: the exclusion of seller contact hints that reveal_seller is the tool for that data, and the schema (not the description) points to search_listings as the id source. There is no explicit when-to-use statement or named alternative routing.

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=false, so the safety profile is covered. The description adds genuinely non-structured context—that the payload is a per-country breakdown of sale/rent counts, currency, and filter availability—which compensates for the absent output schema, though it says nothing about format, 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?

Two sentences, both earning their place: the first defines the returned content, the second sequences the call before dependent tools. The most action-relevant fact (what it returns and why call it first) is front-loaded with no filler.

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 parameterless, read-only discovery tool with no output schema, the description supplies exactly the missing pieces: the shape of the returned records and its role as the prerequisite step for market-code-dependent tools. Nothing needed to invoke it correctly 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 the baseline of 4 applies. The description correctly implies a no-argument call ('Call this first'), leaving nothing about inputs ambiguous.

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 ('list_markets' = the countries Every Room covers) and enumerates exactly what each entry contains: home counts for sale and rent, currency, and supported filters. No sibling tool overlaps this scope, so an agent can place it immediately.

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 instructs 'Call this first to get the two-letter market codes the other tools take,' which is a direct when-to-use rule and an implicit prerequisite for the rest of the sibling set. Given no alternative tool exists for this purpose, no exclusion clause is needed.

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=false, so the safety profile is covered. The description adds the auth requirement ('Needs sign-in') and scopes the reveal count to 'this week', both of which are behavioral facts the annotations do not carry.

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 tightly packed sentence plus a short prerequisite clause, with the resource front-loaded and no filler. Every listed item (plan, reveals, shortlists, saved searches) earns its place as a return-value preview.

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 burden of saying what comes back, and it does list the returned content plus the auth requirement. The only gap is that it does not clarify the overlap with my_saved_searches / my_saved_listings, which an agent choosing among these tools would want.

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 and the schema is fully self-describing, which is the baseline-4 case. The description adds nothing about parameters because there is nothing to add, and it correctly implies the account is inferred from the session rather than passed in.

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?

It names the specific resource (the signed-in person's account) and enumerates what that account view contains: plan, weekly seller-reveal balance, shortlists, saved searches. That is concrete rather than tautological, but it never distinguishes itself from siblings like my_saved_searches or my_saved_listings, which also surface saved-search/list 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 closing 'Needs sign-in' gives one prerequisite, which is useful. However, there is no statement of when to prefer this overview over the more specific sibling tools (my_saved_searches, my_saved_listings), so usage is only implied.

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 bar is lower. The description adds two useful pieces beyond that: result ordering ('newest first') and an auth prerequisite ('Needs sign-in'), which an agent must know before calling.

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 compact sentence plus a short auth note; scope and ordering are front-loaded and nothing is redundant.

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 simple read-only list tool, the definition covers scope, ordering, and auth, which is most of what an agent needs. It omits any hint about result size or pagination, though with no output schema that is a minor gap rather than a blocker.

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 single `list` parameter is already documented as 'Only this shortlist. Optional.' The description's 'only the one named' restates that rather than adding format or matching semantics, 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 resource (the listings in the person's shortlists) and its ordering (newest first), which distinguishes it from write-oriented siblings like save_listing or remove_saved_listing. It doesn't explicitly contrast with search_listings, but the 'shortlists' scope is clear enough to select correctly.

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?

'every list, or only the one named' implies when to supply the optional `list` parameter, so usage is inferable rather than explicit. There is no statement of when-not to use it or which sibling to prefer for other listing retrieval needs.

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 and idempotentHint, so the safety profile is covered; the description adds context annotations cannot: an authentication requirement ('Needs sign-in') and the ordering plus return shape of each entry. Slightly short of 5 only because it says nothing about pagination or what happens with an empty set.

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 short sentences, zero filler, with the resource and ordering front-loaded and the auth prerequisite placed last where it belongs.

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 parameterless read tool with no output schema, the description supplies what matters: identity scope, sort order, per-item contents, and the sign-in requirement. Only edge-case behavior (empty results, any result cap) is unmentioned.

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 there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4.

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 resource (the person's saved searches) with ordering (newest first) and per-item payload (the link that reopens it), which lets an agent know exactly what it returns. It doesn't explicitly contrast with siblings like save_search or my_saved_listings, so it stops short of 5.

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 name and description — read this to see what the user has saved — but there is no explicit when-to-use/when-not framing or named alternative (e.g., my_saved_listings for saved listings vs. saved searches). 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?

Adds value beyond the annotations: it discloses the realistic scope of destruction (removal from every list that holds the listing, not just one) and the sign-in requirement, neither of which is in the annotation block. It notably implies the listing itself is not deleted, only its shortlist membership – useful nuance the destructiveHint alone would not 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?

A single tight sentence that front-loads the action, then the parameter-driven scope, then the auth note last. No wasted words, no redundancy with the schema or 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?

Covers the key agent needs: what is removed, the two scopes, and the auth requirement, with annotations already carrying the safety profile (destructive, idempotent). No output schema exists and none is needed, though success/failure behavior on a non-member listing is left to the idempotent annotation.

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 50% schema coverage, the description compensates by explaining the default behavior when `list` is omitted (remove from all lists), which the schema ('Only this shortlist. Optional.') does not state. The `id` parameter remains undocumented in both, but its meaning is self-evident.

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+resource: 'Take a listing out of the person's shortlists' clearly states the operation on the shortlist resource, setting it apart from delete_saved_search (a different resource) and save_listing (the inverse). It never names a sibling explicitly, but the resource alone is unambiguous.

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 clarifies the two operating modes ('out of the named `list`, or out of every list of theirs that holds it') and adds an auth prerequisite, which is genuine usage context. However, it gives no explicit when-to-use vs. save_listing or when-not guidance and leaves routing to alternatives 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?

Goes well beyond the annotations: it discloses that a credit is consumed, the concrete plan pricing and reveal counts, the free-reveal case, idempotent behavior (already revealed costs nothing, matching idempotentHint), the sign-in requirement, and the failure shape (revealed: false with upgrade_url). This is exactly the behavioral detail annotations alone 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-loads the purpose and return fields, then the cost/auth caveats. The pricing parenthesis is dense but directly supports the spend-decision the agent must make, so it earns its place; slightly tighter phrasing could still trim it.

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 having no output schema, the description explains the meaningful return outcome (revealed: false + upgrade_url when quota is exhausted) and all preconditions. An agent has everything needed to decide whether to call 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?

Only one parameter (id) with 100% schema description coverage and a clear schema description pointing back to search_listings. The description adds no syntax or format detail beyond the schema, 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?

States a specific verb (reveal) and resource (who is selling/letting a listing) and enumerates the exact fields returned: portal/agency, agent, ad reference, original ad link, ad text. This clearly separates it from read-only siblings like get_listing or search_listings, which cannot return seller identity.

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 strong when-to-use context: requires sign-in, must ask the person before spending a reveal, an already-revealed listing costs nothing, and no-reveals-left returns revealed: false. It stops short of naming alternatives (e.g., get_listing for free non-seller data), so it is clear context rather than full alternative routing.

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 this is a non-readOnly, non-destructive, idempotent, closed-world write. The description adds context annotations can't carry: authentication is required, and a side effect occurs (a first list is created if none exists, and an unknown `list` name silently creates a new list). It doesn't describe the response payload, but that gap is modest.

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 tightly written sentences; the core action and destination come first, followed by the parameter branching and the auth requirement. No filler.

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 should carry the return/confirmation story, and it does not say what a successful save returns or reports. Otherwise it covers the mutation semantics, side effects, and auth, which is nearly everything an agent needs to invoke it correctly.

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 the baseline is 3, but the description goes further by defining the fallback semantics of `list` when omitted and the create-on-unknown behavior, which the schema's 'A shortlist name. Optional.' does not convey. It also implicitly documents that `id` comes from search_listings, matching 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 (save) and resource (a listing) plus the destination concept (the person's shortlists, tied to the evryroom.com heart behavior), which cleanly separates it from remove_saved_listing and my_saved_listings. An agent knows exactly what this does 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?

Explains the branching conditions for the optional `list` parameter (absent -> first list, made if none; unknown name -> new list) and the sign-in prerequisite, which is solid context. It stops short of naming alternatives or stating when-not-to-use (e.g., when the listing is already saved, or versus save_search).

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=false, idempotentHint=true and destructiveHint=false. The description adds two things the annotations cannot: the authentication requirement and the externally visible side effect (it persists into the user's saved searches on the web app). It stops short of explaining what happens when a name already exists, which is the key behavioral question for an idempotent save.

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 short sentences with no filler: identity of the operation first, equivalence to search_listings second, prerequisite last. Every clause earns its place and nothing is repeated from the schema.

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 16-parameter write tool with no output schema, the description covers purpose, persistence, auth and filter provenance, which is enough to call it correctly. It leaves open the duplicate-name/idempotency behavior and why a saved search carries a 'page' parameter, which are minor but real gaps.

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 16 parameters at 81% schema description coverage, the schema carries most of the semantic load and the baseline would be 3. The description's 'same filters as search_listings' adds real value by telling the agent it can reuse a known filter vocabulary rather than re-deriving 16 fields, plus it hints at the naming intent via the 'save under a name' phrasing.

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+resource ('Save a search under a name') and locates the effect ('appears in the person's saved searches on evryroom.com'). It also differentiates from the sibling search_listings by clarifying that the same filters are reused rather than redefined, so an agent can distinguish saving from searching without opening either 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 a clear prerequisite ('Needs sign-in') and implicitly routes the agent from search_listings (build the filters there, then save them here). It does not name an explicit when-not or point at my_saved_searches/delete_saved_search for managing existing saves, so the sibling routing is not fully spelled out.

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?

Beyond the readOnly/idempotent/non-destructive annotations, it discloses page size (24 results), default ordering ('newest first unless sorted'), the fields returned, and a hard 4-page cap on a single search. It also explains the currency semantics of the price filters, including the rent-per-year market caveat. These are the behavioral traits an agent cannot infer from the annotations or 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?

Three sentences, front-loaded with the purpose and results shape, with no filler. The final sentence about euro pricing is slightly convoluted but earns its place because the unit ambiguity genuinely affects filter values.

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 15-parameter search tool with annotations but no output schema, the description covers result shape, ordering, pagination limits, and price-unit semantics, leaving the remaining filters (kind, town, text, areas, near, min_baths) to the well-populated schema. Nothing essential for correct invocation 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 already 80%, so most parameters are self-documenting, but the description adds value by clarifying that price min/max are interpreted as a sale price or a monthly rent in euros, and that some markets quote rent annually. It also reinforces that filters ('narrow') are preferred over the page parameter, adding intent the schema does not convey.

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 scope ('Search homes for sale or to rent in one market'), which is clearly distinct from single-listing siblings like get_listing or compare_listings. It does not explicitly name any sibling to route the agent, so it stops short of a 5.

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?

'Up to 4 pages per search: narrow with filters rather than paging' gives concrete operational guidance on when to filter versus paginate, which is the key usage decision for this tool. There are no explicit exclusions or named alternatives, so it is clear context rather than full routing guidance.

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