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

Annotations already mark readOnlyHint, openWorldHint, and idempotentHint, and the description builds on them with valuable behavioral details: concurrent fan-out capped at 6, one retry per row for bridge timeouts, per-row error isolation, automatic extracted_features population, and description omission by default. It gives the agent a clear execution model beyond 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 dense but every sentence carries operational meaning, and the primary purpose is front-loaded in the first sentence. It covers behavior, errors, defaults, concurrency, and comparisons without filler or repetition.

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 explains the return shape: each row is either { listing_id, property } or { listing_id, error }. It also covers failure isolation, concurrency, retries, defaults, and optional output fields, so the agent has everything needed to invoke 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 description coverage is 50%, and the description compensates for include_description and group_id by explaining their defaults and effects. listing_ids constraints are in the schema, so less description is needed there. However, saved_search_id is not described in either the schema or the description, leaving a meaningful parameter unexplained.

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 up to 200 OneHome listings in a single call.' It clearly distinguishes this tool from the sibling onehome_compare_properties by noting it returns rows rather than a side-by-side summary table. No ambiguity remains about what the tool does.

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 when to use this tool (bulk fetching by id) and explicitly routes summary-table needs to onehome_compare_properties. It also tells the agent that batch-to-batch work should be split, and that single bad ids are handled per row. It does not explicitly contrast with the singular onehome_get_property, so a small exclusion gap remains.

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, covering safety. The description adds that it performs pure local math with no network, and describes outputs including the binding constraint and PITI breakdown, providing useful behavioral context beyond the schema.

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

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

The description is compact and well-structured: purpose first, then input/output summary, and a note on external equivalence. Every sentence earns its place with no redundancy.

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

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

For a 10-parameter tool with no output schema, the description gives a high-level overview but omits details like the optional DTI overrides, units for tax rate, and potential error conditions. It mentions the main output components, which helps, but it is not fully complete for correct invocation.

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 key inputs like monthly income, debts, down payment, interest rate, and optional property tax, insurance, HOA, loan term. However, it does not explain units (e.g., property tax rate as decimal vs percent) nor mention optional overrides for front/back-end DTI ratios, leaving ambiguity.

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 solves for the maximum home price under the 28/36 DTI rule, with a specific verb and resource. It distinguishes from siblings like onehome_calculate_mortgage by focusing on affordability, though it does not explicitly contrast with that sibling.

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

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

The description does not provide guidance on when to use this tool versus alternatives like onehome_calculate_mortgage. It lists inputs and outputs but lacks explicit when-to-use or when-not-to-use conditions, nor any exclusions.

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 indicate readOnly, idempotent, and not openWorld. The description adds valuable behavioral context beyond annotations: it is local-only (no network call), PMI applies automatically when LTV > 80% and pmi_rate is provided, and down_payment_percent defaults to 20%. This enriches the agent's understanding of the tool's side effects and default 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 concise and well-structured. It front-loads the primary purpose, then details the output and key parameter relationships. Every sentence adds value without redundancy or fluff.

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 calculator with 10 parameters and no output schema, the description covers the essential output (PITI breakdown and total interest), the key parameter alternatives, and the PMI rule. It does not explicitly state loan_term_years default (though the schema does) or error behavior, but the coverage is adequate for an agent to call 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?

With only 40% schema coverage, the description must compensate for undocumented parameters. It explains the down_payment/down_payment_percent alternatives, property_tax_annual/property_tax_rate options, and the default for down_payment_percent. However, it does not explicitly describe hoa_monthly or insurance_annual inputs (though they are implied by the PITI breakdown), leaving some parameters under-explained.

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: it is a local-only mortgage payment calculator that returns a full PITI breakdown and total interest. It distinguishes itself as local-only with no network call, but it does not explicitly differentiate from the sibling onehome_calculate_affordability, so it stops short of a full 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?

The description provides parameter usage rules (down_payment OR down_payment_percent, property tax alternatives, PMI condition) but does not explicitly state when to use this tool versus the affordability calculator or any other alternative. The 'local-only' and 'no network call' hints imply use for quick offline calculations, but that guidance is implicit rather than explicit.

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 details: concurrency, per-target error isolation ('one bad target will not fail the whole call'), default omission of description and summary, and the existence of opt-in flags. These are not in the annotations and meaningfully shape agent expectations.

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, front-loading the core purpose and then adding behavioral and parameter nuances. It avoids fluff and each sentence earns its place, though it is 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?

