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

Goes well past the annotations (readOnly/idempotent/openWorld) by disclosing the concurrency cap of 6 in flight, per-row retry-once on transient timeouts, the overall deadline and pending-row behavior, partial-failure isolation, the error_kind taxonomy with retryable vs real-miss classification, and the envelope counts. This is unusually rich behavioral context for an agent.

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

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

Front-loaded with the core action and its limit, and every sentence carries load (return shape, failure semantics, concurrency, deadline, envelope, feature extraction, description flag, group_id default). It is a dense single block rather than organized sections, which slightly hurts scanability.

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

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

With no output schema, the description fully carries the return contract: per-row success and failure shapes, the envelope counts, pending-count semantics, and the fact that extracted_features is auto-populated. Nothing an agent needs to invoke or interpret results is missing.

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

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

Schema description coverage is 50%, and the description compensates for group_id (defaults to magic-link session context) and reinforces listing_ids batching and include_description's default. However saved_search_id is unexplained in both the schema and the description, leaving one of four parameters semantically opaque.

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

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

States a specific verb+resource with scope ('Fetch up to 200 OneHome listings in a single call') and explicitly disambiguates from the sibling onehome_compare_properties. An agent can tell it apart from onehome_get_property (single) and onehome_search_properties (query-based) without opening a schema.

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

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

Gives explicit routing ('use onehome_compare_properties for that'), a batching rule for >200 ids, and operational guidance to re-run only the ids returned as pending. It does not name the single-id alternative (onehome_get_property) for the 1-id case, so the when-not is slightly incomplete.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description adds real value by disclosing 'No network — pure local math' (no auth/network dependency) and naming the exact return shape (max price, binding constraint, PITI breakdown), which matters since there is no output schema.

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

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

Four sentences, front-loaded with the core purpose and then input/output inventory. Dense but every sentence carries information; the cohort note (@chrischall/realty-core) is arguably the weakest line but still signals consistency expectations.

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 10 params, no output schema, and only partial schema descriptions, the description does the necessary work: it names the return fields and the DTI mechanism. An agent could invoke this correctly without further context, though the sibling boundary remains slightly under-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?

Schema coverage is 60% and the description compensates well, enumerating the key inputs (monthly income, recurring debts, down payment, interest rate) and flagging the optional group (property-tax rate, insurance, HOA, loan term). It also ties the 28/36 rule to the front_end_dti/back_end_dti params, adding meaning beyond the raw schema.

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

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

States a precise verb and resource: 'Solve for the maximum home price you can afford under the standard 28/36 DTI rule.' This clearly distinguishes it from the plain mortgage-payment sibling, though it never names onehome_calculate_mortgage explicitly to sharpen the boundary.

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

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

Usage is implied by the affordability framing and the confidence-scoping note ('standard 28/36 DTI rule'), but there is no explicit when-to-use / when-not guidance and no mention of the obvious alternative (onehome_calculate_mortgage) for payment-only questions. The reader must infer the split.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=true, so the safety profile is largely covered. The description adds genuinely useful behavior beyond that: 'fully deterministic,' no network call, the automatic PMI trigger when LTV > 80%, and the 20% down-payment default. It still does not describe the response shape or rounding, but it carries good weight.

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 sentences, each earning its place, with purpose and return contents front-loaded ahead of the parameter rules. Slightly dense but 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?

There is no output schema, so the description correctly takes on the burden of describing return values (PITI breakdown and lifetime interest). For a 10-parameter deterministic calculator with annotations covering safety, this is nearly complete, missing only minor details like currency or rounding conventions.

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

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

With only 40% schema description coverage across 10 params, the description compensates well by resolving the mutually-exclusive pairs (down_payment OR down_payment_percent, property_tax_annual OR property_tax_rate) and the conditional PMI rule. It leaves hoa_monthly, insurance_annual, and loan_term_years unexplained, though those are self-evident from their names.

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 ('mortgage payment calculator') and enumerates the returned components (PITI: principal + interest, property tax, insurance, HOA, PMI, plus total interest). It does not explicitly differentiate itself from the sibling onehome_calculate_affordability, but the 'local-only payment calculator' framing is distinct enough that an agent can distinguish the two.

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

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

