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

Adds significant behavioral details beyond annotations: concurrent fan-out with cap of 6, retry policy for timeouts, per-row error handling, default omission of `description`, and default `group_id` from session. No contradictions with readOnlyHint/idempotentHint.

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 main purpose, each sentence adds value. Slightly verbose in detailing concurrency and retry, but all information is relevant.

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?

Explains return format (rows with success/error), concurrency limits, and default behavior. No output schema, but description provides sufficient detail. Missing specifics on `saved_search_id` and `group_id` fallback, but overall complete for core functionality.

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?

Adds context for `listing_ids` (batch size constraint reiterated), explains `include_description` default and effect, and `group_id` default behavior. Schema coverage is 50% but description compensates for some gaps. `saved_search_id` lacks extra clarification.

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?

Describes specific verb+resource (fetch listings by id), distinguishes from sibling `onehome_compare_properties` by clarifying it returns rows per id instead of a side-by-side summary.

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 contrasts with `onehome_compare_properties` for side-by-side needs, and advises batching for more than 200 ids. No explicit exclusion of other alternatives, but context 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 include readOnlyHint=true, idempotentHint=true, openWorldHint=false. The description reinforces this by stating 'No network — pure local math,' and discloses the DTI rule. No contradictions.

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 (four sentences) and front-loaded with the purpose. Every sentence adds value without 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?

The description covers inputs and outputs adequately for a straightforward calculator. It mentions the output includes 'max home price, binding constraint, and PITI breakdown.' However, it does not specify default DTI values or behavior for optional parameters, which would enhance completeness.

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 inputs like 'monthly income, recurring monthly debts, down payment, interest rate, optional property-tax rate / insurance / HOA / loan term' but does not detail each parameter's meaning or defaults (e.g., front_end_dti, back_end_dti). The 28/36 rule implies defaults, but explicit mapping would improve clarity.

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: 'Solve for the maximum home price you can afford under the standard 28/36 DTI rule.' It lists inputs and outputs, and distinguishes from siblings like onehome_calculate_mortgage by specifying the DTI rule and local math.

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

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

The description explicitly states 'No network — pure local math,' clarifying it's a local calculation. It also notes 'Same math as zillow-mcp / redfin-mcp / compass-mcp / homes-mcp,' providing context for when to use. However, it does not explicitly exclude alternatives or provide 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 indicate readOnlyHint and idempotentHint true, confirming no side effects. The description adds beyond these by stating it is local-only (no network call) and explaining PMI auto-application when LTV > 80% if pmi_rate is provided. 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 a single paragraph of three sentences. The first sentence establishes the overall purpose, and the remaining sentences provide key parameter semantics. Every sentence adds value, with no extraneous content.

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 10 parameters, 2 required, and no output schema, the description covers the main functionality, defaults, and parameter relationships. It misses mentioning that loan_term_years defaults to 30 (though schema states that) and could detail the exact output fields, but the core information is present.

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

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

Schema description coverage is only 40%, so the description must compensate. It does so effectively: explains mutual exclusivity of down_payment and down_payment_percent with default 20%, property tax alternatives, and PMI condition. This adds critical meaning beyond the schema's minimal descriptions.

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

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

The description clearly states the tool is a local-only mortgage payment calculator returning a full PITI breakdown and total interest. The verb 'calculate' and resource 'mortgage PITI' are specific. None of the sibling tools perform this exact function, so it is well-distinguished.

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

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

The description provides explicit guidance: it is local-only (no network call), and specifies that down_payment or down_payment_percent must be provided (with default 20%), and property tax can be given as annual or rate. It implicitly advises when to use this tool (for mortgage calculations) and clarifies parameter alternatives, though it does not explicitly state when not to use.

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 the readOnlyHint/openWorldHint/idempotentHint annotations: it discloses concurrency, per-row error containment, default omission of description and summary, the redundant ~30% summary weight, and the compact/full view caveat. This is rich, honest behavioral context.

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

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

