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

Annotations already mark readOnly, idempotent, and openWorld, and the description adds substantial behavioral detail: per-row status values, ordering matching input, per-row error isolation, hard-deadline pending behavior, omitted description/agent-contact fields, and lot_size_acres null semantics. 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?

The description is long but information-dense; the main purpose is front-loaded and every subsequent sentence covers a distinct behavioral or usage point. No filler or repetition of schema 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 carries the burden of explaining return behavior, and it does: row statuses, field set, ordering, pending count, and edge cases like bad URLs and slow/hung requests. An agent has enough to call and interpret results 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 meaningful context beyond the schema: urls is passed as string[], include_description defaults to false and opts raw prose back in, and include_agent_contact controls telephone/email exposure. The view parameter is left to the schema, which already documents it well.

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

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

The description states a specific verb and resource: fetch up to 200 homes.com properties and return structured records. It also distinguishes itself from siblings by noting it mirrors homes_get_property per-row and is preferable to looping homes_compare_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?

Explicitly says to use this instead of looping homes_compare_properties when only the records are wanted, and explains why (8-item cap + redundant summary). It also frames the relationship to homes_get_property, giving an agent clear 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?

Adds non-obvious behavioral context beyond annotations: 'No network — pure local math' and identical math to zillow-mcp/redfin-mcp, plus the output breakdown. This helps the agent understand execution characteristics without contradicting the readOnly/idempotent 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?

Every sentence earns its place: a precise headline, a compact input enumeration, a clear output summary, and implementation caveats. It is concise and well-structured 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 10-parameter calculator with no output schema and no parameter descriptions, the definition under-specifies units, defaults, and custom DTI overrides. The required fields are clear, but optional inputs remain ambiguous enough to affect correct use.

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 compensate. It lists most inputs and clarifies monthly debts, but omits front_end_dti and back_end_dti, and does not specify units or default conventions for interest rate, property-tax rate, or insurance. This leaves ambiguity for correct invocation.

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?

Description states a specific operation: solving for the maximum affordable home price under the 28/36 DTI rule, with explicit outputs. It is clearly distinguishable from search/get/property tools, but it does not explicitly differentiate itself from the sibling homes_calculate_mortgage.

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 rule and outputs imply this is for affordability calculations, but there is no explicit when-to-use vs alternatives guidance. Mentioning 'Identical math to zillow-mcp and redfin-mcp' gives external context but does not compare it to internal siblings.

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 carry readOnlyHint and idempotentHint, so the bar is lower. The description adds meaningful behavioral details: no network call, 20% default down payment, automatic PMI when LTV > 80% and pmi_rate is provided, and the exact choice between annual tax and tax-rate inputs. 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?

The description is dense but efficient, with every sentence earning its place. It front-loads the core purpose, then immediately covers defaults and conditional parameters in a compact, readable structure.

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 10-parameter tool with no output schema, the description covers the output format, defaults, and conditional inputs well. It falls slightly short on edge cases: what happens if neither property tax parameter is supplied, if both down_payment and down_payment_percent are supplied, or if pmi_rate is omitted. These are minor but not explicitly addressed.

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, the description compensates strongly: it explains mutual exclusivity of down_payment/down_payment_percent, the 20% default, the property_tax_annual vs property_tax_rate choice, and the automatic PMI condition. It also clarifies that HOA and insurance are part of the breakdown, adding meaning beyond 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?

The description states a specific verb and resource: 'Local-only mortgage payment calculator. Returns a full PITI breakdown...' It clearly specifies the computed outputs and distinguishes this from sibling tools like homes_calculate_affordability by emphasizing PITI and total interest.

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 provides clear operational context with 'Local-only' and 'No network call,' and gives explicit either/or rules for down_payment and property tax inputs, plus PMI conditions. It does not explicitly name a sibling alternative such as homes_calculate_affordability, so exclusion of alternatives is implied 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 (readOnlyHint, openWorldHint, idempotentHint) cover the safety profile, and the description adds substantial behavior beyond that: per-target error isolation ('one bad target will not fail the whole call'), concurrent execution, default omission of description/agent contact, and the ~30% response-weight rationale for the opt-in summary. This is exactly the kind of non-obvious runtime behavior an agent needs before calling.

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

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