Given no output schema, the description does a solid job describing return shape (per-property record with extracted_features, rows vs summary) and error handling. Missing details include group_id semantics and the exact effect of the view parameter beyond schema, but the overall picture is comprehensive for a tool of this complexity.

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%, so the description compensates. It explains that listing_id is preferred over url, clarifies include_description and include_summary defaults, and notes that rows[] carries every fact. However, group_id and view are not explained in the description (view has schema coverage, but group_id is bare), leaving a minor gap.

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

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

The description opens with a clear, specific verb+resource: 'Fetch 2 or more OneHome listings and align their facts side-by-side.' This distinguishes it from single-listing tools like onehome_get_property and search tools, leaving no ambiguity about its function.

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 clear context on input types (listing_id preferred, url fallback) and behavior (concurrent, per-target errors), but does not explicitly state when to choose this over siblings (e.g., 'use get_property for a single listing') or when not to use it. The purpose is implied but not contrasted with 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, and the description reinforces these ('Read-only; safe to call repeatedly'). It adds significant behavioral detail beyond annotations: the two-rung ladder (suggestions then search-fallback), the output structure including 'matched_via', the non-throwing error behavior, and the bounded search pool by groupId. This goes well beyond the 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?

The description is dense but well-organized, front-loading the core purpose and then logically detailing the mechanism, output, error case, and safety. It is longer than necessary but every sentence adds information—no fluff or redundancy. The structure aids comprehension, so it earns a 4 rather than a 5 due to slight length.

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 lack of an output schema, the description fully specifies the return shape ({url, listing_id, address, resolved, matched_via}) and the error case. It also explains the fallback algorithm and scoping. The input parameters are well-documented in the schema, and the description clarifies behavioral nuances like the 'view' enum. No critical information for correct invocation is missing, though rate limits or auth requirements are not mentioned (annotations do not cover them either).

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 each parameter (address, zip, city, state, group_id, view) already has a clear description. The description adds context about how group_id scopes the suggestion search and the fallback pool, and clarifies the 'view' parameter's impact on response shape. This adds some semantic value beyond the schema, but the schema already carries the primary meanings, so a baseline of 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 clearly states the tool resolves a free-text street address to a OneHome listing's canonical portal URL and id, with a specific verb ('Resolve') and resource ('OneHome listing'). It describes the output and the two-step mechanism, making the purpose unambiguous. However, it does not explicitly contrast with the similar sibling 'onehome_resolve_addresses', which might handle bulk or different scenarios, so differentiation is only implicit.

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

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

The description implies usage for a single address resolution and explains the fallback ladder, but it does not explicitly state when to prefer this tool over alternatives like 'onehome_resolve_addresses' or when not to use it. The context of being a one-call single-address resolver is present but without explicit exclusions or alternative 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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral detail beyond this: for registered users it returns the GraphQL user.groups list, while for magic-link sessions it synthesizes a single-entry list from the checkToken context. This clarifies conditional behavior without contradicting 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?

Two tightly written sentences, front-loaded with the core purpose and followed by the conditional detail. No wasted words or repetition of the title or schema.

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

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

For a zero-parameter, read-only list tool, this describes both supported session modes and the expected shape of the return (a groups list, or a synthesized one-entry list). Nothing essential is missing for an agent to decide whether to call it and what result to expect.

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 no parameters, so the input schema carries no semantic burden. The description still adds value by explaining what data source is used in each session mode. With zero parameters, the 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 uses a specific verb ('List') and resource ('OneHome groups your agent has shared with you'), making the purpose immediately clear. It also distinguishes the two session contexts (full agent/registered users vs magic-link consumer-share), which prevents confusion about what 'groups' means.

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 indicates when this tool is appropriate: whenever you need the OneHome groups available to the agent. It gives conditional behavior for different session types, but does not explicitly compare against sibling tools or state when not to use it; however, the context is clear enough for a parameterless list 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?

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds meaningful behavioral detail: the raw description is omitted by default and requires include_description; extracted_features is keyword-parsed from the description; lot_size_acres is derived and null for condos/lotless listings; and group_id defaults to magic-link session context. These are non-obvious behaviors an agent needs to know before calling.

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

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

