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

Annotations only declare readOnly/idempotent/openWorld; the description adds substantial behavior beyond them: per-row failure isolation ('one bad target never fails the whole call'), the `retryable` vs `protocol`/`other` distinction with issue #73 context, the overall deadline and `pending` fallback, envelope counts, and concurrent fan-out. This is exactly the operational context annotations cannot 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?

Front-loaded with the core capability, then output shape, then failure/retry semantics, then deadline behavior. Dense but nearly every sentence carries distinct information; the parenthetical restatement of `status` = `error_kind` and the repeated explanation of `extracted_features` are mild 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?

With no output schema, the description fully carries the return contract: both success and error row shapes, `pending` rows, top-level `count`/`ok`/`errored`/`pending`, and the default omission of raw `description`. There is nothing material an agent needs for correct invocation and result handling that is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates `include_description` default false and the `url`/`listing_id_sha` target shape, and mentions `extracted_features` being always populated, but adds no syntax or format detail the schema does not already carry. The `view` parameter is left entirely 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 verb and resource with scope ('Fetch up to 200 Compass listings in a single call') and separates itself from siblings by explicitly naming `compass_compare_properties` as the tool for side-by-side comparison. Also positions itself relative to `compass_get_property` by noting identical target shape. An agent can place it without opening a schema.

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

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

Clear routing guidance: use `compass_compare_properties` for a summary table, batch into multiple calls above 200 targets, and re-run only `pending` rows after a deadline. It also gives actionable retry policy for `retryable: true` cases. What it lacks is an explicit statement of when a single target should go to `compass_get_property` instead of this bulk call.

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 openWorldHint=false, so safety is covered. The description adds meaningful context beyond that: the output shape (max price, binding constraint, PITI breakdown) and the determinism note ('No network — pure local math').

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 rule, then inputs, then outputs. Mostly earns its place, though the 'Same math across the realty MCP cohort (@chrischall/realty-core)' line is promotional filler rather than actionable 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?

No output schema exists, but the description explicitly enumerates the return values (max price, binding constraint, PITI breakdown), compensating adequately. With 10 params at 60% coverage it 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?

Schema coverage is 60% and the description lists the inputs (income, debts, down payment, rate, optional tax/insurance/HOA/term), but it adds no syntax or format detail beyond what the schema already documents. The mid-level coverage justifies the baseline 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?

States a specific verb ('Solve for the maximum home price') and the method (28/36 DTI rule), which cleanly distinguishes it from the sibling compass_calculate_mortgage. An agent can tell what it 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?

Usage context is implied by the description ('what you can afford'), but it never explicitly says when to choose this over compass_calculate_mortgage or what preconditions exist. It is inferable but not 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 readOnlyHint, idempotentHint and openWorldHint=false; the description adds genuinely new behavior by stating there is no network call, that it is fully deterministic, and that PMI applies automatically only when LTV > 80% and pmi_rate is supplied. It does not cover error behavior for invalid inputs, but that is a minor gap given the annotation coverage.

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 purpose and return value before parameter rules; four sentences with no filler. Slightly dense in the parameter-rule sentence, but every clause carries information an agent needs.

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 the PITI return components and total interest, and the annotations cover the safety profile, so an agent has enough to call it correctly. Missing coverage of two parameters and no stated behavior on conflicting down-payment inputs keeps it from being 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?