It gives clear context for when to reach for this tool: 'safe to use for scenario comparison without burning a fetch,' which implicitly routes the agent here instead of a network-backed sibling. It does not, however, name the alternative (e.g. calculate_affordability) or state when-not to use it.

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

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

Annotations already declare 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 readOnly, idempotent, openWorld, so the safety profile is covered. The description adds real behavioral context: contacts are withheld by default, and the return shape differs by session type (GraphQL user.groups vs a synthesized one-entry list from checkToken). This is useful disclosure 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?

Three tight sentences, front-loaded with the core purpose before the contact-omission rule and the two return modes. No filler, though the density of GraphQL/checkToken terms slightly burdens the opening read.

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

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

There is no output schema, so the description carries the return-value burden and does reasonably well by naming the two return shapes (user.groups vs one-entry synthesized list). It stops short of describing field-level contents or ordering, but for a single-optional-param read tool it is largely 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 100%, so the schema already documents include_contacts fully, including the always-returned fields. The description restates the same omission behavior ('omitted unless include_contacts: true') without adding format or default nuance, so 3 is the correct 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?

Specific verb+resource ('List the OneHome groups your agent has shared with you'), stating both the operation and its scope. It doesn't need to differentiate from siblings since none of the other tools list groups, but it also makes no attempt to position itself against them.

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

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

The description explains the two session contexts (full agent vs magic-link consumer-share) in which the tool behaves differently, which implicitly tells the agent when it applies. However, there is no explicit 'use this when / use X instead' guidance, nor any prerequisite or 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?

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 readOnly/openWorld/idempotent, so the safety profile is covered. The description adds genuinely useful behavioral detail: contacts are omitted by default, and for magic-link sessions the response is assembled from checkToken data rather than a live query, which explains degraded-field behavior an agent would otherwise find confusing.

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, front-loaded with the return shape and the contact-omission rule before the implementation paths. Dense but every sentence carries information; 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?

No output schema exists, and the description compensates by naming the returned data (profile, groups, email, contact id, group/savedSearch ids, sharing agent) and the fallback path. For a zero-required-parameter read tool, nothing an agent needs to call and interpret it 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 both parameters are already fully documented, including the view enum and the include_contacts default. The description restates include_contacts behavior (redundant with schema) but adds no new syntax or format meaning beyond it. Baseline 3 applies.

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

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

States a specific verb and resource: returns the OneHome user profile plus attached consumer-share groups. It clearly distinguishes itself from siblings like onehome_get_groups and onehome_get_session_context by centering on the signed-in user's profile.

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

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

Explains the two execution paths and when each fires: the GraphQL `user` endpoint for full agent/registered users, versus the checkToken fallback for magic-link consumer-share sessions where `user { }` is access-denied. This tells the agent what to expect by session type, though it does not name sibling alternatives explicitly.

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?

Adds substantial context beyond annotations: it discloses the default `view: compact` strips image/avatar URLs, that the return is the raw `{ data, errors, status, url }` envelope unprojected, and that mutations/subscriptions are refused. None of that is in the annotations, which only cover read-only/idempotency 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?

Dense but front-loaded: the escape-hatch framing comes first, then the view default warning, then the operation list and parameter guidance. It is long but every sentence carries information an agent needs; slightly verbose with the operation-name 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?

Despite no output schema and low schema coverage, the description covers return shape, default behavior, refusal semantics, sibling alternatives, and the parameter contract. Almost nothing an agent needs to invoke 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 only 25%, so the description compensates by explaining `view` semantics (compact vs full and what compact strips), and that `query`, `operation_name`, and `variables` are an interlocked set. It also warns operation_name must match the document. This goes well beyond the sparse 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?

States a specific verb and resource ('send a raw GraphQL document to services.onehome.com') and frames itself as a 'power-user escape hatch'. Clearly distinguishable from siblings like onehome_search_properties, which are typed operations.

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

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

Explicitly says when to use it ('pass view: full when you need the envelope byte for byte' and 'worth doing if you are here because a payload is not what you expected'), and routes users away for LocalLogic endpoints to onehome_get_schools / onehome_get_walk_score. Covers both when-to-use and 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 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?