The description is long but every sentence earns its place: purpose, returned fields, default behavior, and scoping semantics are all packed in without padding. Important caveats are front-loaded after the core purpose, and the parameter-specific guidance is clearly separated from the return-value enumeration.

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 well by enumerating the main returned fields and clarifying key behaviors like description omission and lot_size conversion. The main completeness gap is the unexplained saved_search_id parameter and the lack of explicit guidance on which selector parameter(s) should be provided when none are required by the schema.

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

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

Schema description coverage is only 20%, so the description carries most of the parameter burden. It explains url/portal URL, group_id defaults, and include_description behavior well. However, it does not explicitly explain listing_id or saved_search_id, and 'by id' is ambiguous about which parameter is the primary id. This leaves meaningful gaps for two of five parameters.

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 'Fetch full details for a single OneHome listing by id or portal URL,' which names a specific verb, resource, and selection method. It also distinguishes itself from sibling tools like onehome_search_properties, onehome_get_property_photos, and onehome_bulk_get by emphasizing 'single listing' and 'full details.' The extensive field listing reinforces exactly what 'full details' means.

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 usage context: use by id or portal URL, pass include_description only when raw text is needed, and pass group_id explicitly only when querying a different group from the magic-link session. It does not explicitly name sibling tools as alternatives or state when not to use this tool, 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 readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is clear. The description adds behavior beyond annotations by specifying the per-image structure (CDN URLs, dimensions, LongDescription, display order) and that it returns one entry per image.

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

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

Two sentences, no filler; the purpose is front-loaded and the return format and input alternatives are stated efficiently. 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 tool with no output schema and 0% parameter coverage, the description leaves a significant gap around group_id and does not discuss behavior when multiple identifiers are passed or any error/empty cases. It gives useful return fields but is not complete enough for an agent to call correctly in all situations.

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 must explain the parameters, but it only mentions passing 'listing_id or a portal URL' and ignores the group_id parameter entirely. It also does not clarify how the three parameters relate or what group_id is for.

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 full media gallery for a OneHome listing') and clearly distinguishes this tool from siblings like onehome_get_property by focusing on the photo gallery. The return details reinforce the gallery scope.

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 says what the tool does but provides no guidance on when to choose it over sibling tools or when not to use it. The only usage hint is which identifier to pass, not the tool-selection context.

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, so the description adds value by disclosing the session-context default for saved_search_id and the conditional suppression of listing_ids. This is meaningful behavioral context beyond what the annotations express, though it does not discuss edge cases like not-found behavior or authentication requirements.

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 core action and resource. Every sentence adds distinct value: identity, return shape, parameter behavior, variant differentiation, and defaulting behavior. No filler or redundant restatement of the title is present.

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-optional-parameter read-only fetch with no output schema, the description covers the essential return fields, both parameters, the session-context default, and the tool's canonical position among variants. An agent has enough information to select and invoke the tool correctly without additional context.

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

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

Schema description coverage is 0%, so the description carries full weight for both parameters. It explains that saved_search_id is a UUID and defaults to session context when omitted, and that include_listing_ids: false suppresses the listing-id array for metadata-only callers. This fully compensates for the bare 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 agent-curated saved search by its id'), and immediately distinguishes this tool from related variants by noting it is the canonical consumer-readable endpoint and that the by-groupId variant is agent-only. It also clearly enumerates the returned data, so an agent can predict what this tool produces without ambiguity.

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 usage context: it identifies this as the canonical consumer-readable endpoint, notes the agent-only by-groupId variant, and tells the agent to pass include_listing_ids: false when only metadata is needed. It does not explicitly route around the closely named sibling onehome_get_saved_search_with_listings, but the parameter guidance and endpoint classification are strong enough for most routing decisions.

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, and the description adds substantial behavior beyond that: it runs two internal operations, returns a specific shape ({ saved_search, listings, count, page_info }), inherits defaults from magic-link session context, defaults sorting to Newest, and warns that PublicRemarks is absent from the listing-card projection. 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 dense, with the core purpose front-loaded and each sentence adding distinct value. Some phrasing is implementation-heavy (GraphQL projection, buildGetSavedListings), but this is useful context for an MCP agent. Slightly verbose, yet not 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?