Dense but every sentence earns its place: purpose first, then input requirement, return fields, error/concurrency semantics, then the three opt-in behaviors in a logical flow. The field list and opt-in explanations would normally be redundant with an output schema, but since none exists, they carry necessary information rather than 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 and no nested objects, the description carries the full burden of explaining the return shape — and it delivers: the specific per-property fields, per-row error behavior, concurrency, and all three opt-in toggles are disclosed. The `view` parameter's response-shape semantics live in the schema (100% coverage), so nothing an agent needs to call 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%, so the baseline is 3; the description lifts it by adding cross-tool meaning for `url` (sourced from homes_search_properties) and behavioral rationale for the opt-in flags (what the 'description' prose is, which agent fields are withheld, why summary is redundant). It doesn't reach 5 because the schema already documents defaults and effects precisely, leaving the description to add context rather than essential meaning.

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

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

Opens with a specific verb+resource: 'Fetch 2 or more homes.com properties and align their facts side-by-side.' The side-by-side comparison scope plus the 2+ count requirement distinguishes it from homes_get_property (single property) and homes_bulk_get (bulk fetch without alignment), so the purpose is unambiguous.

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

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

Clear context: the tool is for comparing 2–8 properties, and the input guidance ('full homes.com property URL, e.g. from a homes_search_properties result's url field') actively routes agents to the correct sibling as the data source. However, there is no explicit when-not-to-use or named alternative for single-property lookups (homes_get_property) or bulk fetch (homes_bulk_get), so it stops short of a 5.

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

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

The description adds substantial behavioral context beyond the readOnly and idempotent annotations: it is pure local math, P&I stops at loan term end, each year reflects the buyer's net position if sold, break-even independence from the horizon, and enumerated defaults (maintenance ~1%, appreciation ~3%, rent growth ~3%, investment return 6%, horizon 7y). This gives an agent an accurate mental model of the calculation and its outputs without contradiction.

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 dense and front-loaded with the core purpose, and every sentence delivers useful information. The NOTE about monthly_rent is well-placed. It is slightly long and runs as one block of text, which could be improved with bullet points or clearer paragraph breaks, but it remains efficient for the complexity of 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?

Given the tool's complexity (15 parameters, no output schema), the description is quite complete: it explains the model, defaults, return values, and a critical external dependency. Minor gaps remain—units for rates and exact handling of omitted parameters are not stated—but overall the agent can invoke this tool correctly after reading the description.

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 0% schema coverage, the description carries the parameter-documentation burden. It names many parameters (down payment, closing costs, monthly PITI, maintenance, appreciation, rent growth, investment return) and supplies defaults. It also explicitly flags monthly_rent as required. However, it omits some parameters (hoa_monthly, selling_cost_rate, loan_term_years) and does not clarify whether rates are fractions or percentages.

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: 'Project the cumulative cost of buying a home versus renting a comparable place over N years.' It precisely defines the tool's scope and adds model details, and the mention of 'Same math contract as zillow_estimate_rent_vs_buy' plus 'No network — pure local math' clearly separates it from calculator/compare siblings like homes_calculate_mortgage and homes_compare_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?

The description gives explicit usage context: it states a hard prerequisite ('caller must supply monthly_rent'), explains why (homes.com does not publish rental estimates), and routes the agent to alternative sources for that input. It does not explicitly state when not to use this tool versus other siblings, but the prerequisite callout provides clear 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?

ReadOnlyHint, OpenWorldHint, and IdempotentHint already signal safety, and the description adds substantial behavioral context beyond those annotations: the three resolution rungs, exact return shapes, retryable timeout/blocked states, the known failure mode for rural/new construction, and the instruction to compare the returned street_address against input. Nothing contradicts the 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?

Although long, every sentence earns its place: purpose is front-loaded, followed by mechanism, parameter behavior, return contracts, retry semantics, failure modes, and batching guidance. There is no filler; the density is justified by the tool's complexity and the absence of an output 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 tool with no output schema, the description fully specifies success and error shapes, matched_via values, timeout/blocked semantics, known failure modes, and batch-size routing to a sibling. Nothing needed for correct invocation or result interpretation 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%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains that price_min/price_max bind ONLY the city/zip search-fallback rung, clarifies how the typeahead/slug rungs ignore them, and describes the unit guard and whole-token street-match verification. This extra context helps an agent decide which parameters matter for a given resolution.

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 a US street address to its canonical homes.com property URL + opaque property hash.' It clearly differentiates from siblings by naming the batch alternative ('For larger batches (≥ 3 addresses), prefer homes_resolve_addresses') and by describing the multi-rung resolution mechanism, so an agent can distinguish it from search or property-lookup tools.

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

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

It states exactly when to call this tool, when not to, and what alternative to use: 'For larger batches (≥ 3 addresses), prefer homes_resolve_addresses.' It also explains when optional parameters should be used ('when an address is ambiguous or the typeahead misses') and when they should be omitted ('Omit for unchanged unbounded behaviour').

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 reinforces safety while adding non-obvious behavior: series are empty arrays when absent, events_normalized uses a shared enum, and the response shape is spelled out. This goes well beyond what annotations alone 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?

Four dense sentences, each earning its place: purpose, replacement guidance, return shape, empty-series behavior, and safety. Key routing information is front-loaded.

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?

Complete for a single-parameter endpoint with no output schema: it names the required input, lists all returned fields, explains empty-section behavior, and covers normalization semantics. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents the single url parameter. The description adds only minor emphasis ('full property detail URL') rather than meaningful new semantics, so it stays at the high-coverage baseline.

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 it is a combined history endpoint that fetches both property and tax history in a single call, with a clear verb and resource. It explicitly names the two sibling tools it replaces, making differentiation immediate.

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 use this instead of calling homes_get_property_history plus homes_get_tax_history, and tells the caller to pass the full property detail URL. The when/why guidance is unambiguous and alternative-aware.

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?

Despite annotations already declaring readOnly/openWorld/idempotent, the description adds meaningful behavioral detail: the report is sample-based with typically ~40 recent listings and is not an exhaustive market index. It also discloses the return shape and explicitly says 'Read-only', reinforcing the 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 description is compact and front-loaded: purpose first, then parameter guidance, return shape, and a critical caveat. Every sentence carries information and none is wasted.

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

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

For a two-parameter tool with no output schema, the description is complete: it explains what the tool does, how to pass location, what the response will look like, and the important sample-size limitation. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a couple of location examples but otherwise restates what the schema already says; 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?

The description opens with a specific verb-resource pair: 'Fetch homes.com's recently-sold listings' and 'derive a market summary', which is unambiguous. The market-report aggregation purpose is clearly distinct from sibling tools like property lookup or search.

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

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

The description makes the intended use clear: pass a city/ZIP/neighborhood to get a market summary. It does not explicitly name alternatives or exclusions, so it falls short of the 'when-not-to-use' standard, but the context is strong enough to guide 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?

Annotations already provide readOnlyHint, openWorldHint, and idempotentHint, and the description adds valuable non-obvious behavior: the nearby section is a curated cross-link list, not a comparable-sales set, and only URL + address are exposed (no price/beds/baths/sqft/photo). This prevents incorrect assumptions about the data.

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 concise despite covering purpose, parameters, output shape, caveats, and follow-up guidance. It front-loads the core operation, then layers details logically, with no redundant or filler sentences.

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 provides the full return shape: { property_id, url, count, listings: [...] }. It also covers important limitations and the enrichment path, making it complete enough for an agent to select and invoke the 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 baseline is 3. The description adds a little semantic context, such as url being 'the property whose neighborhood to inspect' and the default For Sale tab behavior, but limit and include_rentals mostly restate the schema descriptions.

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

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

The description states a specific verb ('Scrape ... and return'), a precise resource (the nearby-links section of a homes.com detail page), and the expected output (nearby active listings). It clearly distinguishes this tool from siblings like homes_get_property and homes_search_properties by focusing on the curated nearby cross-link list.

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 clear context: it is for inspecting the nearby-links section of a given property page, with defaults and optional flags explained. It also explicitly points to homes_get_property for enriching rows, which is a helpful alternative cue, though it does not list explicit 'when not to use' scenarios.

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 fetch/parse mechanism (Schema.org JSON-LD plus DOM sections), defaults for description/agent contact, and important edge-case behavior (lot_size_sqft and lot_size_acres are null, never 0, for condos/no-lot listings). It also states it is read-only and safe to call repeatedly, matching the annotations without contradiction.

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 carries information: purpose, input source, returned fields, derived fields, null semantics, opt-in flags, and cost/behavior notes. It is front-loaded with the core action before enumerating details.

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, the description goes beyond a simple summary by enumerating the response surface (address, lat/lng, beds/baths, schools, price history, tax history, agent contact, etc.) and boundary conditions. The `view` parameter's compact/full behavior is covered in the schema, so the description does not need to repeat it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds extra meaning: it explains where the `url` comes from, that `extracted_features` is derived server-side to avoid keyword parsing, and that inlining history/tax saves a round trip when both are needed. It does not add new semantics for the `view` parameter, but the schema already documents that thoroughly.

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 'Fetch a property's full homes.com record' names a specific verb and resource, and the rest enumerates the returned fields so there is no confusion about scope. It also ties the input to homes_search_properties output and distinguishes inline history/tax data from the dedicated sibling tools.

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

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

The description tells the caller exactly where to get the required `url` (from a homes_search_properties result) and how to choose opt-in flags for price history and tax history instead of calling the dedicated sibling tools. It explicitly notes both flags are off by default, that opting in costs no extra page fetch, and that the tool is safely repeatable.

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 behavior. The description adds useful behavioral context: the tool returns normalized events mapped to a cross-MCP enum, will be removed in a future major version, and excludes tax history (implied by the alternative). This goes beyond the annotations without contradicting them.

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 compact and front-loaded with the most important information (deprecation and alternatives). Each sentence adds value: deprecation warning, alternative route, removal notice, return payload summary, and normalization detail.

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 naming the returned fields and the normalized enum behavior. It does not spell out the exact shape of each timeline event, but for a deprecated tool the primary need is routing to alternatives, which is fully covered.

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 single parameter `url` is already fully described in the schema as 'homes.com property detail URL or path.' The description adds no extra semantic detail about the parameter, so a baseline score of 3 is appropriate given 100% 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 description clearly identifies the tool as retrieving homes.com property history with three concrete timelines: listing_events, ownership_events, and lien_events. It also distinguishes this from siblings by naming the preferred alternatives and stating that the tool is deprecated.

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 explicitly tells the agent to prefer `homes_get_history` or `homes_get_property` with include_price_history, citing 'same data, fewer round trips.' This provides clear routing guidance and makes the usage context unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral detail: it scrapes every <img> tag and filters to the homes.com CDN, explaining the underlying mechanism and the exact return structure. This goes beyond the annotations and is fully transparent.

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 three sentences, front-loaded with the core purpose, followed by rationale and usage/return details. It is efficient without being terse, and every sentence contributes meaning.

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

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

Despite lacking an output schema, the description explicitly defines the return object structure, input requirements, and the tool's behavior. An agent has everything needed to call it correctly and interpret the result.

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 single parameter `url` is fully documented in the schema (100% coverage), and the description reinforces its usage with a concrete source (homes_search_properties result). This adds practical context beyond the schema's basic type/description.

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 clearly states the tool's purpose: retrieving the full photo gallery for a homes.com listing. It distinguishes itself by explaining the limitation of JSON-LD (only one primary image) and the scraping approach, which separates it from other property-related 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?

The description provides explicit usage guidance: pass the `url` from a homes_search_properties result. It also notes the tool is read-only and safe to call repeatedly, giving context for when to use it. It doesn't explicitly exclude alternatives, but the specificity is sufficient.

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 and idempotentHint annotations, the description reveals that the tool scrapes the favorites page, that field values are best-effort DOM extractions that may be missing, and what missing values mean. It also specifies the exact error condition for unauthenticated sessions.

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 dense but every sentence earns its place: purpose, source, return shape, auth requirement, data-quality caveats, and cross-reference to a sibling. Key operational constraints are front-loaded.

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 zero-parameter, read-only tool with no output schema, the description fully equips the agent: what it returns, what may be missing, what errors to expect, and how to get canonical records. Nothing essential is left out.

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 zero parameters, the schema leaves no parameter semantics to clarify; the baseline is 4. The description still adds useful context about implicit inputs: the signed-in user's session and browser tab.

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

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

The description states a specific verb and resource: retrieving the signed-in user's saved homes from homes.com's /customer/dashboard/favorites/. It clearly distinguishes itself from the sibling saved_searches tool and references homes_get_property as a complementary tool for canonical records.

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 explicitly states the user must be signed in, warns that the call throws SessionNotAuthenticatedError otherwise, and advises when to switch to homes_get_property per row for canonical data. This gives the agent concrete conditions for correct use versus alternatives.

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 annotations' readOnly and idempotent hints, the description discloses that the tool scrapes the saved-searches page, requires an authenticated browser session, throws a specific error when not signed in, and that missing name/filters fields are a scraping artifact rather than an absence of data. This goes well beyond the structured metadata.

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 four sentences with no wasted words. It front-loads the core purpose, then adds the endpoint, return shape, authentication caveat, missing-field semantics, and safety note. Every sentence earns its place.

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

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

For a zero-parameter, read-only tool, the description is complete: it provides the return format, the authentication prerequisite, the error case, the caveat about DOM scraping, and the fact that it can be called repeatedly. The annotations already supply safety hints, and the description fills in all agent-relevant behavior.

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

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

There are zero parameters, so the input schema has nothing to document. The description adds valuable context by specifying the return shape, `{ count, searches: [{ name?, url, filters? }] }`, but this is output information rather than parameter explanation; the zero-parameter baseline of 4 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 names a specific verb and resource: it 'gets the signed-in user's saved searches on homes.com' and specifies the exact endpoint scraped. This clearly distinguishes it from sibling tools like homes_get_saved_homes, which handles saved homes rather than saved searches.

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 clear context for use: it requires the user to be signed into homes.com in their browser tab dove altrimenti it throws SessionNotAuthenticatedError, and it is safe to call repeatedly. It does not explicitly name alternative tools or say when not to use it, so it stops short of full 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 declare readOnlyHint and idempotentHint, but the description adds meaningful context beyond those: it clarifies that the tool does not change account usage, and it explains the external dependency on the fetchproxy browser tab sign-in. This additional behavioral insight (side-effect-free nature and account routing mechanism) is exactly what the agent needs to safely invoke the tool.

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 with zero waste. The primary purpose is front-loaded, followed by the edge case and the crucial account-routing caveat. Every sentence earns its place, and the structure is immediately scannable.

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

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

For a parameterless, read-only tool with no output schema, the description is fully complete. It covers the return content, the empty-case behavior, and the operational impact on other Homes tools (account selection via browser tab). An agent can call this correctly with no further guidance.

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 input schema is trivially complete (100% coverage). The description goes beyond parameter semantics by explaining the output structure (sessions list and active_session_id, including empty/null states). Per the baseline for 0 params, a 4 is appropriate; nothing more is needed for parameters themselves.

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

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

The description uses a specific verb ('List'), names the resource ('every registered account label plus the current active_session_id'), and specifies the edge case (empty sessions, null active_session_id). This clearly differentiates it from siblings like homes_set_active_session or homes_register_session, which perform mutations. The purpose is unambiguous.

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

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

It provides clear context on when to use this tool: to view registered sessions without affecting which account is used. It explains that listings are label-only and that account selection is determined by the browser tab the fetchproxy extension is signed into, with instructions to switch tabs to change accounts. However, it does not explicitly name alternative tools or state 'when not to use', so it stops short of a 5.

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

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

Annotations already declare read-only, open-world, and idempotent hints, so the safety profile is covered. The description adds behavior beyond those hints: deprecation status, planned removal, equivalence to alternatives, and the field-name mismatch (`tax_records` vs `records`). It does not contradict the 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 deprecation warning is front-loaded so an agent immediately knows not to prefer this tool. Every sentence earns its place: alternatives, removal timeline, field-name warning, and a one-line summary of the return data. There is no filler or redundant restatement of 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 deprecated read-only tool with one fully documented parameter, the description is nearly complete: it states purpose, alternatives, deprecation, output fields, and the record-name difference. It does not give exact JSON key names for each output field, but that is a minor gap given the low complexity and strong schema coverage.

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 schema covers the only parameter, `url`, with a clear description, so the schema carries the full burden. The tool description does not add parameter-specific detail beyond mentioning `url` in the replacement call, which is not needed for understanding this tool's single parameter. Baseline 3 applies.

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

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

The description identifies the resource as 'year-by-year property-tax records' and names the exact fields returned (tax paid, total assessed value, land/improvement split). It also distinguishes this tool from siblings by naming the replacement paths (`homes_get_history`, `homes_get_property`), so an agent knows precisely what it does and how it fits in the family.

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 opens with an explicit deprecation and gives concrete alternatives: use `homes_get_history` or `homes_get_property({ include_tax_history: true })`. It explains why (same data, fewer round trips), notes the future removal, and even flags the `tax_records` vs `records` naming difference, leaving no ambiguity about when to avoid this 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?

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is known. The description adds valuable behavioral context beyond that: it explains the round-trip mechanism, lists the specific diagnostics returned (role, port, version, extension link, elapsed time, plain-English hint), and notes 'no auth required.' It also clarifies the failure-mode distinctions, which is useful for interpreting results. This goes beyond the annotations without contradicting them.

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, well-structured paragraph that front-loads the core action and then enumerates the diagnostic outputs. The first sentence establishes the purpose and the second gives the usage scenario. Every sentence adds meaningful information without redundancy. It is dense but not bloated, making it an efficient and effective description.

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

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

For a parameterless healthcheck tool with no output schema, the description provides all necessary context: it states what it does, what it returns (including a list of specific diagnostics), when to call it, and its safety (read-only, no auth). The plain-English hint distinction further clarifies possible outcomes. Nothing essential is missing for an agent to decide when and how to invoke it correctly.

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

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

The tool has zero parameters, so the baseline is 4 per the instructions. The empty input schema is fully covered (100%), and the description doesn't need to explain parameters. Since there are no parameters to describe, this dimension is inherently satisfied at the baseline level.

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 clearly states a specific action: 'Round-trips a small public www.homes.com URL (/robots.txt) through the fetchproxy bridge and returns diagnostics.' It specifies the exact resource and the diagnostic purpose, which distinguishes it from the property search, mortgage, and other home-related siblings. The verb 'round-trips' and the diagnostic focus make its function unmistakable.

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 explicitly states when to call: 'Call this when a real tool fails and you want to know which hop broke.' This gives a clear context for use. It does not, however, mention when not to use it or name specific alternative tools, but the sibling list makes it obvious this is for troubleshooting rather than normal operations. The absence of explicit alternatives is a minor gap, so a 4 is appropriate.

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 annotations (readOnlyHint=false, idempotentHint=true), the description discloses key behaviors: re-registering the same identity updates the existing entry, returning a session_id, supporting mark_active to set active in the same call, and explicitly clarifying the registry is a label only and does not affect which account requests use. This is rich, non-obvious context.

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 dense but every sentence contributes: purpose, idempotent update behavior, return value and option, relationship to actual account routing, and cross-tab sign-in context. It is front-loaded with the core purpose and contains 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 3-parameter tool with no output schema, the description provides everything an agent needs: what the tool does, the return value, the active flag, idempotency, and the crucial caveat that it doesn't switch accounts. It also clarifies the integration boundary with the fetchproxy extension context. No significant missing information.

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 schema already documents all parameters. The description adds extra meaning by explaining `account_identity` is the key for the registry and that `mark_active` can be set in the same call. It does not mention `auth_expires_at`, but the schema covers it, so this is more than adequate.

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

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

The description states a specific action (record or refresh a session registration), the resource (Homes account association with the signed-in browser tab), and the keying field `account_identity`. It also clarifies that registration is a label and does not change which account requests use, distinguishing it from siblings like homes_set_active_session.

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 explains when to use the tool: to record or refresh which Homes.com account a tab is signed into. It provides an explicit exclusion by noting the registry does not change account routing, and advises signing the tab into another account to read a different account. It does not explicitly name the alternative tool `homes_set_active_session`, but the guidance is clear enough.

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, openWorld, and idempotent hints. The description goes far beyond, detailing fan-out rungs, per-row statuses (resolved/unresolved/pending/blocked), challenge handling for HTTP 403/429, preservation of input order, and that one bad row won't fail the whole call. 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?

The description is long but information-dense: every sentence covers a distinct concern (input format, fan-out behavior, output shape, statuses, retry guidance, ordering, usage threshold, safety). It front-loads the core purpose and keeps related details grouped.

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 output contract: it specifies success/failure row shapes, matched_via enum values, status enum meanings, and error handling. It also covers input constraints, ordering, and when to use the tool, making it complete for a complex bulk operation.

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

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

Schema description coverage is 100% and already documents the addresses array shape, optional zip, and price_min/price_max semantics. The description repeats the shape briefly but adds no meaning beyond what the schema provides, so 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?

States a specific verb ('Resolve'), resource ('street addresses to canonical homes.com property URLs'), and scale ('up to 100'). It clearly distinguishes itself from sibling homes_get_by_address by being the bulk counterpart and mentions the sibling by name.

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 directs when to use this tool: 'Use this instead of looping `homes_get_by_address` for any batch ≥ 3.' Also explains fallback behavior and per-row outcomes, so an agent knows when this tool is appropriate versus alternatives.

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/openWorld annotations, the description discloses significant behavioral traits: it slugifies the location into homes.com's URL routing, parses embedded Schema.org JSON-LD, and exposes the known ~40-listing server-render cap with `truncated: true` and `total_estimated` flags. This gives the agent exactly the kind of nuance needed to anticipate result truncation and plan enumeration. It also confirms the read-only nature expectations, matching the 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 description is front-loaded with the purpose, then filters, then behavioral details. Every sentence contributes meaningful information about filtering, slugification, parsing, or the cap. It is somewhat longer than necessary—'Read-only; safe to call repeatedly' partly duplicates the annotations—but the additional structured details are dense and useful. Overall it is appropriately sized for the tool's complexity.

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 covers return values explicitly: parsed listing fields (address, price, beds/baths, sqft, primary photo, listing agent + brokerage, property URL) and the `truncated`/`total_estimated` flags. It also addresses the operational context of searching busy markets with a clear mitigation strategy. Combined with fully documented parameters and annotations, nothing critical is left for an agent to infer.

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 input schema covers all 8 parameters with descriptions, meeting the 100% coverage baseline. The tool description adds value beyond the schema by explaining that location is slugified (e.g., 'Atlanta, GA' → /atlanta-ga/condos-for-sale/), that price_min/price_max should be paired to band a busy market under the cap, and that parameters compose (property_type + listing_type). This enriches parameter understanding rather than merely repeating schema text.

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 concrete verb-plus-resource statement: 'Search homes.com listings by free-text location (city, ZIP, neighborhood).' This clearly distinguishes the tool from siblings like homes_get_property (which targets a specific listing) and homes_get_by_address (which resolves exact addresses), and it states the core mechanism. It then names the optional filters, making the purpose unambiguous.

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

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

The description conveys clear context for when to use the tool: to search listings by a free-text location with filtering options. It also gives practical usage guidance around the 40-listing cap ('price-band or sub-area your search until each segment fits under the cap'). However, it does not explicitly route agents away from the tool toward siblings like homes_get_property for specific-listing lookups, so it stops short of full when/when-not 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 declare idempotentHint=true and readOnlyHint=false, so the description's disclosure of being a label-only registry adds context without redundancy. It further explains the broader account-routing behavior through the browser tab/fetchproxy extension, which is not in the annotations and clarifies side effects.

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 compact, opens with the core action, and every sentence earns its place: the purpose, the label-only caveat, and the account-routing alternative. No filler or redundant restatement of the tool name.

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 single-parameter, no-output-schema tool, the description fully covers what the tool does, its non-effect on account selection, and the browser tab behavior needed to understand its impact. Agents have all necessary context to call it correctly without ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic meaning beyond the schema by requiring the session_id to be 'previously registered' (constraint not in the schema) and explains its role as a current label, which clarifies the parameter's purpose in the workflow.

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

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

The description uses a specific verb ('Mark') with a clear resource ('previously registered session_id') and states the purpose ('current account label... for your own bookkeeping'). It distinguishes itself from homes_register_session (which registers) and homes_get_session_context (which reads) by emphasizing the 'label only' nature, so an agent can tell them apart.

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 explicitly states when to use it ('for your own bookkeeping across a conversation'), when not to rely on it ('does not change which Homes.com account requests use'), and gives an alternative action for a different goal ('to read a different account, sign that tab into it'). This provides clear when/when-not and alternative routing.

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