The description is dense but efficient: every sentence adds operational value, with the core purpose first and important defaults and caveats clearly laid out. No filler or repetition of structured fields.

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

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

The description thoroughly covers response rows, errors, defaults, and view behavior, but it does not explain saved_search_id or group_id at all, and there is no output schema to compensate. This leaves gaps an agent must resolve by guessing.

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 description adds meaningful semantics for include_description, include_summary, view, and the preferred target identifier (listing_id vs url). However, it omits saved_search_id and group_id, both of which appear in the schema without their own descriptions, so coverage is incomplete.

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 2 or more OneHome listings and align their facts side-by-side.' This clearly distinguishes the tool from single-listing fetchers like onehome_get_property and search tools like onehome_search_properties.

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

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

The description conveys a clear use case — comparing multiple OneHome listings — and explains target selection via listing_id or url. However, it does not explicitly state when to prefer this tool over siblings such as onehome_bulk_get or onehome_get_property, nor does it give 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the two-rung lookup algorithm (ListingSuggestionsSearch then search-fallback), the bounded groupId pool, the matched_via output values, and the no-throw 'no listing found' behavior. This gives the agent an unusually complete picture of how the call behaves.

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 front-loads purpose and then compactly covers algorithm, return shape, error behavior, and safety. Every clause adds operational information; there is no filler or redundant restating of the tool name.

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

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

With no output schema, the description fully specifies the return object including url, listing_id, address, resolved, and matched_via, plus the failure response. Combined with 100% parameter coverage and read-only/idempotent annotations, the agent has everything needed to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, and the schema already explains zip, city, state, address, view, and group_id well. The tool description adds meaning beyond the schema by clarifying that group_id bounds both the suggestion search and the fallback page-walk, which the schema only attributes to the suggestion search.

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

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

The first sentence clearly names the verb 'Resolve', the resource 'a OneHome listing', and the outputs 'canonical portal URL and id', so there is no tautology. It distinguishes this from search/property tools by focusing on free-text street address resolution, but it does not explicitly differentiate itself from the sibling onehome_resolve_addresses.

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 the tool: resolving a free-text street address with optional city/state/zip to a listing URL and id in one call. It does not explicitly state when not to use it or name alternatives such as onehome_resolve_addresses or onehome_search_suggestions, so exclusion guidance is missing.

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 annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds specific behavioral details: it returns GraphQL list for full agents and synthesizes a one-entry list for magic-link sessions using checkToken context. This is rich transparency.

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 wasted words. The first sentence states the primary purpose, the second explains variants. It is front-loaded and concise.

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

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

Given the tool has no parameters and no output schema, the description fully covers the behavior for both user types. It is complete for a simple listing 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?

With 0 parameters and 100% schema coverage, the baseline is 4. The description does not add parameter-specific information but explains different behaviors, which is appropriate 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 it lists OneHome groups the agent has shared. It uses a specific verb 'list' and resource 'groups', and distinguishes between full agent/registered users and magic-link consumer-share sessions, providing precise context.

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 when the tool behaves differently based on user type (full agent vs magic-link), which implicitly guides usage. However, it does not explicitly state when not to use this tool or mention alternatives among siblings.

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

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

Description adds significant behavioral context beyond annotations: defaults for group_id and include_description, extracted_features processing, lot_size handling (null for condos), raw description omission. Annotations (readOnlyHint, idempotentHint, openWorldHint) are consistent and complemented.

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?

Single dense paragraph that packs a lot of info. Could be more structured (bullets) but every sentence adds value; front-loaded with purpose.

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?

Highly complete: no output schema, but description details return fields comprehensively. Covers all 5 parameters, defaults, edge cases (lot_size null for condos), and behavioral notes. Agent can invoke 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?

Only 20% schema coverage, but description explains all 5 parameters: url/listing_id as identifier options, group_id session default, include_description default false with rationale, saved_search_id implied. Adds meaning far beyond 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?

Description clearly states it fetches full details for a single OneHome listing by id or portal URL, listing many specific fields returned. It is distinguished from siblings like onehome_get_by_address and onehome_search_properties.

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

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