Given a complex combo tool with no output schema and low parameter coverage, the description covers the essential call path: purpose, return shape, defaulting behavior, sort default, and the key data limitation. The main gap is lack of guidance on pagination parameters and include_dislikes, but the core invocation is well specified.

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 only 14% of parameters with descriptions, so the description must compensate. It does clarify saved_search_id/group_id defaults and sort_field/sort_order behavior, but page_num, page_size, and include_dislikes remain semantically unexplained. Partial compensation 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?

The description states a specific composite verb-object pair: it fetches a saved search and inflates its listings in a single trip. It clearly distinguishes itself from siblings by naming the exact two-call sequence it replaces (onehome_get_saved_search followed by onehome_search_properties), so an agent can tell it apart 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?

It explicitly identifies the intended consumer flow ('magic-link-to-listings'), contrasts itself with the two-call alternative, and gives a concrete when-not-to-use rule: call onehome_get_property(listing_id) per row when the full listing description is needed. This is actionable usage guidance, not just a statement of function.

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 critical behavioral context: an error field with HTTP details when access is denied, the endpoint being sometimes agent-only, and the response structure. This goes beyond what annotations provide and is highly 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, and includes essential context (error handling, source of lat/lng). It is efficient without unnecessary 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 adequately describes the return structure (lists, attributes, proximity) and error behavior. However, it omits explanation of the optional 'language' parameter and leaves 'attributes' vague. For a tool with 3 parameters and no output schema, this is moderately complete but not fully.

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

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

Schema coverage is 0%, so the description must compensate. It explains lat/lng as coordinates and mentions they usually come from onehome_get_property, but does not describe units, ranges, or the optional 'language' parameter at all. This leaves significant gaps in parameter understanding.

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 verb 'Fetch' and the resource 'Local-Logic school data for a coordinate', and specifies the output structure (separate primary and high-school lists with name, attributes, and proximity). It differentiates from siblings by noting the lat/lng source from onehome_get_property, establishing a distinct workflow.

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 context on typical input (lat/lng from onehome_get_property) but does not explicitly state when to use this tool over alternatives like onehome_get_walk_score or search tools. It implies usage but lacks clear when-to-use and when-not-to-use 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 provide readOnlyHint and idempotentHint, so the description doesn't need to re-state that. It adds value by explaining the semantics of active_session_id and the defaulting behavior of other tools, plus the error behavior for multiple matches. This goes beyond the structured annotations, though it could mention that it doesn't mutate state explicitly, but the annotations already cover that.

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 dense paragraph that packs a lot of information, but it remains concise and relevant. It front-loads the purpose, then explains routing and default behavior. While it is longer than strictly necessary, every sentence contributes to understanding the tool's behavior.

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

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

For a tool with no parameters and no output schema, the description thoroughly explains what the output will contain (session_id, auth_mode, token expiry, session scope, active_session_id), how the output is to be interpreted (routing and defaults), and the common use case. Nothing essential is missing for an agent 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 schema has zero parameters, and the description clearly states that no input is required. Since there are no parameters to document, the description appropriately focuses on the output semantics, which meets the baseline for a parameterless tool.

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 that the tool returns one entry per registered session with a specific set of fields, and it differentiates from siblings by explaining its role in session inspection and default resolution. The verb 'returns' and resource 'registered session' are specific and 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 explicitly says when to use it (to see defaults and session context, especially for single-session use) and when not to use it (when there are several matches, it errors and directs to use onehome_set_active_session). It also explains the routing behavior and the common case, providing clear usage 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, so the safety profile is covered. The description adds valuable behavioral context: the fallback mechanism for magic-link sessions and the reason (user {} access-denied). This goes beyond annotations and clarifies what data is returned in the fallback.

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

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

Two sentences, front-loaded with the core purpose, then a concise explanation of the fallback. No wasted words; every sentence adds information.

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

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

