RentReboot Apartment Search

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

Annotations already establish the safe read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's job is additive. It does add two useful behavioral facts: results are confined to 'their own market' and it 'returns names only, not listings', which with no output schema is a meaningful disclosure about return content.

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 lookup purpose front-loaded and the scope constraint immediately after. 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 small read-only lookup tool with no output schema, the description covers purpose, market scope, and result type (names, not listings). Only the limit/pagination behavior and how query matching works are unaddressed, which is a minor 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 only 50% (query is documented, limit is not), so the description should compensate, yet it says nothing about either parameter — no matching semantics for query, no cap/default behavior for limit. The 'in their own market' phrasing hints no market parameter exists but adds no real semantics.

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 ('look up neighborhood names and ids') and scopes it to what the connected renter can add to their alert search, which separates it from the plain list_neighborhoods sibling without naming it. The distinction is inferable but not explicit.

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 alert-search framing, but there is no explicit when-to-use statement and no guidance on why an agent would pick this over list_neighborhoods or get_search_preferences. The reader must infer the routing decision.

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 the safe read profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the bar is lower. The description adds real context beyond them: it scopes the read to 'the connected renter' (i.e. the authenticated account only) and enumerates the exact returned state, which matters because there is no output schema. It still says nothing about behavior when no account is connected.

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 leads with the most decision-relevant fact (plan: free or paid) and then packs the remaining returned fields without filler. Every clause maps to content the agent or user will actually receive.

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 input parameters, no output schema, and annotations carrying the safety profile, the description's field enumeration is the main source of return-value information and covers it well. It stops short of covering edge cases such as an unconnected/unauthenticated state or what the manage link requires.

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. Schema coverage is nominally 100% and there is nothing for the description to disambiguate beyond the implicit 'no arguments needed' contract.

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 clear verb ('Show') on a specific resource (the connected renter's account) and enumerates exactly what that resource comprises: plan, alert state, market, frequency, channel, and manage link. It is unambiguous on its own, but it never distinguishes itself from siblings such as set_apartment_alerts or update_search_preferences, which touch overlapping concepts (alerts, search settings).

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 field list makes it obvious this is the tool for viewing account state, and the mention of the alerts on/paused flag faintly gestures at set_apartment_alerts. There is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer the 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that by disclosing that the guide is public (no auth needed) and returned as Markdown, which no structured field states.

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 with zero filler; verb, resource, scope, format, and key all appear once and in a sensible order.

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 read tool with full annotation coverage and no output schema, the description is nearly sufficient: it covers access scope and return format. It would be fully complete if it noted that the slug must be exact or pointed to search_guides for discovery.

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 0%, so the burden falls on the description, which only says 'using its slug' and does not explain where slugs come from or that they are exact-match. The schema's pattern and maxLength do encode the format constraints, partially offsetting the gap.

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 ('Retrieve'), resource ('RentReboot guide'), access scope ('public'), return format ('Markdown'), and identifier ('slug') are all stated. It does not, however, name the sibling that produces slugs (search_guides), so it relies on the agent inferring the relationship.

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 tool takes a slug, so the agent infers it needs an existing slug rather than a query. There is no statement of when to prefer this over search_guides or how to obtain a valid slug.

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 adds genuine context by stating the values are aggregated and not personal data, but it says nothing about result shape (which percentiles), rate limits, or failure behavior when the neighborhood is unpublished.

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, front-loaded with the verb and resource; the second sentence is not filler but a meaningful scope/privacy clarification. Nothing is redundant with the title or 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 simple, annotation-covered read tool with no output schema, the description adequately covers what is returned and the aggregation/privacy guarantee. Remaining gaps (category semantics, how to obtain valid neighborhood identifiers) are modest given the schema provides area format examples.

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 67%, and the one undocumented parameter, 'category' (enum all/likely/verified), is semantically opaque without explanation. The description mentions no parameters at all, so it does not compensate for the coverage gap or clarify what 'likely' versus 'verified' rents mean.

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 ('Retrieve') and a precise resource ('aggregate asking-rent percentiles and sample sizes') scoped to a published NYC neighborhood. It implicitly separates itself from listing-oriented siblings via 'not individual listings or personal data', but it never names an alternative tool, so differentiation is inferential rather than explicit.

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 'published NYC neighborhood' phrasing implies a precondition (the neighborhood must exist/published) and the scope note tells the agent this is a statistics lookup rather than a listing search. However, there is no explicit when-to-use/when-not or pointer to a sibling for resolving neighborhood names, so the agent must infer 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 structurally. The description still adds value by implying the read-before-write workflow and by enumerating what the saved search comprises, though it adds nothing about formatting or edge cases.

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 verb and resource, and the field enumeration earns its place by previewing the return shape in the absence of an output schema. The list is long but not padded with 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 usefully substitutes by enumerating the returned fields, and with zero parameters there is nothing else an agent needs before invoking this read-only 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a parameterless 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 verb ('Show') and resource ('the connected renter's saved alert search') and enumerates exactly what the resource contains (budget, bedrooms, filters, alert frequency, channel). This clearly distinguishes it from write siblings like update_search_preferences and set_apartment_alerts.

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 instruction 'Read this before changing the search' gives explicit context for when to use it, effectively routing the agent to call this before update_search_preferences. It stops short of naming the alternative tool or stating when-not to use it.

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. The description adds rich behavioral context beyond that: ordering (newest first), pagination via nextCursor, a 200-item window, hidden-filtering semantics, privacy guarantees (no account identifiers or broker contact details), and the state fields returned. This is exactly the kind of extra signal that helps an agent call the tool correctly.

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 description is front-loaded with the core purpose and then adds five tightly scoped sentences covering pagination, filtering, link behavior, and privacy. Every sentence earns its place with no redundancy.

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 the output schema exists, the return values need not be explained. The description covers pagination, filtering, ordering, link behavior, and privacy—everything an agent needs to invoke the tool correctly. The only omission (limit behavior) is minor because the schema supplies constraints.

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% (cursor only). The description compensates for cursor (pass nextCursor for older alerts) and includeHidden (hidden left out unless true), adding meaning beyond the schema for those two. But the limit parameter is entirely undocumented in both schema and description, leaving a gap. Partial compensation yields a 3.

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 verb (List) and resource (apartments RentReboot already sent to the connected renter), and its scope ('already sent') inherently distinguishes it from sibling list_upcoming_matches and update_alerted_listing. An agent can tell what the tool 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?

The description implies usage by stating it lists already-sent alerts and describes pagination and hidden filtering. However, it does not explicitly name alternatives or state when to choose this over list_upcoming_matches or other sibling tools, leaving the agent to infer the boundary.

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 'Read-only' in the description is largely redundant. However, the explicit exclusion list (credentials, application numbers, income, household details, email, internal identifiers) is genuine added context about the data surface that 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?

Two short sentences with zero filler, and the scope statement is front-loaded ahead of the privacy qualifier. Every clause adds 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?

An output schema exists, so return-value shape need not be explained, and the description covers scope plus data exclusions. The remaining gap is pagination/limit behavior, which matters for a list tool but is a minor omission given the annotations and output 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 description coverage is 0% and the description says nothing about the single 'limit' parameter, its default of 20, or the 50-item ceiling. Since the tool does take a parameter, the description should have compensated for the silent schema but does not; only the schema's own bounds/default carry any meaning.

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 a precisely scoped resource (the connected renter's provider-confirmed NYC Housing Connect application statuses). No sibling tool touches Housing Lottery applications, and the 'provider-confirmed' qualifier further narrows what is returned, 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?

There is no when-to-use statement, no prerequisites, and no mention of alternatives such as list_alerted_listings or list_upcoming_matches. The 'connected renter's' phrasing implies whose data comes back, but the agent must infer the usage context entirely.

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 openWorldHint=false, so the safety profile is covered. The description adds the meaningful scoping fact that only neighborhoods with published percentile data are returned, but says nothing about pagination or the default page size.

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 with no filler or repetition. It is efficient, though arguably too terse for the amount of undocumented behavior the tool carries.

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 two-parameter listing tool with no output schema and 0% parameter documentation, the description should at least explain the query and limit parameters and the shape of results. It leaves the agent guessing how to filter or page.

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 0% — neither 'limit' nor 'query' is documented in the schema, and the description adds nothing about them. It never explains that query filters by name or that limit caps results at 100 with a default of 50, so the description fails to compensate for the coverage gap.

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 (list NYC neighborhoods) plus a scope qualifier: only those with published RentReboot asking-rent percentile data. This is clear, though it never distinguishes itself from the sibling find_search_neighborhoods, which an agent could plausibly confuse it 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?

No when-to-use guidance, no prerequisites, and no mention of the alternative find_search_neighborhoods tool. The only hint is the implicit scope of the data set; the agent must infer when this tool is the right pick.

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 openWorldHint=false, so the safety profile is covered; the description's 'Read-only' largely repeats it. However, it adds genuinely non-obvious context by stating the output excludes broker contact details and account identifiers, 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?

Two front-loaded sentences that get to the scope and the exclusion behavior quickly. The 'Read-only' clause partially duplicates the readOnlyHint annotation, so a small amount of the text does not earn 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?

An output schema exists so return format needn't be described, and the connection/exclusion behavior is stated. It stops short of defining what 'historical' spans chronologically or what happens to archived availability, which would fully close the gap for a list 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?

There is one optional parameter (limit) with 0% schema description coverage, and the description says nothing about it. The schema's own min/max/default constraints carry the semantics well enough for a single integer, but the description does not compensate for the coverage gap.

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 clear verb and resource: listing historical apartment records that match a connected renter's saved requirements. The scope is specific and distinguished from generic search siblings by tying results to saved requirements, though no sibling is named explicitly. The naming mismatch (tool name says 'upcoming', body says 'historical') is partly reconciled by 'planning upcoming availability'.

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 'useful for planning upcoming availability' implies a usage context, but there is no explicit when-to-use vs when-not, and no alternative tool is named despite near siblings like get_search_preferences or list_alerted_listings that could be confused with this.

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 two useful facts beyond the annotations: the corpus is public (implying no auth) and results are canonical URLs rather than content. It says nothing about ranking, rate limits, or empty-result behavior, so the gain 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?

A single sentence that front-loads the verb and resource and ends with the return format. No padding, no restatement 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?

For a two-parameter, read-only search tool with full annotation coverage and no output schema, the description covers action, scope, and result form adequately. It stops short of explaining result ordering or how limit interacts with results, which would fully close the loop.

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 50%: query is documented in the schema (maxLength 100, minLength 1) but limit (min 1, max 10, default 5) is undocumented in both places. The description's 'by keyword' merely echoes the existing query description and does nothing to compensate for the unexplained limit parameter.

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), resource (RentReboot public NYC renter guides), and scope (keyword search), plus what comes back (canonical URLs). This implicitly separates it from sibling get_guide, which would retrieve a guide's content; however, it never names that sibling, so the differentiation is inferential rather than explicit.

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 keyword-search framing implies when to reach for this tool, but there is no explicit when-to-use statement, no exclusions, and no pointer to get_guide for full content versus this tool for discovery. Usage is left 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 establish mutation (readOnlyHint=false), idempotency, and non-destructiveness; the description adds value beyond that by scoping the blast radius (only alerts toggle, other settings preserved) and imposing a consent requirement. Return format is not described, but there is no output schema and the operation is a simple toggle.

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, front-loaded with the action and parameter mapping, then scope, then the safety instruction. 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 one-parameter toggle with no output schema, the description supplies everything needed: the action, the parameter semantics, the scope of side effects, and a consent guardrail.

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 0%, so the description carries the full burden — and it does, mapping enabled=false to pause and enabled=true to resume. That fully disambiguates the single boolean parameter; only minor details (e.g., required/type) are 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 specific verbs (pause/resume) and the exact resource (the connected renter's apartment alerts), with the boolean mapping inline. An agent can immediately distinguish this from siblings like update_search_preferences or update_alerted_listing.

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 clear context for use and implicitly routes away from siblings by stating that search, plan, billing, and Housing Connect settings are untouched, plus an explicit precondition ('Confirm with the renter first'). It does not name an alternative tool or an explicit when-not condition, so it stops 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 the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), lowering the disclosure bar. The description usefully adds that status "none" clears the state, but it never explains how the independent saved/hidden/status fields interact (e.g. saved and hidden both true, or contradictory combinations), nor what the response returns.

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 plus an ID-sourcing clause, with the core action and state list front-loaded. The dashboard-buttons analogy earns its place as a mental model; little is wasted, though slightly denser than strictly needed.

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 4-param mutation tool with no output schema, the description covers the state vocabulary well but omits the return value and the interaction rules between the three state fields. An agent knows what to send but not how the write resolves.

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 0%, so the description must carry the load — and it does for most fields: saved=save, hidden=hide, the status enum values including the "none" clear case, and listingId's provenance from list_alerted_listings. It falls short only on how saved/hidden/status combine, which the schema does not constrain.

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 (change state), the exact resource (one apartment from the renter's alerts), and enumerates the resulting states (saved, hidden, contacted, toured, applied, none clears). It also cites the sibling list_alerted_listings as the ID source, so an agent can place it precisely among the alert-related tools.

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 clear context that this is the write counterpart to list_alerted_listings and mirrors the dashboard buttons, plus where to source listingId. It does not explicitly say when NOT to use it or contrast with update_search_preferences, but for a state-toggle tool the routing 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?

With destructiveHint=true and idempotentHint=true already declared, the description usefully adds partial-update semantics ('everything else stays'), inheritance of the preferences-page rules, the new-account city constraint, and the alertFrequency/weekly-recap interaction. It does not contradict annotations; 'everything else stays' refers to unsent fields, consistent with the schema's list-replacement notes.

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 action and partial-update rule, then layered constraints and a caution. Dense but almost every sentence carries actionable content; slight overload from cramming several rules into one block.

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 17-parameter mutation tool with nested objects and no output schema, the description covers the critical behaviors: partial update, rule inheritance, new-account constraint, and confirmation requirement. It could note the response/return behavior, but the destructive and idempotent annotations plus the rules given make it largely sufficient.

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 moderate (59%) and the schema already documents many params (city, channel, minRent, amenities, neighborhoods, alertFrequency, strictMoveInDate). The description adds real meaning for city ('set once, market cannot change here') and alertFrequency ('weekly recap pauses individual alerts'), but leaves many parameters undiscussed. Baseline 3 is fair.

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 verb and resource: 'Change the connected renter's saved alert search.' That distinguishes it from read-oriented siblings like get_search_preferences and from set_apartment_alerts, though no sibling is named explicitly. An agent can identify what the tool mutates.

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 clear operational context: send only fields to change, set city with neighborhoods once for a new account, and confirm with the renter before applying. It lacks an explicit pointer to the read counterpart (get_search_preferences) for inspection beforehand, so it stops short of naming alternatives.

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