Provides clear context on when to use (fetch details by id/URL) and defaults (group_id to session, include_description false). Lacks explicit when-not-to-use and alternative sibling references, but the purpose is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by detailing the response structure and that it returns one entry per image, but does not introduce additional behavioral traits beyond 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 two concise sentences. The first sentence states purpose and output, the second gives parameter guidance. No wasted words, front-loaded with key 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?

The description explains the return values adequately, but omits the group_id parameter entirely. Given no output schema and moderate tool complexity, the description is adequate but has a clear 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 0%, so the description carries full burden. It explains that listing_id is an ID and url is a portal URL, but fails to mention group_id, leaving one of three parameters undocumented.

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 fetches the full media gallery for a OneHome listing, specifying the return format with CDN URLs, dimensions, and description. It distinguishes from sibling tools (e.g., onehome_get_property) by focusing solely on photos.

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 advises to pass either listing_id or a portal URL, providing clear context on when to use the tool. However, it does not explicitly state when not to use it or mention any prerequisites, though no alternatives exist among siblings.

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

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

Annotations already provide readOnlyHint, openWorldHint, and idempotentHint. The description adds value by detailing the returned fields (name, filters, polygon, listing count, listing_ids), the effect of the 'include_listing_ids' parameter, and the session-context default for saved_search_id. This goes 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 extremely concise with 3-4 sentences, all relevant and front-loaded. There is no redundant information; every sentence adds value: main action, return fields, parameter usage, and endpoint context.

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, the description sufficiently lists the returned fields. It covers both optional parameters and their effects. It could be more complete by mentioning error behavior or the exact shape of nested objects like 'filters' and 'polygon', but for a simple read tool this is quite comprehensive.

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 description coverage, the description fully explains both parameters: 'include_listing_ids' (suppress listing-id array to get only metadata) and 'saved_search_id' (defaults to MCP's session context). This is excellent compensation for the lack of schema documentation.

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 uses the verb 'Fetch' and specifies the resource as 'agent-curated saved search by its id'. It distinguishes from the sibling 'onehome_get_saved_search_with_listings' by noting that this is the 'canonical consumer-readable endpoint' and the by-groupId variant is agent-only, though it could be more explicit about the difference between these tools.

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

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

The description provides guidance on when to use this tool (consumer-readable) vs. the agent-only variant (by-groupId). It also explains the optional parameter 'include_listing_ids' and the default behavior for 'saved_search_id'. It would benefit from explicitly stating when not to use this tool or when to use the sibling.

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?

Discloses internal operations (two internal calls), default values (group_id, saved_search_id from session context, sort default), and limitations (no PublicRemarks). 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?

Concise at ~150 words, front-loaded with the key purpose. Each sentence provides essential information without 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?

Covers purpose, usage, behavior, return structure, and limitations. Lacks details on pagination behavior or error handling, but overall adequate given the tools 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?

Adds meaning for group_id, saved_search_id (defaults), and sort_field (default). But other parameters like page_num, page_size, sort_order, include_dislikes are not described beyond the schema. Schema coverage is low (14%), so more detail would be better.

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 combines fetching a saved search and inflating listings into one call. It distinguishes from sibling tools like onehome_get_saved_search and onehome_search_properties by explicitly mentioning the two-call sequence it replaces.

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 explicit guidance on when to use this tool instead of the two-call alternative. Also warns that PublicRemarks are missing and advises using onehome_get_property for full descriptions.

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 annotations (readOnly, openWorld, idempotent), the description adds behavioral context: it discloses that the endpoint may return an error field if the session lacks access and mentions it is sometimes agent-only. This is useful for the agent to handle auth responses.

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, covering key aspects in a few sentences without unnecessary detail. It front-loads the purpose and then adds behavioral notes. It is well-structured and easy to parse.

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 adequately explains the return structure (separate lists with name, attributes, proximity) and error handling. It covers the essential information an agent needs to invoke and interpret results.

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

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

With 0% schema description coverage, the description should clarify each parameter. It mentions lat/lng source but does not explain the optional 'language' parameter or provide additional meaning beyond the schema for any parameter. The focus is more on output than inputs.

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 fetches Local-Logic school data for a coordinate, distinguishing it from siblings by specifying the data source and structure (separate primary and high-school lists with attributes and proximity).

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 usage context by noting that lat/lng usually come from `onehome_get_property`, guiding the agent on how to obtain the required parameters. It does not explicitly list when not to use or alternatives, but the guidance is adequate for selection.

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

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

Annotations already mark as readOnly and idempotent. Description adds behavioral detail: returns active_session_id and per-listing routing preference, explaining how it affects tool behavior. 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?

Concise, well-structured, front-loaded with main purpose. Every sentence adds relevant information. No unnecessary words.

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, so description must cover return values. It lists fields and explains active session and routing. For a read-only inspection tool, it is complete enough, though could briefly mention no side effects.

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?

No parameters, schema coverage 100%. Description adds value by explaining the meaning of returned fields and how they influence other tools, compensating for absence of param guidance.

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?

Clearly states it returns one entry per registered session with specific fields (session_id, auth_mode, etc.). The verb 'Returns' and resource 'session' are explicit, distinguishing it from sibling tools like onehome_set_active_session.

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

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

Provides guidance on when to use: to see what default values tools will use by defaulting from active session context. Does not explicitly exclude alternatives but implies utility for understanding session 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?

The description goes well beyond the readOnly/idempotent annotations by disclosing the GraphQL endpoint behavior, the access-denied case for user { }, and exactly what data is used in the fallback. This gives the agent an accurate model of how the tool behaves under different authentication states, with no contradiction to 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 two sentences with no wasted words. It front-loads the primary return value, then explains the two authentication paths and fallback details without 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 read-only profile retrieval tool with one optional parameter and no output schema, the description is complete enough: it names the returned data, covers the main behavioral edge case, and the parameter semantics are fully handled by the input schema. The agent has sufficient information to invoke and interpret the result.

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

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

Schema description coverage is 100%, and the view parameter is thoroughly documented in the schema itself, including the compact/full distinction and the rationale for no field projection. However, the tool description itself adds no additional parameter meaning beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description clearly states what the tool does: it returns the OneHome user profile plus attached consumer-share groups. It is specific about the resource and the action, but it does not explicitly differentiate itself from sibling tools such as onehome_get_groups or onehome_get_session_context, so it stops short of a 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 clear usage context by distinguishing the two session paths: full agent/registered users query the GraphQL user endpoint, while magic-link consumer-share sessions fall back to checkToken data. It does not explicitly name alternatives or state when not to use this tool, but the context is strong and actionable.

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 read-only, open-world, and idempotent. The description adds value by explaining the output format (value/text pairs) and error handling (returns error field with HTTP details on rejection), which goes 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?

Two sentences are concise and front-loaded. First sentence defines the tool's function and lists outputs; second covers output format and error handling. No unnecessary words.

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

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

For a 3-parameter tool with no output schema, the description covers the output format and error case well. However, it omits details on coordinate system expected for lat/lng and does not explain the optional 'language' parameter. Minor gaps.

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% with no parameter descriptions. The description implies lat/lng form a coordinate but does not explain the 'language' parameter. It adds minimal meaning beyond the schema, failing to compensate for the lack of param documentation.

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?

Clearly states it retrieves 'Local-Logic location scores' for a coordinate and enumerates the types of scores (pedestrian, car, etc.). The verb 'get' is specific to a resource, but does not explicitly differentiate from siblings like onehome_get_schools, though the resource is distinct.

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. Does not mention prerequisites, coordinate system restrictions, or cases where another tool would be more appropriate.

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

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

The description goes well beyond the annotations by explaining that the default view is 'compact', which strips image/avatar URLs, and that passing view:'full' returns the envelope byte-for-byte. It also discloses the exact response envelope: { data, errors, status, url }.

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

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

The description is dense and front-loaded with the core purpose, then adds important caveats and examples. Some phrasing is wordy, but each sentence contributes useful operational context.

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 appropriately explains the response envelope, the compact/full behavior, common operation names, parameter passing, and sibling alternatives. An agent has enough context to invoke this escape-hatch tool correctly.

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

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

Schema description coverage is only 25%, so the description compensates by explaining that query is the full document body, operation_name must match the document, and variables should be passed as JSON. It doesn't exhaustively document query syntax, but it gives enough actionable direction for a raw GraphQL 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 the tool's job: send a raw GraphQL document with variables to services.onehome.com and get the full response envelope. It also frames itself as a 'power-user escape hatch' and names common operations, which distinguishes it from the higher-level sibling tools.

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

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

It explicitly identifies when to use the tool: when raw GraphQL access is needed. It also gives a concrete when-not by pointing out that LocalLogic schools/walk-score are REST endpoints and directs the agent to onehome_get_schools and onehome_get_walk_score instead.

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?

Description explains query selection logic, return values (auth mode, token expiry, elapsed time, error detail), and that it's a round-trip. Annotations already indicate readOnly, idempotent, openWorld; description adds concrete behavioral context without contradiction.

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

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

Three concise sentences covering action, session-specific behavior, return values, and usage recommendation. No unnecessary words.

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?

Fully describes the healthcheck behavior, return fields, and purpose. No output schema needed given the description covers key outputs.

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?

No parameters exist in schema; description doesn't need to add parameter info. Baseline 4 for zero-parameter tools.

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?

Clearly states the tool performs a round-trip authenticated query to verify auth and GraphQL reachability, with specific query selection based on session type. Distinguishes itself from sibling data-retrieval tools.

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

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

Explicitly advises to run this first when a tool fails to isolate auth issues from API misbehavior, providing clear when-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 already declare readOnlyHint, idempotentHint, and openWorldHint, so the description doesn't need to repeat those. However, it adds valuable behavioral details: the exact resolving algorithm (2-rung ladder), concurrency cap, per-row error handling, and output order preservation. No contradictions 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 reasonably concise despite being detailed. It front-loads the core purpose in the first sentence, then provides necessary details in subsequent sentences. Every sentence adds value, though slight tightening could improve readability.

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

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

Despite lacking an output schema, the description comprehensively explains the return format (preserved order, resolved/error rows, fields like url, listing_id, matched_via). It also covers error handling, concurrency, and the algorithmic equivalence to the single tool. This fully equips the agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it explains the default for group_id (magic-link session context), limits addresses maxItems/shape, and communicates the row-level output structure. This enhances understanding beyond the raw schema.

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

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

The description clearly states the tool bulk-resolves up to 100 structured addresses to OneHome canonical portal URLs and listing OSK IDs. It distinguishes itself from the sibling tool 'onehome_get_by_address' by explicitly noting they walk the same ladder but this is the bulk variant.

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 explicit guidance on when to use this tool versus the single-address alternative, mentions concurrency cap (6 in-flight), error isolation per row, and the default group_id behavior. This helps the agent choose correctly between sibling 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?

Discloses the two endpoint resolution modes, the automatic fallback when group_id returns 0 and a savedSearchId exists, and the default sort order. Notes that listings lack PublicRemarks, explaining why there's no description field. None of this contradicts the readOnlyHint, openWorldHint, and idempotentHint 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 longer than typical but well-structured with clear sections for each mode. Every sentence adds value, explaining fallback, defaults, and limitations. Could be slightly tighter but is appropriate for the 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?

Considering the tool has 7 parameters, no output schema, and complex fallback logic, the description covers the key behavioral aspects. It explains the listing projection and missing description field. However, it could mention pagination behavior more explicitly and clarify that page_num/page_size are optional.

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 low (14%), but the description compensates by explaining the purpose and defaults for key parameters like saved_search_id, group_id, include_dislikes, and sort. It does not detail page_num or page_size, but these are standard pagination params. The description adds meaningful context beyond the schema.

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

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

The description clearly states it fetches listings inside a OneHome consumer-share, with two distinct modes: using saved_search_id for agent-curated collections or group_id with fallback. This distinguishes it from sibling tools like onehome_get_property and onehome_get_saved_search_with_listings.

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 explicit guidance on when to use saved_search_id vs group_id, including the caveat that saved_search_id is the only mode for non-agent consumer accounts. Also explains default behavior from session context and the fallback mechanism. Directs users to onehome_get_property for full description when needed.

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 value by revealing the endpoint behavior (bypassing groups, hitting global endpoint) and listing returned fields (id, address parts, beds/baths, price, thumbnail). No contradictions 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 a single, well-structured paragraph of four sentences. It front-loads the core action, then adds context, return info, and optional parameter guidance. Every sentence contributes meaningful information without 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?

Given the tool's simplicity (2 parameters, no output schema), the description covers purpose, usage, return shape, and parameter hints. It could mention result limits or pagination, but overall it provides sufficient context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description carries full burden. It explains the 'query' parameter accepts addresses, MLS numbers, or partial queries, and 'group_id' scopes to a market. While query format specifics are omitted, the description provides meaningful usage context beyond 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 clearly states it performs a 'cross-feed suggestion search by address, MLS number, or partial query,' and distinguishes itself from siblings by noting it bypasses group/saved-search structures and hits a global endpoint. The verb 'search' combined with specific resource details makes the purpose unambiguous.

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

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

The description explicitly marks it as 'useful for' address lookups or MLS number searches, and mentions scoping via optional group_id. However, it does not explicitly state when not to use it or name alternative tools for different use cases, leaving some ambiguity for an AI agent.

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

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

Annotations already indicate destructiveHint=true (mutation) and idempotentHint=true. The description adds context by explaining the consequential effect on subsequent requests. It does not contradict annotations and adequately describes the 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 four sentences, tightly written with no extraneous information. It is front-loaded with the core purpose and sequentially provides usage context, parameter guidance, and consequence.

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

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

Given the tool's simplicity (one parameter, no output schema), the description fully covers what the tool does, when to use it, where to get the parameter, and the effect on subsequent behavior. No gaps remain.

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% (one parameter with a description). The description adds value by explaining the parameter's source (previous calls to onehome_set_auth or onehome_get_session_context) and its purpose, slightly exceeding the schema's description.

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

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

The description clearly states the tool's purpose: 'Force a specific registered session to be the active one.' It specifies the verb 'force' and the resource 'registered session,' and distinguishes it from sibling tools by focusing on session management, while siblings are largely data retrieval tools.

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

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

The description explicitly states when to use the tool: 'Useful when MLS-suffix routing picks the wrong session.' It provides concrete scenarios and references parent tools for obtaining the session_id. It also clarifies the effect on subsequent requests without a ~MLS suffix.

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?

Discloses registration of a new transport, marking active, and that previous sessions stay. Explains routing using MLS suffixes. Annotations indicate destructiveHint=true, which aligns with state modification. Description adds security notes about magic links in chat history, beyond 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 comprehensive and well-structured, with clear sections. It front-loads the purpose and input shapes. Slightly long but every sentence adds value; could be tightened slightly but not excessively verbose.

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?

Fully covers input types, detection, session management, routing, response contents (session_id, active_session_id, auth mode, etc.), and security. No output schema, but response structure is described. Completes the agent's understanding.

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?

Single 'input' parameter with schema description. The description greatly expands on valid input formats (URL with token, JWT, email-token) and the detection logic. Provides examples and explains how each is processed.

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 registers an additional authenticated session using various credential types. It differentiates from sibling tools like onehome_set_active_session by explaining session management and routing with MLS suffixes.

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 explains when to use: when a buyer holds shares across multiple agents/MLSes. Details input shape detection (URL, JWT, email-token) and mentions alternatives for session switching by name. Provides clear context on usage.

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