Goes well beyond the annotations (readOnly/openWorld/idempotent). Discloses the deadline-bounded behavior, the `pending` status semantics (retry, not 'no listing'), error_kind values, the 2-rung resolution ladder, matched_via surfaced per row, and concurrency capped at 6 in-flight. This is exactly the kind of behavioral detail annotations cannot express.

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

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

Front-loaded with the core purpose and limits, but the middle is dense and repetitive: the pending/retry contract is stated twice, the ladder description is verbose, and the final 'Read-only; safe to call repeatedly' partly repeats the readOnly/idempotent annotations. Information-rich but not tight.

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 2-param bulk tool with no output schema, the description covers input shape, ordering, per-row success/failure schema, error taxonomy, deadline behavior, and resolution provenance. Missing only explicit rate-limit figures or size guidance beyond 'up to 100' and pagination across calls, which is minor.

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

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

Schema coverage is 100% and already documents every parameter, so baseline is 3. The description adds meaning beyond the schema by explaining input ordering is preserved, that group_id defaults to the magic-link session context, and the per-row error contract — context the schema alone does not carry.

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

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

Specific verb (resolve), resource (structured addresses), scope (up to 100), and output (OneHome URLs + listing OSK ids). Explicitly distinguishes from the single-row sibling `onehome_get_by_address` by noting both walk the same 2-rung ladder via a shared helper, so an agent can tell why bulk vs single exists.

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?

States clearly when to use bulk (batch address resolution, up to 100) and ties it explicitly to the single-address sibling, but never states when NOT to use it (e.g., when a single address is needed, or when group_id must be overridden). No exclusions or prerequisite 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 cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial behavior beyond them: the empty-page fallback trigger, the `fell_back_to_saved_search` marker, the deliberate error instead of silent empty, the rule that paging past the end is never swapped, defaults bootstrapped from session context, default sort, and default include_dislikes.

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

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

Front-loaded with mode selection before the fallback mechanics, and every sentence carries operative detail (fallback, error shape, projection limits). It is dense and long, but the length is buying real behavioral information rather than restating the 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?

No output schema exists, and the description compensates by describing the GraphQL listing-card projection, the absence of PublicRemarks/description, the presence of extracted_features, and the pointer to onehome_get_property for full text. An agent has everything needed to call and interpret results.

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

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

Schema coverage is only 14% with 7 params, so the description must compensate and largely does: it explains session-context defaults for group_id/saved_search_id, the include_dislikes default and semantics, the sort default and override, and empty-page behavior tied to page_num. It does not explicitly bound page_size or fully characterize sort_order, leaving minor gaps.

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

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

States a specific verb and resource ('Fetch listings inside a OneHome consumer-share') and immediately distinguishes the two operating modes by argument shape. An agent can tell this apart from onehome_get_saved_search_with_listings and onehome_get_property without opening a schema.

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

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

Explicitly says when each mode applies (saved_search_id vs group_id alone), which mode works for non-agent consumer accounts, and routes the agent to onehome_get_property(listing_id) per row when a full description is needed. Exclusions and fallback conditions are spelled out.

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?

Annotations already cover safety/idempotency (readOnly false, idempotent, non-destructive). The description adds the routing semantics that no structured field carries: which requests the active session answers and the error case when a ~MLS id matches multiple sessions. It stops short of saying whether the switch persists across calls or what it returns.

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

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

Front-loaded with the action, then rationale, then sourcing, then routing rules. Dense but each sentence earns its place; the long final sentence is a bit packed but justifies its length by explaining routing precedence and the ambiguity error.

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 switching tool with no output schema, the description covers when to use, input sourcing, and routing consequences. It leaves minor gaps (persistence and return value) but is otherwise complete enough to call correctly.

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

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

Schema coverage is 100%, so the session_id parameter is already documented. The description reinforces the two legitimate sources (set_auth response, get_session_context), but adds no format or syntax detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Force/set active) and resource (registered session), and precisely distinguishes from siblings: it is the tool that overrides MLS-suffix routing, while set_auth registers and get_session_context lists.

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 gives the trigger condition (MLS-suffix routing picks the wrong session) with three concrete examples, and states where the session_id comes from. The agent knows exactly when to reach for this over other session tools.

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.