With only 40% schema description coverage across 10 parameters, the description does real work: it states the down_payment/down_payment_percent mutual exclusivity and 20% default, the property_tax_annual vs property_tax_rate alternatives, and the LTV condition for PMI. It leaves hoa_monthly and insurance_annual unmentioned, so the compensation is strong but not complete.

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 ('Local-only mortgage payment calculator') with a clear scope, and the 'local-only' qualifier implicitly separates it from the network-backed sibling tools. It stops short of explicitly naming compass_calculate_affordability, the nearest sibling, so the boundary between the two calculators must be inferred.

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 context is implied rather than stated: 'safe to use for scenario comparison without burning a fetch' suggests when it is preferable to a network tool, but there is no explicit when-to-use vs when-not rule, nor any pointer to the affordability sibling. The rest of the guidance is parameter mechanics rather than tool selection.

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 far beyond the readOnly/openWorld/idempotent annotations: per-row error capture that prevents one bad target from failing the whole call, specific error_kinds (timeout/bridge_down/protocol/other) with retryable and error fields, concurrency, an overall deadline with a pending status, envelope counts (count/ok/errored/pending), and default suppression of description and summary. This is exactly the kind of failure-mode and resource-bounding detail an agent needs before invoking.

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 core action, then proceeds through per-target input, failure semantics, and defaults in a logical order. It is dense and every sentence carries information, though the single long sentence covering error kinds and envelope keys requires close reading.

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 read-only comparison tool with no output schema, the description fully arms the agent: input forms, redirect path, per-row success/failure contract, retry strategy for pending rows, and the opt-in flags determining response shape. Nothing material 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?

Schema description coverage is already 100%, so the schema documents url, listing_id_sha, view, the toggles, and the min/max bounds. The description reinforces the default-off behavior of description/summary and the sha-only redirect path, but adds no syntax or constraints the schema lacks. Baseline 3 given full schema 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 title and the opening sentence both state a specific verb and resource: fetch 2+ Compass properties and align their facts side-by-side. That distinguishes it from compass_get_property (single fetch) and from compass_bulk_get, which is mentioned later in the schema yet only as an aside. Purpose is clear, though it doesn't sharpen the boundary against compass_bulk_get within the description front-end.

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 explains how to drive each target (url vs sha) and how to handle pending rows, but says nothing about when to pick this tool over compass_get_property or compass_bulk_get. The only comparison guidance is buried in the schema for targets, not the description. Usage is implied by behavior 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?

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses meaningful behavioral details: closed_deals is omitted by default to keep the payload lean, compact view strips image/avatar URLs, full returns Compass's payload untouched, and there is deliberately no field projection because the server has no verified record of which fields matter. This is rich, honest behavioral context and does not contradict any annotation.

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 long but every section earns its place: core fetch, returned shape, closed-deals behavior, view behavior, and chaining guidance are all clearly labeled. The key information is front-loaded, and the internal headings make it easy to scan without losing density.

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 fully carries the responsibility of explaining the response shape, and it does so concretely: { agent: {name, slug}, active_listings: [...] }, normalized fields, closed_deals, and the listing_agent.profile_slug chaining path. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is 100%, but the description goes further by explaining the relationship between slug and profile_url, the exact response effect of compact vs full view, and the normalized shape of closed_deals. It also clarifies that one of slug or profile_url is required, adding meaning beyond the raw 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?

The description opens with a specific verb and resource: "Fetch the listings represented by a Compass agent from their profile page (/agents/<slug>/)." It clearly distinguishes itself from siblings by naming compass_get_property and compass_search_properties and explaining how the agent slug appears in each, so an agent can tell exactly what this tool is for.

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 gives actionable usage guidance: pass either slug or profile_url, both are accepted, and the closed-deals payload is opt-in via include_closed. The CHAINING section explicitly explains when to use this tool relative to compass_get_property and compass_search_properties, including the note that compass_search_properties results don't carry the listing agent.

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 readOnlyHInt annotations, the description discloses the WAF 403 workaround, all three resolution rungs, the candidate verification rule, the stable _pid/ versus fallback _lid/ URL behavior, and the distinct auth_required error shape. This gives an agent unusually complete knowledge of the tool's runtime behavior.

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 long but front-loaded with the central purpose and then logically organized by fallback rung, verification, return values, and error cases. It is slightly redundant with the annotations at the end and includes internal issue IDs that are informative but not essential, so it is not perfectly concise.

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?

