Realty.Bingo

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

Annotations establish the safety profile (destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds real value on top: rent estimates are 'labelled', the disclaimer must always be relayed, and gross yield is explicitly not a return. The unexplained gap is readOnlyHint=false for what reads as a pure calculation tool — nothing in the description accounts for the write/non-idempotent side (e.g., a live RentCast refresh or quota cost).

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?

Dense but front-loaded: outputs and data sources come first, assumptions and the disclaimer caveat last. Every clause carries information, though the opening metric list is compressed to the point of being slightly hard to parse on one read.

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 enumerates return values, and it covers the rent-source logic. The main omission is identifier selection: both listing_id and property_id are optional and mutually unexplained, which is exactly what an agent needs to invoke this correctly. The non-read-only hint is also left unaccounted for.

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 40%, so the description must compensate, and it largely does: it names most assumption fields (down payment, rate, taxes, insurance, vacancy, repairs, management, capex) and both rent paths (monthly_rent vs. the labelled estimate). It omits loan_years and hoa_monthly, and never explains how listing_id vs. property_id are meant to be chosen given neither is required.

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 ('analyze' an investment property / sale listing) with an explicit enumeration of the computed metrics (gross yield, price-to-rent, price per sq ft, cash flow, cap rate, cash-on-cash, sensitivity table) and the three rent-data sources. It is clearly distinct in function from siblings like get_property_details or compare_properties, though it never names or contrasts them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the framing (analyze a sale listing, with assumptions for the fuller cash-flow view), and the ordering of rent sources conveys an implicit priority (user rent > rental listing > labelled estimate). There is no explicit when-to-use / when-not-to-use guidance and no alternative tool is named, 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 cover read-only, idempotent and non-destructive, so the description is free to add the value it does: the exact fields returned, the 'unknown where the listing is silent' data-completeness caveat, and the optional match-score mode. It stops short of stating result ordering or output shape, but goes meaningfully beyond the structured hints.

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 ('Side-by-side comparison of 2-5 properties...') followed by the dimension list and the optional watchlist clause. The dense clause list is long but each item is load-bearing, since there is no output schema to carry the compared fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must convey what comes back, and it does so by enumerating compared dimensions plus the unknown-when-silent caveat. Read-only behavior is covered by annotations, so the remaining omission — result ordering or uncertainty about duplicate ids — is minor.

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 50% — property_ids has no inline description. The description compensates by naming 'property_id' and bounding the count to 2-5, and it explains the watchlist parameter as scoring each property against a saved search, which matches and enriches the schema's terse one-liner.

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 (compare) and resource (properties) with the exact scope of 2-5 items and the dimensions compared (price, size, age, HOA, etc.). It is clearly distinguishable from siblings like get_property_details or analyze_property_investment by the multi-property side-by-side framing, though it never names an alternative to route against.

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 '2-5 properties' constraint tells the agent the batch size, and the optional watchlist clause hints at the scoring use case. There is no explicit when-to-use vs when-to-pick-get_property_details/analyze_property_investment guidance.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, and the description explains why: "Returned alerts are marked retrieved," i.e. the call mutates alert state so a repeat call differs. It also discloses the payload shape (property, source, previous/current values, detection time, freshness, match reason) and adds a meaningful guardrail against overstating the wording. It does not mention permissions 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?

Front-loaded with the resource and its alert vocabulary, then filtering, then payload, then the wording guardrail. Efficient overall, though the inline enumeration of ten alert types is a long block that partly duplicates the schema enum.

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 describing the alert fields, the freshness/match-reason metadata, and the side effect of marking alerts retrieved. The remaining gap is pagination/limit behavior and the omitted alert types, which are minor for a 4-parameter read-with-side-effect 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 description coverage is only 25%, so the description has to carry more weight. It covers the `types` and `watchlist` filters in prose and its "marked retrieved" note implicitly explains `include_already_retrieved`, but `limit` is never addressed and the enumerated alert list omits four schema enum values (NEW_LISTING_OBSERVED, PRICE_INCREASE, PROPERTY_PENDING, PROPERTY_SOLD).

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?

Names a specific verb+resource (retrieve monitoring alerts) and enumerates the alert categories it returns, which frames it distinctly from search_properties and get_property_history. However, it never explicitly names a sibling or states what makes it different, so sibling differentiation is implied rather than stated.

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?

"Filter by types (e.g. price changes only) or watchlist" gives a usable filtering hint, which is more than nothing. But there is no when-to-use/when-not guidance and no routing to alternatives such as get_property_history for older events or search_properties for non-alert discovery.

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 annotations giving readOnlyHint=false/idempotentHint=false, the description usefully explains why: refresh=true performs a live fetch from source when the stored record is over a day old, i.e. a network side effect that explains the non-read-only, non-idempotent profile. It also discloses that contact data is 'as published', that features carry evidence, that identity resolution has a confidence value, and that rent/value figures are 'labelled as estimates'. No contradiction with the annotation profile.

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 primary payload ('Everything Realty.Bingo holds on one property or listing'), then a compact colon-list of returned content, then the refresh clause. No filler sentences, though the dense inline list is slightly harder to scan than separated clauses.

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?

There is no output schema, so the description carries the return-value burden and does so thoroughly by enumerating the response contents. The remaining gap is the zero-required-parameter situation: it never states what happens without property_id/listing_id or whether both may be passed together, which is a meaningful ambiguity for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33% (only refresh is documented in the schema), so the description must compensate. It does add real semantics: property_id and listing_id are alternative lookup keys for the same tool, and it restates the refresh trigger with the 24-hour threshold. It stops short of explaining the rrp_/rrl_ ID formats or what happens when both or neither ID is supplied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete lookup target (one property by property_id or one listing by listing_id) and enumerates exactly what is returned — attributes, listings, contact, features, identity confidence, changes, estimates. That is far more specific than a generic get_details. It does not, however, explicitly differentiate itself from overlapping siblings such as get_property_history (which also touches 'recent changes') or search_properties.

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: supply a property_id or listing_id to retrieve a single record. There is no guidance on when to prefer this over search_properties when the ID is unknown, no explicit when-not condition, and no statement about which sibling to use for history versus full details.

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-only, idempotent, closed-world profile, so the bar is lower; the description nevertheless adds real behavioral context by guaranteeing provenance separation between observed data and the source's self-reported history, and by explicitly stating the limitation 'never infers an earlier price.' It does not cover ordering, pagination, or volume of returned history.

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 dense sentences, front-loaded with the core payload before the provenance and inference caveats; each sentence carries distinct information with no filler. Slightly compressed but appropriately sized for the tool.

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 does the work of describing the return structure (observed vs source-reported vs cumulative), which is the most important missing piece and is handled well. It falls short on the two-ID parameter choice and on when this tool beats get_property_details.

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?

Two ID parameters with 0% schema description coverage, and the description never mentions listing_id or property_id at all — not which to supply, whether both are accepted, nor how they relate. With required=0 the agent has no guidance on selection, so the description fails to compensate for the schema 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 ('Price and status history for a property') and enumerates the concrete payload components: observed history with dates, detected changes, source-reported history, cumulative change. It implicitly separates itself from get_property_details (current state) but never names a sibling to make the routing 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 only implied — an agent can infer 'use this when you need price/status changes over time' — but there is no explicit when-to-use, no when-not-to-use, and no pointer to get_property_details or compare_properties for adjacent needs. Adequate but leaves the 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond that: it does not mark alerts retrieved, clarifying a side effect an agent might otherwise assume. Return-shape detail (pagination, size) is absent but not critical here.

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 dense sentence that front-loads the highest-value content (pending alerts, top items) before less central items, followed by a short side-effect disclaimer. Every clause maps to a distinct part of the digest, though the sentence is long enough to be slightly taxing.

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 what comes back, and its enumeration of digest sections does this well. Personalization is stated ('learned-preference suggestions'), so an agent understands the result is user-specific. Minor gaps remain around freshness/refresh behavior but nothing essential 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly spends no space on parameter 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?

The description names a specific resource (a personalized digest) and enumerates its contents: pending alert counts, watchlist matches and data age, tracked property changes, and preference suggestions. This clearly separates it from narrower siblings like get_property_alerts or get_property_history, though it does not explicitly name those alternatives.

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 (a digest is the natural starting point for a session) but there is no explicit when-to-use or when-to-prefer-alternatives guidance. The clause 'Does not mark alerts retrieved' is the only comparative hint, implicitly contrasting it with alert-fetching tools that may change state.

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, readOnlyHint=false and idempotentHint=false, so safety is partly covered. The description adds genuinely useful operational context beyond that: delete must be paired with confirm: true, pause/resume are non-terminal state changes, and plan limits are surfaced. It does not state permission requirements for the destructive path.

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 dense sentence that front-loads the action list and the confirmation requirement before the secondary 'matches' and plan-limit notes. No filler, though it is slightly run-on and packs three separate ideas into one sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotation coverage of return values, the description should say more about what list/get/matches return. It only hints at returns ('best-scoring current listings', 'plan limits') and is silent on error behavior, per-user scoping, and pagination. Adequate but with clear gaps for a 6-action multi-mode 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 0%, so the description has to carry the load, and it largely does: it explains that 'name' identifies the watchlist, enumerates the valid action values, and specifies that 'confirm: true' gates deletion. It does not say what happens when name is omitted for actions that need it, or whether name is ignored for 'list'.

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 opens with a specific set of verbs (list, get, pause, resume, delete) applied to a named resource ('the user's watchlists'), plus a distinct 'matches' mode. That is far more informative than the title 'Manage watchlists'. It does not explicitly contrast itself with the sibling save_property_watchlist, but the action enumeration implicitly covers that gap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clarifies the two non-obvious invocations: 'matches' returns the best-scoring current listings, and delete requires confirm: true. However there is no explicit when-to-use-this-vs-alternative guidance, e.g. no statement that creating a watchlist belongs to save_property_watchlist rather than here. Usage is implied by the action list rather than stated.

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 tool as non-read-only and destructive, but the description adds useful behavioral context: destructive account/personalization actions require confirmation and an explicit request, webhooks are signed and gated by paid plans, and preferences include provenance. These details go beyond the structured annotations. The omission of `revoke_key` behavior keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single semicolon-separated sentence that is front-loaded with the view operation and then groups related actions. It is dense but efficient, with no filler. A clearer enumeration of actions, especially including `revoke_key`, would improve structure slightly.

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 complex tool with nine action values, destructive behavior, no output schema, and 0% schema description coverage, the description covers many important semantics and safety constraints. It still leaves out the `key` parameter and the `revoke_key` action, which are material gaps for correct invocation. The account-view return shape is also unstated, though no output schema exists.

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 parameter meaning. It explains most action values and the `confirm` requirement for destructive account actions, and it implies `webhook_url` through the webhook action. However, it never explains the `key` parameter and omits the `revoke_key` action, leaving meaningful gaps.

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 specific verbs and resources for account viewing, preference management, personalization clearing, account deletion, and webhook management, so the tool's purpose is clear. It is distinguishable from the property-focused siblings. However, it omits the `revoke_key` action and does not explicitly contrast itself with any sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete prerequisites for sensitive actions: `clear_personalization` and `delete_account` need `confirm: true` and an explicit request, and webhooks are limited to paid plans. It does not name alternatives or when-not-to-use cases, but no sibling tool appears to cover account management, so the guidance is reasonably clear.

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 write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, and the description adds real semantics: 'save (also tracks it)' and 'dismiss (never shown again)' explain durable side effects. It also discloses the return payload ('learned preference suggestions and clarifying questions'), 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?

Front-loaded with the verb and the discriminating enum values, then the guardrail, then the return note — three sentences, no filler. The inline enum parentheticals are dense but each one adds usable meaning rather than restating 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 four-parameter write tool with no output schema, the description covers the feedback semantics and return values but leaves the identifier parameters and the reasons cap unexplained. An agent still cannot determine from the description alone which id to supply or whether one is mandatory.

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 burden: it enumerates all seven feedback values and all ten reasons with meaning, matching the schema enums. However, the listing_id/property_id parameters (and their rrl_/rrp_ patterns), the maxItems=5 cap on reasons, and which identifier is required are never addressed.

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 ('Record') plus resource ('the user's reaction to a property') and enumerates the exact feedback vocabulary, so the agent knows precisely what payload is accepted. It is clearly distinguishable from watchlist/alerts siblings by being about reaction capture rather than watch management.

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?

"Only when the user says so" is an explicit when-to-use constraint that prevents proactive/unsolicited logging. It does not name alternatives (e.g., track_property or manage_property_watchlist) or describe the inverse case, so it stops short of full routing guidance.

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

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

Annotations only give the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds substantial behavior beyond that: asynchronous scheduled monitoring outside the conversation, the alert categories recorded (new listings, price reductions, relistings), replace-on-same-name semantics, the refusal of fair-housing-style people preferences, and the shape of the response (hard/soft/excluded interpretation plus a stored-data preview).

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 dense paragraph with the core action front-loaded, then monitoring behavior, replacement semantics, and the return/fair-housing caveats. Every clause carries information, though the alert-preference enumeration is slightly list-like and could be tightened.

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 correctly explains what comes back (criteria interpretation and a preview from stored data). It also covers the policy boundary (fair housing refusals) and the persistence/monitoring model, which are the non-obvious things an agent needs before calling this five-parameter, nested-schema 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 description coverage is reported at 0%, so the description must compensate, and it does for the semantically tricky parts: alert_prefs (min_score, new listings, price drops with optional minimum percent or amount, back on market) and the hard-vs-soft-vs-excluded criteria distinction. It adds nothing for name, priority, or monitoring, leaving those to the schema's enums and defaults.

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 ('Save the user's search criteria once as a named, persistent watchlist') and explicitly anchors it to a sibling's criteria model ('same criteria as search_properties'). An agent can distinguish this from search_properties and manage_property_watchlist 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?

Explains the context clearly: save criteria once, then Realty.Bingo monitors on a schedule independent of any conversation, and re-saving with the same name replaces the prior watchlist. It does not explicitly say when to prefer this over manage_property_watchlist or when not to save, so it stops short of 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?

Goes well beyond the annotations by disclosing the 12-hour cache reuse rule, daily-allowance-gated live requests, the Realtor.com/RentCast source chain, and the 'unknown means unknown, never assumed' contract. The live-request behavior also explains why readOnlyHint=false despite this being a search, resolving a potential inconsistency rather than creating one.

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?

Purpose and scope are front-loaded in the first sentence, and each subsequent clause adds real semantics (filter classes, scoring, unknowns, cache, source). It is clause-dense rather than flabby, though the stacked list of ranked/excluded parameters makes it heavier than it needs to be.

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 28-parameter tool with no output schema, the description carries much of the return-value burden (0-100 match score with reasons and uncertainties, feature evidence class, source, last-confirmed-active) and the hard/soft/unknown model. It still omits pagination/sort behavior and several filter families, so it is strong but not fully complete.

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 43% across 28 params, so the description must compensate — and it does by teaching the semantic taxonomy (hard vs soft vs exclusion) and naming max_price, min_bedrooms, min_bathrooms, property_types, must_have, ideal_max_price, preferred_bedrooms, nice_to_have, styles, avoid, exclude_property_types. Numerous parameters (investment, max_distance, bedrooms_exception, sort/limit/offset, area and year bounds) get no description-level explanation, leaving the gap only partly closed.

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 ('Find active U.S. homes for sale or rent') plus the exact geographic shapes accepted (city+state, ZIP, radius, polygon). That scope cleanly separates it from siblings like get_property_details (single listing) and compare_properties (multi-listing analysis).

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: hard requirements filter, soft preferences rank, avoid/exclude remove, and when cache vs live requests apply. However, it never explicitly names an alternative tool or state when NOT to use this search (e.g. versus compare_properties or get_property_details), which keeps it 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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the agent knows this is a state-changing, non-idempotent operation. The description adds that tracked properties produce alerts on verified price or status changes, which is useful behavioral context beyond annotations. However, it doesn't clarify whether tracking requires the property to exist, what happens on untrack, 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?

Three sentences that are front-loaded with the action and resource, then thresholds, then alert behavior. Every sentence adds information without waste. Could be slightly more structured with explicit action-parameter mapping.

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 6 params, no output schema, and partial schema descriptions, the description does not fully explain parameter applicability per action (e.g., listing_id vs property_id), nor does it cover the note parameter or untrack behavior. It's adequate but with clear gaps for a multi-action 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 description coverage is only 33%, with price_below and min_drop_pct documented in the schema but listing_id, property_id, note, and action lacking descriptions. The description mentions optional price_below and min_drop_pct thresholds, adding some meaning, but doesn't compensate for the undocumented parameter formats or which parameters apply to which action. Baseline 3 for partial coverage.

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 three actions (track, untrack, list) on properties, which is a specific verb+resource. However, it doesn't distinguish this from sibling tools like manage_property_watchlist or save_property_watchlist, which appear to overlap functionally. The purpose is clear enough but lacks sibling differentiation.

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 guidance on when to use this tool versus alternatives like manage_property_watchlist or save_property_watchlist. The description mentions thresholds but doesn't explain when to set them or what action they apply to. The agent must infer usage from the action enum alone.

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