For a read-only getter with no output schema, the description explains both execution paths and lists the key fields returned in the fallback. It lacks explicit error behavior or auth requirements, but annotations cover the safety profile. Complete enough for a single-parameter read tool.

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

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

Schema description coverage is 100%, so the single 'view' parameter is fully documented in the schema. The description does not add extra semantics, but the schema suffices. Baseline 3 applies because the schema carries the burden.

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 it returns the OneHome user profile plus consumer-share groups, which is specific and not a tautology. It distinguishes the tool's scope (user profile) from siblings like onehome_get_groups, though it doesn't name them explicitly.

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

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

No guidance on when to use this tool versus alternatives. It explains two execution modes (full agent vs magic-link) but does not state when to prefer this over onehome_get_session_context or other siblings. The agent must infer usage from the resource name.

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 and idempotent behavior. The description adds useful context about the error field (HTTP details when upstream rejects) and the score value/text structure, which goes beyond what annotations declare.

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

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

Two sentences, no filler, with the core purpose front-loaded and return details following. Every sentence adds value and the structure is clean.

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 there is no output schema, the description explains the score pair format and error field, which covers the main return expectations. It does not mention language defaults or the overall response envelope, but for a read-only getter with annotations, it is nearly complete.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not. It never explains what `lat`, `lng`, or `language` mean or how they affect the result. It only says 'for a coordinate,' which vaguely implies lat/lng but leaves language entirely undefined. For a tool with zero schema help, this is a critical gap.

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

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

The description states a specific resource ('Local-Logic location scores') and the exact kind of data returned (pedestrian/car/cycling/transit friendliness plus proximity summaries). It clearly distinguishes itself from sibling tools like get_property or get_schools, which focus on other data types.

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 it obvious this is for location scores near a coordinate, providing clear context for when to call it. However, it does not explicitly mention alternatives or situations where it should not be used, so it lacks the exclusion guidance that would earn 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 goes well beyond annotations by disclosing that the response is the whole `{ data, errors, status, url }` envelope, that `view: compact` strips image/avatar URLs, that `view: 'full'` returns the payload byte-for-byte, and that mutation/subscription documents are refused. This aligns with the readOnlyHint instead of contradicting it.

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 key 'escape hatch' framing, with all major caveats covered. It is somewhat long and uses heavy parentheticals, but every sentence adds substantive information the schema and annotations do not provide.

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 fully covers the return envelope, response projection behavior, required inputs, common operations, restrictions, and sibling-tool alternatives. Nothing needed to call the tool correctly is left unaddressed.

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

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

Schema description coverage is only 25%, but the description compensates by explaining all four parameters: the full query document body, a matching operation name, variables as JSON, and the view option's behavioral impact. It also lists common operation names, which gives concrete semantic grounding for the `operation_name` field.

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 ('send a raw GraphQL document') with a named endpoint ('services.onehome.com'), and frames itself as a power-user escape hatch. It distinguishes itself from sibling REST-based tools by explicitly noting that schools and walk-score are separate REST endpoints.

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?

Provides clear context for when to use the tool — raw GraphQL needs with variables and full unprojected responses — and explicitly says which sibling tools to use instead for schools and walk-score. It stops short of a comprehensive when-to-use matrix against every sibling, so it is strong but not exhaustive.

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

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

Annotations declare readOnlyHint, openWorldHint, and idempotentHint, already indicating safety and non-mutating behavior. The description adds value by disclosing that it returns auth mode, token expiry, bridge role, elapsed time, and error detail, which is beyond the annotations. It also hints at the mechanism (round-trip) and its diagnostic role, covering key behavioral aspects without contradicting 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 a compact paragraph that front-loads the core action, then explains the query selection logic, output information, and usage guidance. Every sentence adds value, with no fluff or redundancy, and it reads naturally as a cohesive, informative unit.

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 has no parameters and no output schema, the description fully covers what an agent needs: what it does, which queries it uses, what it returns, and when to use it. There are no gaps in operational knowledge for an agent to call it correctly, as it is a parameterless action.

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 no parameters, and with 0 parameters, the description naturally cannot add parameter-specific detail. The baseline for zero parameters is 4, and the description does explain the operational context (which queries are used, what it returns), which compensates for the lack of parameters. Since schema coverage is 100% and there are no params, the description's contextual detail earns a 4.

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

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