Since there is no output schema, the description correctly enumerates the return object, the possible matched_via values, the no-match error shape, and the auth_required error case with retry guidance. Combined with the fully documented input schema and annotations, an agent has everything needed to invoke and interpret this tool 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 description coverage is 100%, so the address/city/state/zip/view parameters are already well documented in the input schema. The description adds free-text semantics for the address and clarifies output fields, but does not add per-parameter meaning beyond what the schema already provides.

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 first sentence is specific: it resolves a free-text street address into a Compass listing's canonical URL and identifiers, which clearly distinguishes it from a generic search or retrieval tool. It stops short of a 5 because it does not explicitly name or differentiate against the sibling compass_resolve_addresses tool.

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 clearly states the intended use case: resolve one free-text street address in a single call, including which fallback strategies will be tried. It does not explicitly list when not to use it or point to batch alternatives like compass_resolve_addresses, so it lacks full exclusion guidance.

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

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

Annotations already cover read-only, idempotent, and open-world, so the bar is lower. The description adds real behavioral value beyond them: how the locality is derived (lifts city/state/zip from homedetails), the empty-result contract ("rentals: [] with the target locality preserved"), and repeated-call safety. No contradiction with annotations.

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, then adds derivation, return shape, and edge-case behavior in a compact block. Dense but every sentence carries information; only the return-field enumeration is mildly 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?

No output schema exists, so the description must carry return-value burden and does: it enumerates returned fields (address, monthly price, beds/baths, sqft, URL) and handles the empty case. Only the exact response envelope shape (keys besides rentals) is left implicit.

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%, so the schema already documents url, view, limit, and listing_id_sha in detail. The description adds only a light note that locality is derived from the target and mentions price_formatted (a return field, not a param), so baseline 3 applies.

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

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

States a specific verb and resource ("Surface nearby rental listings for a Compass property") and even names the business purpose (STR viability). It is clearly distinct from siblings like compass_get_property or compass_compare_properties by resource, but it never explicitly names an alternative, so differentiation is inferred 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?

Gives a use case ("evaluating STR viability in vacation markets") which implies when it's relevant, but offers no when-not guidance and does not name any sibling to use instead. Usage context is present but incomplete.

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, openWorld, but the description goes further: it discloses the three returned arrays, the normalized cross-MCP schema with a fixed type enum, the 302-redirect behavior of sha-only calls, and the data-duplication caveat versus compass_get_property. This is exactly the extra behavioral context annotations cannot 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?

Dense but front-loaded: purpose and event taxonomy first, then return shape, then parameter routing, then the usage caveat. Every sentence carries distinct information — no filler, 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?

There is no output schema, so the description must describe return values, and it does so thoroughly (events, history, events_normalized with the shared field set and enum). Combined with the parameter routing and the read-only note, an agent has everything needed to call 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 adds real meaning beyond the schema — the 'url is preferred, no resolver round-trip needed' tradeoff and the fact that listing_id_sha alone triggers /listing/<sha>/view with a redirect. The view param's compact/full semantics are left to the schema, keeping it from a 5.

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 ('Full listing history for a Compass property') and enumerates the event types it returns. It explicitly distinguishes itself from compass_get_property, telling the agent this is the merged + normalized timeline rather than the inline arrays, so the tool is unmistakable among siblings.

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 an explicit when-to-use rule ('call this tool only when you want the merged + normalized timeline') and names the alternative (compass_get_property returns the same events[]/history[] inline). It also clarifies the url-vs-sha calling condition, leaving nothing 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 readOnly/idempotent/openWorld, and the description adds substantial context beyond them: the /listing/<sha>/view 302-redirect behavior, that `description` is omitted by default, that `extracted_features` is always populated, and that sha URLs go stale on relist while `_pid` is stable. The 'Read-only; safe to call repeatedly' line is mildly redundant with annotations but the rest is genuinely additive.

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?