The description clearly states the tool's purpose: to round-trip a minimal authenticated query through the transport, verifying auth and GraphQL reachability. It specifies the exact queries used and the distinction between consumer-share vs agent sessions, which distinguishes it from sibling tools that fetch specific 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?

It explicitly instructs to run this tool first when another tool fails, and explains that it isolates the question of whether auth is wired up from actual API misbehavior. This provides clear when-to-use guidance and contextual reasoning, though it doesn't mention alternatives directly, it's clear this is a diagnostic step.

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 annotations already declare readOnlyHint, openWorldHint, and idempotentHint, the description adds substantial context beyond them: output order preservation, per-row error isolation ('one bad address never fails the whole batch'), the two-rung resolution algorithm, the matched_via field, and a concurrency cap of 6. The closing 'Read-only; safe to call repeatedly' merely restates the annotations and does not contradict 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 front-loaded with its core purpose and every sentence carries a distinct fact: batch cap, input/output shapes, ordering, error isolation, resolution ladder, concurrency limit, and defaults. It earns its length, but it is slightly dense with internal jargon (rung names, 'raw-listings pool'), so a small trim would make it crisper.

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 takes on the burden of documenting the return shape, spelling out both the resolved row `{resolved: true, url, listing_id, address}` and the failure row `{resolved: false, error, query}`. Combined with 100% parameter coverage and disclosure of ordering, error isolation, concurrency, defaults, and read-only behavior, an agent has everything needed to invoke this 2-param 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 coverage is 100%, setting the baseline at 3, but the description goes further by explaining the input object shape `{address, city?, state?, zip?}` and the group_id default to the magic-link session context plus its role in bounding the search-fallback pool. This adds behavioral meaning to group_id that the schema's own description does not convey.

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

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

The opening sentence names a specific verb and resource: 'Resolve up to 100 structured addresses to OneHome canonical portal URLs + listing OSK ids in one call.' It explicitly distinguishes itself from sibling onehome_get_by_address by calling out that both walk the same 2-rung ladder and 'cannot diverge,' so an agent can immediately tell the bulk tool apart from the single-address 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 positions this as the bulk counterpart of onehome_get_by_address, and the schema notes 'for higher counts, batch into multiple calls,' giving a concrete usage rule. However, it never explicitly states when NOT to use this tool or how it differs from other bulk tools like onehome_bulk_get, so it stops just 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?

Goes far beyond the readOnly/idempotent annotations by disclosing fallback behavior, the exact fallback condition, error-raising when no fallback exists, session-context defaults, sort defaults, include_dislikes default, and the GraphQL projection limitation with no PublicRemarks/description field. This is rich behavioral context an agent needs.

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 densely informative with no filler. The mode breakdown is front-loaded, followed by defaults, fallback behavior, and output limitations. Every sentence earns its place given 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?

Given 7 parameters, no output schema, and complex fallback logic, the description covers the essential invocation semantics, result projection, and limitations, and routes to onehome_get_property for full descriptions. It doesn't detail pagination behavior or the exact response envelope, but the missing pieces are comparatively minor and partially inferable from the schema.

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

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

With schema coverage at only 14%, the description compensates well by explaining group_id vs saved_search_id semantics, session-context defaults, include_dislikes default, and sort defaults tied to sort_field/sort_order. However, page_num, page_size, and sort_order behavior are not explicitly described, so it doesn't fully cover all parameters.

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 action ('Fetch listings') on a specific resource ('a OneHome consumer-share') and immediately distinguishes its two operating modes. It differentiates from sibling tools by clarifying the consumer-share context and explicitly directing the agent to onehome_get_property when full descriptions are needed.

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?