Long but front-loaded and sectioned (core sentence, DESCRIPTION HANDLING, URL FORMS), so an agent can stop reading once it has what it needs. The _lid/_pid discussion is valuable but slightly verbose, and the read-only line duplicates annotations.

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 correctly carries the return-value burden by enumerating the returned fields (address, neighborhood, beds/baths, sqft, lot_size_acres derivation, price, MLS status, extracted_features, canonical URL). Nothing an agent needs to call it correctly appears missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the fetch-path difference between supplying `listing_id_sha` alone versus `url`, the redirect that follows, and the default behavior of `include_description`. This goes beyond the schema's field-level prose.

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 ('Fetch a property's full Compass record') and immediately scopes it against siblings by tying it to a compass_search_properties result and describing it as the full single-record fetch. An agent can distinguish it from compass_search_properties (list), compass_get_property_photos (photos), and compass_compare_properties (comparison) without opening schemas.

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 says to pass `url` or `listing_id_sha` alone, and the URL FORMS section explains which URL shape to use for reading vs long-lived references. It references where `url` comes from (compass_search_properties). What's missing is explicit guidance on when NOT to use this vs compass_get_by_address or compass_bulk_get, but the context is otherwise 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 readOnly/idempotent/openWorld, but the description adds real value beyond them: the return shape, per-entry CDN/thumbnail/dimension content, the category-0 default, and the redirect behavior. It slightly repeats the safety profile ('read-only; safe to call repeatedly'), which the annotations already 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?

Purpose is front-loaded in the first clause, followed by return format, input routing, and category behavior. Dense but every sentence earns its place; it is slightly packed rather than wasteful.

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 compensates by specifying the returned object `{ listing_id_sha, count, photos }` and what each photo entry contains. An agent has enough to call and interpret the result 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 adds meaning beyond the schema by clarifying that url and listing_id_sha are alternatives and detailing what the sha-only path fetches. It also reinforces the default-off behavior of include_all_categories.

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: the full photo gallery for a Compass listing, resolving to listing.media[]. It is clearly distinguishable from compass_get_property (general property data) and compass_get_price_history by naming the concrete artifact returned.

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 guidance: pass either `url` or `listing_id_sha` alone, and explains the sha-only redirect path. It covers when to use which input, but does not explicitly contrast the tool against siblings like compass_get_property for agents deciding which to call.

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, and the description adds crucial runtime behavior: the tool throws a clear error explaining the limitation and identifies the root cause (auth-scoped GraphQL endpoint not identified). This helps an agent recover without wasting effort.

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 front-load the unsupported status and include only the necessary technical context and error behavior. There is no filler or 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?

For a stub with no parameters and no output schema, the description fully communicates what an agent needs to know: expect no data, expect a clear error, and understand why. 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 has zero parameters and an empty schema, so the description carries no parameter burden. The baseline of 4 applies because there is nothing further to document.

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 immediately states 'Not yet supported' and names the specific underlying resource (/overview/favorites), making the intended function (retrieving saved favorites) and its stub status unmistakable. This distinguishes it from working siblings by clearly communicating that it will not return 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 description gives an explicit when-not-to-use signal: it is not yet supported and throws an error. It does not mention alternatives, but for a deliberately unsupported stub, the exclusion is clear and 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?

While annotations already disclose readOnly, openWorld, and idempotent behavior, the description adds crucial runtime behavior: the tool is not implemented and will throw a clear error explaining the limitation. It also explains why (auth-scoped GraphQL not identified), giving the agent useful context beyond the structured annotations.

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 entire description is one compact sentence plus an explanatory clause. It front-loads the most important fact ('Not yet supported') and provides the necessary detail in two short segments, 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 stub tool with no parameters and no output schema, the description covers the essential facts: it is unsupported, why, and what happens if called. A slight gap is the absence of any pointer to an alternative, but given the low complexity and informative annotations, this is adequate.

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 has zero parameters, so the baseline of 4 applies. There is no parameter semantics to document, and the description does not need to add anything beyond the empty 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?

The description and title make clear the tool concerns the agent's saved Compass searches, and the first phrase 'Not yet supported' immediately conveys the tool's current status. It does not explicitly state the action verb 'get', but the resource is unambiguous and distinct from siblings such as compass_get_saved_homes, so an agent can understand what this tool is about.

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 gives no direct guidance on when to call this tool or which sibling to use instead; it only states that the tool is not yet supported and will throw an error. An agent is left to infer that the call should be avoided, but no alternative tool or condition is offered.

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 openWorldHint=false, so the safety profile is covered. The description goes well beyond that, disclosing the empty/null return state and the non-obvious semantics that the registry does not change request routing, which an agent could not infer from structured fields.

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, each carrying distinct information: the return shape, the empty/null edge case, and the crucial routing caveat. The core purpose is front-loaded and no sentence 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?

No output schema exists, so the description must carry return-value meaning, and it does by naming sessions and active_session_id plus their empty/null behavior. Combined with annotations covering the read-only idempotent profile, nothing needed to invoke or interpret this tool 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 schema has nothing to document and the description correctly spends no words on inputs. Baseline 4 applies for a no-parameter tool; there is no parameter ambiguity to resolve.

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

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

The description gives a specific verb (list) and two concrete resources (registered account labels and active_session_id), so an agent knows exactly what is returned. It does not explicitly name sibling tools like compass_register_session or compass_set_active_session to sharpen the boundary, but the scope is unambiguous on its own.

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 conveys the operative context: that the session registry is a label only and does not affect which account Compass requests use, and that switching accounts requires signing the browser tab in. That is real usage guidance, though it never states a direct 'use this when...' rule or names an alternative tool.

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 cover readOnly/idempotent/openWorld, but the description adds real behavioral value: no auth required, no side effects, the enumerated return fields (role, port, version, link state, elapsed time), and a plain-English hint that distinguishes four distinct failure modes. Since there is no output schema, this disclosure carries the full diagnostic semantics.

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, front-loaded with the core action and followed by returns, then the trigger condition. No filler sentences, though the enumerated diagnostic list makes it longer than strictly necessary.

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 parameters and no output schema, the description fully compensates by describing what gets returned and how to interpret the failure signal. An agent has everything needed to call it and read the result 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly implies no input is needed.

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 concrete action (round-trips a public /robots.txt URL through ContextMint Bridge) plus the output (diagnostics). It is unmistakably distinct from the compass_* data siblings, which fetch property/session data rather than probing the bridge itself.

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 says when to call it: 'when a real tool fails and you want to know which hop broke.' That single condition both triggers use and rules out normal operation, so an agent knows this is a diagnostic fallback rather than a routine call.

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 re-registering the same identity updates rather than duplicates, that a session_id is returned, that mark_active alters the current account in the same call, and — most valuable — that the registry does not change which account requests actually use and that account switching happens via the signed-in browser tab. That last point is non-obvious behavioral context an agent could not derive from readOnlyHint=false / idempotentHint=true.

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 key, and every sentence carries information (idempotent refresh, return value, activation flag, label-only caveat, tab-based account switching). It is on the longer side at five sentences, but none is padding.

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

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

With no output schema, the description correctly supplies the return value (session_id), and with three simple parameters and default false on mark_active, nothing needed to invoke correctly is missing. The label-only caveat closes the most likely source of agent error.

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%, so account_identity, auth_expires_at and mark_active are already documented in the schema; baseline is 3. The description restates mark_active's effect and the keying role of account_identity but adds no new format or edge-case detail beyond what the schema provides.

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 ('Record (or refresh) which Compass account the signed-in session belongs to, keyed by account_identity') and clarifies the write semantics of re-registration. It does not explicitly name or differentiate itself from the close sibling compass_set_active_session, even though mark_active overlaps with that tool's job, so it stops just 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?

Gives clear context for use: register or refresh the identity, and optionally fold in activation via mark_active: true rather than making a separate call. It also sets a crucial expectation ('the registry is a label only: it does not change which Compass account requests use'), which steers the agent away from misuse. It still never names compass_set_active_session or compass_get_session_context as alternatives, so there is no explicit 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?

Even though readOnlyHint and idempotentHint already cover safety, the description adds substantial non-obvious behavior: retryable statuses that are NOT misses, auth_required recovery, the three-rung WAF-routing fallback, the deliberate decision to return no URL rather than leak a wrong property, server-side fan-out, and the pending deadline. This is far beyond what annotations provide.

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 long, but proportionally so: it documents multiple return modes, retry semantics, and a fallback algorithm with no output schema available. It front-loads the core purpose and then methodically adds one behavior per sentence; every sentence earns its place and there is 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 tool with no output schema and multiple non-obvious failure modes, the description is exceptionally complete. It covers exact row shapes for resolved, no-match, timeout, bridge_down, auth_required, and pending cases; explains when to retry; and states read-only/idempotent behavior consistent with the annotations. Nothing needed to call or interpret the tool correctly is missing.

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

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

Schema coverage is 100% and the only parameter, the addresses array, is already documented with min/max item counts and an example address line. The description adds that each input produces one row and that row's query echoes the input, but it does not need to compensate for schema gaps, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: "Resolve up to 100 street addresses to Compass listing URLs in a single call." This immediately distinguishes it from the singular compass_get_by_address and other siblings, and the rest of the description elaborates on output modes rather than obscuring the core purpose.

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 gives strong usage context: it is the bulk variant, it references compass_get_by_address for the same lookup rungs, and it gives explicit retry guidance for timeout, bridge_down, pending, and auth_required rows. However, it does not explicitly say "use compass_get_by_address for single addresses" or otherwise state when-not to use this tool, so it stops just 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?

Beyond the readOnly/idempotent annotations, it discloses the ~41-listing SSR page ceiling, #87 pagination canonicalization, offset/next_offset semantics, stable pid vs sha-based URL behavior, and photo URL omission in compact view. This is deep behavioral context an agent needs to avoid false cursor loops and stale references.

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 long but every sentence earns its place: purpose is front-loaded, then critical caveats are grouped into PAGINATION, banding, return-field, and URL-stability sections. There is no filler or repetition beyond a harmless closing read-only note.

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 no output schema and a complex search with pagination and URL nuances, the description enumerates the returned fields (address, price, beds/baths, sqft, lat/lng, _lid/ and _pid/ URLs, pid) and explains the total_items/num context. An agent has enough to call it correctly and interpret results.

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 56% schema coverage, the description compensates by explaining view modes ('compact' strips image URLs), limit/offset caveats tied to #87, and the price/beds banding strategy for params that have bare schema entries. It adds actionable meaning beyond what the schema alone provides.

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 opening sentence delivers a specific verb and resource: 'Search Compass listings by location (city, ZIP, neighborhood) and optional filters.' It goes on to describe the retrieval mechanism and return payload, so an agent can distinguish this search primitive from single-property siblings like compass_get_property or compass_get_by_address.

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 gives strong operational guidance: narrow with price/beds bands to reach beyond the first SSR page, use next_offset to continue within a page, and pass view:'full' or switch to compass_get_property_photos for images. It stops short of explicitly ruling out when not to use search in favor of property-detail tools, though the names and returned URL guidance make the distinction mostly 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 say readOnlyHint=false and idempotentHint=true, but the description adds the critical behavioral fact that this state change is cosmetic: the registry is a label only and does not alter which Compass account requests use, since all calls route through the extension-signed browser tab. That is exactly the kind of context an agent cannot infer from annotations and prevents a serious misuse.

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, no filler. The action is front-loaded, the scope caveat follows immediately, and the routing explanation closes the loop. Every sentence carries distinct 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, non-destructive state tool with no output schema, the description supplies everything needed: the action, the prerequisite, the fact that the effect is bookkeeping-only, and how account switching actually works. Nothing material is missing.

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

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

Schema coverage is 100% and describes session_id as 'Session id to make active', so the baseline is 3. The description goes further by establishing that the id must reference a 'previously registered' session, which constrains valid values in a way the schema does not.

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 ('Mark a previously registered session_id as the current account label') and immediately disambiguates the scope of that action from what an agent might wrongly assume (it does not change account routing). The reader can distinguish it from compass_register_session and compass_get_session_context 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?

It names the use case ('your own bookkeeping across a conversation') and a prerequisite ('previously registered'), and gives a when-not: to actually read another account, sign that browser tab in instead. It stops short of explicitly naming register_session as the required precursor tool by name, so not quite a 5.

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