Provides strong mode-selection guidance: saved_search_id mode is called 'the only mode that works for non-agent consumer accounts', and the fallback condition for the raw endpoint is described precisely. It also tells the agent when to use onehome_get_property instead. It doesn't explicitly contrast with nearby sibling search tools like onehome_get_saved_search_with_listings, but the operational guidance is 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 readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context: it lists exact return fields (id, address parts, beds/baths, list price, thumbnail), explains the global endpoint behavior that bypasses groups, and clarifies the effect of the optional group_id scope. 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, with the primary purpose front-loaded in the first sentence, followed by the use case, return fields, follow-up hint, and parameter explanation. Every sentence contributes distinct information with no filler or repetition.

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

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

For a simple two-parameter search tool with no output schema, the description covers the purpose, the expected return format, the scoping behavior, and the recommended follow-up. No essential detail is missing for an agent 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?

With schema description coverage at 0%, the description carries full responsibility for parameter meaning. It explains query as 'address, MLS number, or partial query' and group_id as scoping to 'one OneHome market'. Both parameters receive clear, non-redundant explanations that exceed what the bare 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?

The description opens with a specific verb and resource: 'Cross-feed suggestion search' and then enumerates the accepted search keys (address, MLS number, partial query). It explicitly states it bypasses the group/saved-search structure and hits a global endpoint, which distinguishes it from sibling search tools like onehome_search_properties or onehome_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 concrete use cases ('find an address', 'look up by MLS number') and explains that it bypasses group/saved-search structure, implying when it is preferable to structured search. It also advises a follow-up action (inflate with onehome_get_property). However, it does not explicitly name alternative search tools or state when not to use it, so it stops short of a full when/when-not guide.

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 (destructiveHint=true, idempotentHint=true), the description discloses the operational semantics of 'active' — the active session answers all non-`~MLS` requests and any `~MLS` request matching its own MLS, while ambiguous `~MLS` ids error until selection. This routing behavior is exactly the kind of context annotations cannot convey. 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?

Three sentences, each earning its place: purpose, when-to-use with examples, and behavioral consequences. The main verb is front-loaded. It is slightly longer than strictly necessary, but the density of routing semantics justifies the length.

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 state-switching tool, the description covers the prerequisite (session must already be registered), the failure modes it addresses, where to obtain the session_id, and the post-condition routing rules. It omits the success response format, but with no output schema and low complexity, this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents that session_id comes from `onehome_set_auth` responses or `onehome_get_session_context` listings. The description restates nearly the same provenance information, adding no new syntax, format, or lifecycle detail. Baseline 3 is appropriate since the schema carries the load.

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-resource pair ('Force a specific registered session to be the active one') and then differentiates itself from siblings by explaining the routing mechanism that makes it distinct from onehome_set_auth (which registers) and onehome_get_session_context (which inspects). An agent can tell exactly what state change this tool performs.

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 trigger conditions ('Useful when MLS-suffix routing picks the wrong session') with three concrete examples: two shares in the same MLS, free-text search across MLSes, and a listing without a `~MLS` suffix. It also describes the error case this tool resolves. It does not explicitly state when not to use it or name a direct alternative, so it stops just 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 detail beyond the annotations: input-shape detection rules, registration of a new direct-bearer transport, activation behavior, preservation of previous sessions, response fields, fingerprint format, and a security warning about chat-history exposure. It clearly sets expectations for 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 long but appropriately so for a security-sensitive, multi-format auth tool. It is front-loaded with the core action, then uses compact, technical structure and a distinct SECURITY section. No sentence is filler.

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

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

With no output schema, the description's enumeration of response contents is essential and sufficient. It covers input formats, processing behavior, session lifecycle, routing alternatives, response details, and security caveats, making it complete for an agent to 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?

The schema already describes the three accepted input forms, but the description goes further by specifying exactly how each form is resolved: URL extracts ?token=, 3-segment JWT is used directly, and otherwise it is exchanged via /api/authentication/checkToken. This materially improves 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?

The description clearly states the tool's purpose: adding another authenticated OneHome session at runtime via magic-link URL, JWT, or email-token. It differentiates itself from onehome_set_active_session, which switches among already-registered sessions, so an agent can distinguish them immediately.

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

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

It provides an explicit use case (buyer spans multiple agents/MLSes) and names the alternative behavior: switching back via onehome_set_active_session or relying on MLS-suffix routing. This gives an agent clear when-to-use and when-to-prefer-another-tool guidance.

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