HireNimbus home services MCP

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

The annotations already signal read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: it runs the provider search first with query='electrician' prefilled, it should not start OTP until create_booking returns auth_required, and omitting the context parameter does not fail the call. These details give the agent a clearer model of side effects and sequencing.

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; it front-loads the core intent and example triggers before procedural guidance. Almost every sentence adds unique information, though the same point about context is made both in the description and the schema, slightly inflating 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 output schema exists and the annotations cover safety semantics, the description is nearly complete. It explains the full workflow, when to stop for OTP, exclusions, and the required context format. The only minor gap is pagination behavior (page/limit), but defaults exist and the main flow is fully 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 location and context with detailed descriptions, but page and limit have only defaults and no explanation. With 50% schema coverage, the description partially compensates by restating and expanding context requirements (15-25 words, third person, no PII, omit is allowed) and by emphasizing location should be a 5-digit ZIP. It does not add any semantics for page or limit, leaving pagination behavior implicit.

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 use case ('book or hire a electrician') and enumerates many example problems (dead outlet, breaker tripping, EV charger, etc.), making the tool's purpose unmistakable. It clearly distinguishes itself from siblings by explaining that it runs a provider search and then defers actual booking to create_booking.

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

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

The description gives explicit conditions for use, including a long list of qualifying scenarios and an explicit exclusion: 'Do not use for DIY how-to advice or price research with no hiring intent.' It also outlines the sequence of steps (provider search → ask which pro → create_booking). It doesn't explicitly name find_electrician as the alternative for search-only intent, which would make it even clearer, but the exclusion plus process guidance is strong.

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

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

Annotations already declare readOnlyHint and idempotentHint; the description adds important behavioral context beyond those: the tool only runs the provider search, booking is delegated to create_booking, and OTP must not be started until auth_required is returned. This is consistent with the read-only annotation and clarifies the division of labor between the tools.

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 and the first sentence is a run-on, but the extensive list of handyman tasks serves a real routing purpose. The key workflow points are front-loaded and each sentence contributes either a usage condition, a behavioral step, or a context-handling instruction.

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 output schema and detailed annotations, the description covers when to use the tool, how to proceed after results, what to avoid, and how to handle context. It is slightly incomplete in not addressing how this tool relates to find_handyman or book_electrician, but an agent has enough information to select and 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 already documents location and context in detail, and the description adds useful non-obvious context semantics ('Omitting it does not fail the call; do not send an empty string'). However, page and limit have no schema description and no description-level explanation, leaving their semantics to be inferred from names and defaults, which is a meaningful gap at 50% schema coverage.

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

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

The description clearly identifies the trigger ('wants to book or hire a handyman') and gives a long, concrete list of example jobs. It also states that the tool runs a provider search with query='handyman'. However, it never explicitly frames the primary output as returning providers and does not contrast itself with sibling find_handyman or book_electrician, so differentiation is mostly 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 gives explicit when-to-use conditions, a when-not-to-use condition ('Do not use for DIY how-to advice or price research with no hiring intent'), and precise workflow instructions: ask which pro, then use create_booking, and do not start OTP until auth_required. This is strong routing guidance that leaves little to inference.

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

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

The description reveals that the tool itself only runs the provider search (read-only), and the actual booking is delegated to create_booking. It also discloses the OTP timing, the requirement to always pass context (with 15-25 word format), and that omitting context does not fail the call. This adds significant value beyond the readOnlyHint annotation, clarifying the non-destructive nature and the intended sequence.

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 is purposeful: it enumerates problem types, gives workflow steps, and specifies parameter details. It is well-structured, starting with the primary use case and then proceeding to constraints and execution. A minor deduction for verbosity—the list of scenarios could be trimmed without loss—but it remains highly functional.

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 that orchestrates a multi-step booking flow, the description covers all essential aspects: when to invoke, what the tool returns (provider list), how to proceed (ask which pro, then create_booking), OTP handling, and parameter specifics. The presence of an output schema relieves the need to describe return values. Nothing critical is missing.

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

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

The description gives detailed, actionable guidance for the two complex parameters: location (prefer ZIP, never street address, use postalCode from profile) and context (15-25 words, third person, no PII, with examples). Page and limit have defaults and are self-explanatory, so the lack of description is acceptable. This compensates well for the 50% schema coverage.

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

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

The description clearly states the tool's purpose: booking or hiring an HVAC pro, with a long list of concrete problem scenarios (AC not cooling, furnace won't turn on, etc.). It distinguishes itself from sibling tools by focusing on HVAC and explicitly naming the alternative workflow (create_booking) for the actual booking.

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

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

It explicitly states when to use ('Use when the user wants to book or hire a HVAC') and when not to ('Do not use for DIY how-to advice or price research with no hiring intent'). It also provides a step-by-step workflow (run provider search, ask which pro, then create_booking) and specifies not to start OTP prematurely. This is exemplary 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?

The description goes beyond annotations by revealing the tool is an orchestration step: it runs a prefilled provider search, asks which pro to book, and then delegates to create_booking. It also discloses OTP sequencing ('Do not start OTP until create_booking returns auth_required'), which is critical given the readOnlyHint annotation and the 'book' name.

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 well-organized: trigger scenarios, workflow, OTP timing, exclusions, and context instructions are each addressed. The extensive list of plumbing problems is useful for intent classification but makes it slightly verbose; still, every sentence contributes.

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 output schema and annotations, the description is nearly complete for invocation. It covers the full workflow, OTP handling, exclusions, and context requirements. The only minor gap is no explicit guidance on page/limit parameters, though their defaults make this non-blocking.

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 provides thorough descriptions for location and context. The description adds only a small nuance about context ('Omitting it does not fail the call; do not send an empty string') but adds nothing for page and limit, which lack schema descriptions. With 50% schema coverage, it partially compensates but not fully.

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 for booking/hiring a plumber and gives a concrete list of trigger scenarios (leaky faucet, clogged drain, water heater, etc.). It also distinguishes itself from siblings by explicitly routing the agent to create_booking after search and excluding no-hiring-intent uses.

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 says when to use the tool ('when the user wants to book or hire a plumber'), when not to use it ('Do not use for DIY how-to advice or price research with no hiring intent'), and names the next step (create_booking) after the user picks a pro. This gives clear decision rules versus alternatives like find_plumber.

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

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

Beyond the readOnly/idempotent annotations, or description discloses the operational flow: it runs a prefilled provider search, does not create the booking itself, and instructs to wait for create_booking to return auth_required before starting OTP. It also explains the analytics-driven context requirement and its tolerances, adding substantial behavioral context the annotations do not provide.

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

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

The description is front-loaded with the use case and then delivers action steps, exclusions, and parameter guidance in compact, purposeful sentences. Every sentence adds either a selection criterion or a behavioral requirement, so the length is justified by the operational 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?

For a tool that coordinates provider search and subsequent booking, the description covers the trigger scenarios, the negative cases, the required next step (create_booking), the OTP sequencing, and the context parameter rules. The output schema is present, so returning value details are not needed in the description, and nothing essential for correct invocation is missing.

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

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

The schema already documents location and context in detail, and the description reinforces the context requirements with guidance about length, third-person wording, and not sending empty strings. However, page and limit are left undocumented in both schema and description, and the description does not add semantic guidance for the required location parameter beyond what the schema provides.

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

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

The description states a specific verb and resource bundle: use when the user wants to book or hire a renovation, and it enumerates concrete project types (kitchen remodel, basement finishing, flooring, deck build, painting, etc.). It also clearly separates this tool from DIY or price-research intenthebdomad, which distinguishes it from non-booking siblings like find_renovation or search_providers.

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 the tool ('when the user wants to book or hire a renovation') and when not to ('Do not use for DIY how-to advice or price research with no hiring intent'). It also gives a clear follow-on workflow: run the search, ask which pro, then call create_booking, with precise OTP timing 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=false (mutation allowed). The description explicitly discloses that the tool 'may create a real booking request,' including out-of-market addresses, and requires homeowner approval before confirmation. It also details the context parameter's optional nature and warns against empty strings. This goes well 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?

Every sentence earns its place: purpose, safety warning, preview/confirm flow, context requirement, and parameter clarifications. The structure is front-loaded with the core action and then details, making it easy for an agent to parse quickly.

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 tool has 9 parameters (1 required) and an output schema, but the description covers all critical behavior: rebooking flow, side effects, out-of-market handling, context usage, and address overrides. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 89%, so most parameters are self-explanatory. The description adds extra meaning for `context` (always include, 15-25 words, third person, no PII) and `confirm_booking` (false=preview, true=submit). It also clarifies the address override and location hints, going beyond the schema.

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

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

The description states a specific verb and resource: 'Rebook a HireNebula provider the homeowner has used before, by job ID.' It clearly distinguishes from sibling book_* tools by targeting a prior provider, not a trade. The preview/confirm flow adds precision.

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 when to use it (rebooking a previously used provider) and provides a clear two-step flow (preview with confirm_booking=false, then confirm after homeowner approval). It also warns about out-of-market addresses. It doesn't explicitly name alternatives or state when NOT to use it, but the context is sufficient.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds crucial behavioral context: the first call is a non-destructive preview, and the second call actually cancels. It also discloses that the cancellation reason is sent to the provider, a side effect beyond what annotations convey.

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 the core action and two-step flow front-loaded. It conveys all essential operational details without redundancy or filler, achieving high information density in a compact format.

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 destructive two-step action, the description covers the entire workflow: preview, approval, cancellation, and side effect. The presence of an output schema handles return values, so nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema coverage is 100%, but the description adds significant value by emphasizing that the context parameter is mandatory on every call and explaining its purpose and format. It also clarifies the semantic difference between confirm_cancellation=false (preview) and true (cancel), which the schema's default description implies but the description makes explicit.

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 ('Cancel') and resource ('one of the authenticated homeowner's bookings'), and it distinguishes itself from all sibling tools (no other cancel tool exists). It also clarifies the two-step process, making the purpose unambiguous.

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

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

The description explicitly instructs the agent to first call with confirm_cancellation=false to present a preview, then call again with true only after explicit approval. It also mandates the always-include context argument and warns that the reason is delivered to the provider, giving clear usage direction.

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=false and idempotentHint=false, and the description goes well beyond those by disclosing that confirmed calls are not idempotent and may create duplicate requests, that unauthenticated calls return auth_required, that default confirm_booking=false only previews, and that marketplace availability varies by region. This is rich, non-obvious behavioral context that an agent needs before invoking the tool.

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

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

The description is longer than ideal but front-loads the core purpose and selection criteria, followed by auth, preview, duplicate, market, and context notes in roughly logical order. Some points are repeated (do not call before a pro is picked), but nearly every sentence contributes a distinct operational fact, so the length is justified.

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

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

Given the tool's complexity — auth, preview vs. confirm, non-idempotency, market restrictions, sibling routing, and an output schema an agent can rely on for return values — the description is complete. It covers the main failure modes, edge cases, and required invocation pattern, leaving little an agent needs to infer on its own.

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 70%, and the description meaningfully supplements several parameters: confirm_booking's preview-vs-submit effect, search_result_id's role in out-of-market bookings, and the context parameter's analytics purpose plus the warning not to send an empty string. It does not describe all parameters (e.g., serviceProviderSlug, job_description, address), but the schema covers those adequately, and the description adds value where ambiguity is highest.

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

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

The description clearly identifies a specific action — creating a secured booking after the homeowner has picked a specific pro from search or book_* results — and explicitly distinguishes it from discovery and the category-specific booking siblings. It names the sibling tools it is not, so an agent can select it correctly without opening the schema.

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

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

The description gives explicit when-to-use context (only after the homeowner has seen and picked a specific pro), explicit when-not-to-use guidance (do not call to start discovery, do not call on ambiguous intent), and names concrete alternatives (book_handyman, book_hvac, etc.) for standard workflows. It also explains auth handling, preview vs. submit behavior, and out-of-market requirements.

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 signal read-only, non-destructive, idempotent behavior, and the description reinforces this with 'Read-only; does not create a booking.' It adds useful behavioral context: how to handle empty results, when get_my_profile may supply the ZIP, and the requirement to pass context for analytics.

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

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

Although long, the description is tightly packed and front-loaded with use cases, then exclusions, then behavioral rules. Every sentence adds decision-relevant information; none merely restates the title or schema.

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

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

Given the output schema exists and annotations cover safety, the description fully covers when to call, what to pass, how to handle edge cases, and how to behave with results. An agent has enough context to invoke this tool correctly in a variety of user-intent 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?

The description adds value for location and context beyond the schema, like 'never pass a street address' and '15-25 words, third person, abstract purpose only.' Page and limit are not explained, but they are self-explanatory with defaults, and schema coverage for the other two parameters is detailed.

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 clearly that the tool finds, searches, or compares electrician professionals and gives a concrete list of electrician-specific problems. This differentiates it from sibling tools like find_plumber or find_hvac without needing to open their 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 tells when to use the tool, what not to use it for (DIY advice, cost research, emergencies), and when to use get_my_profile. The guidance about preferring a 5-digit ZIP and keeping empty results instead of substituting nearby providers gives clear, actionable decision rules.

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 annotation, the description adds meaningful behavior: it does not create a booking, results should be shown before booking or OTP, empty ZIP results must remain empty rather than filling from another area, and the `context` parameter should be provided but omitting it will not fail the call. These details materially shape an agent's invocation and 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 longer than average, but almost every sentence earns its place by stating a use case, an exclusion, a location rule, or a behavioral guardrail. The example list of handyman tasks is extensive yet useful for classification; only slight redundancy with the schema's context description keeps it from a 5.

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 finder tool with a rich output schema and safety annotations, the description covers invocation scenarios, location handling, empty results, booking behavior, and the context parameter requirement. It is complete enough for correct use, though page and limit semantics are not addressed and no sibling alternative is named for broader search scenarios.

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 documents location and context well, and the description reinforces key constraints like preferring a 5-digit ZIP and using third-person, non-PII context. However, page and limit are left without any semantic explanation in either the schema or description, and schema coverage is only 50%, so the description does not fully compensate for the undocumented 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 states a specific verb and resource ('find, search, or compare handyman professionals') and enriches it with concrete example tasks like TV mounting and drywall repair. It distinguishes this tool from book_handyman by explicitly noting it is read-only and from find_electrician/find_plumber etc. by focusing on handyman work.

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

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

The description gives explicit 'Use when' and 'Do not use for' guidance, including exclusions like DIY advice, cost research without hiring intent, and emergencies. It also provides sequencing advice involving get_my_profile and ZIP-based search, but it does not explicitly name alternative sibling tools for the excluded cases, so it stops just short of a 5.

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

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

The description adds meaningful behavior beyond the annotations: it clarifies the tool is read-only, does not create bookings, should not fabricate providers when the ZIP returns no results, and should preserve empty results. It also documents the optional-but-expected context parameter behavior, including that omitting it won't fail the call and that an empty string should not be sent.

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 and well organized, front-loading user intent and exclusions before behavioral details. Some redundancy exists—'Prefer a 5-digit ZIP' and the context-passing rule appear in both the description and the schema—but each sentence otherwise earns its place given the tool's complexity.

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

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

The description is complete for a tool of this complexity, covering use cases, exclusions, profile/ZIP integration, empty-result behavior, and the required analytics context. Since an output schema exists, not detailing the return shape is acceptable. No material guidance an agent needs to call the tool correctly is missing.

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

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

With only 50% schema description coverage, the description compensates well for the two semantically important parameters: location (ZIP preference, postalCode from get_my_profile, never a street address) and context (15-25 words, third person, no PII, always passed). The page and limit parameters are not explained in the description, though their defaults in the schema make them largely self-explanatory.

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 ('find, search, or compare HVAC professionals') and gives concrete problem examples, which makes the tool's purpose unmistakable. It also implies a clear distinction from booking tools by noting that it is read-only and does not create a booking.

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 ('Use when the user wants to find...') and when not to use it ('Do not use for DIY how-to advice... emergencies...'). It also names get_my_profile as a complementary tool and positions this tool as the pre-booking search step, providing strong routing guidance.

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

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

Annotations already mark readOnlyHint and idempotentHint, and the description reinforces 'Read-only; does not create a booking' and 'Showcase matching pros before any booking or OTP.' It adds non-obvious behavior: if the ZIP returns no providers, keep the empty result and do not substitute providers from another area. This is exactly the kind of context beyond annotations that helps an agent avoid a common mistake.

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 every sentence carries information: use cases, exclusions, read-only status, ZIP handling, empty-result behavior, and context policy. It is longer than a one-liner but well organized with signposts. Slight redundancy with annotations (read-only) costs a point, though it is not enough to harm usability.

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 moderate complexity — four parameters, one required, an optional analytics context field, and conditional ZIP sourcing — the description covers every operational aspect an agent needs: what triggers the call, what input to prefer, what to do on empty results, and what the read-only side effect is. The output schema exists, and the description properly avoids re-explaining return values.

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 50% description coverage, and the description compensates by explaining the location semantics ('Prefer a 5-digit US ZIP', 'Never pass a street address') and how to populate it after get_my_profile. The context parameter is also explained with length, person, and PII constraints. The page and limit parameters are not discussed in the description, but their integer defaults and idiomatic meaning are self-evident from the schema, so the compensation is adequate.

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

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

The description opens with a clear verb-resource pair ('find, search, or compare plumber professionals') and goes on to enumerate concrete scenarios (leaky faucet, clogged drain, water heater repair) that map directly to user intents. It is clearly differentiated from sibling find_electrician, find_hvac, and find_handyman tools by naming the plumber-specific domain.

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

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

It states explicit when-to-use criteria (user wants plumber professionals or describes a plumber-solved problem) and explicit exclusions (DIY advice, cost research without hiring intent, auto/appliance retail, emergencies needing 911). It also provides a conditional branching rule involving get_my_profile and ZIP input, leaving no ambiguity about when this tool should be invoked over 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explicitly says 'Read-only; does not create a booking', instructs to keep empty results rather than filling with providers from another area, and mandates passing the optional context parameter for analytics. These are behavioral traits an agent needs to know and are not present in the annotations.

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

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

The description is dense but well-organized: it front-loads the primary use case and examples, then exclusions, then behavioral notes, then parameter guidance. Every sentence earns its place, though it is longer than strictly necessary and could be tightened without losing information. The structure is logical and scannable.

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

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

For a read-only search tool with a rich output schema, the description covers the core decision (when to call), the location input rules, the empty-result behavior, the analytics context requirement, and the relationship to siblings. The output schema exists, so return values need not be described. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 50%, so the schema documents location and context but not page or limit. The description compensates by explaining the location preference (5-digit ZIP, use postalCode from get_my_profile, never pass a street address) and by explaining the context parameter's purpose, length, third-person requirement, and PII prohibition. It does not add detail about page/limit, but those are self-explanatory pagination parameters with defaults, so the gap is minor.

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 ('find, search, or compare') and a clear resource ('renovation professionals'), then enumerates concrete example projects (kitchen remodel, bathroom remodel, basement finishing, flooring, deck build, room addition, wall removal, painting, countertop, cabinets). This distinguishes it from sibling find_* tools by domain and from book_renovation by explicitly stating it is read-only and does not create a booking.

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

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

The description gives explicit when-to-use guidance ('Use when the user wants to find, search, or compare renovation professionals, or describes a problem a renovation solves'), explicit when-not-to-use guidance ('Do not use for DIY how-to advice, cost research with no hiring intent, auto or appliance retail questions, or emergencies'), and names the sibling alternative (book_renovation) by stating this tool does not create a booking. It also instructs to use get_my_profile for a saved ZIP, which is a clear routing decision.

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, idempotentHint=true, and destructiveHint=false. The description adds 'Requires authentication,' which is beyond the annotations, and reinforces 'does not create a booking.' However, it does not describe the specific status values returned or any potential failure modes. Since annotations cover safety and idempotency, the extra auth note adds some value but not rich 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 very concise: three short clauses that front-load the purpose ('Check the current status...'), then add authentication and read-only notes. Every sentence earns its place, and there is no filler. It is well-structured and immediately readable.

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 an output schema exists, the description need not explain return values. However, it lacks guidance on when to use this tool versus sibling tools like cancel_booking or get_provider_details, and it does not mention the context parameter or its mandatory nature. For a tool with many siblings, this is a notable gap, though the core purpose is covered.

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

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

Schema description coverage is 50% (context has a detailed description, booking_id has none). The tool description only says 'by ID,' which adds minimal semantic value to booking_id. It does not compensate for the missing parameter documentation, nor does it address the discrepancy that context is described as always required but not listed in the required array. The description fails to clarify parameter expectations beyond the schema.

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

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

The description states a clear, specific action: 'Check the current status of a HireNimbus booking by ID.' This uses a strong verb and identifies the resource, and the phrase 'does not create a booking' explicitly differentiates it from create_booking and other mutation tools among the siblings. It is immediately evident what this tool does.

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

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

The description implies its use case by saying it checks status and is read-only, but it does not explicitly state when to prefer it over alternatives like cancel_booking or get_provider_details. There is no 'use this when...' guidance or explicit exclusion of other tools. The read-only note provides a weak hint, but the context is not fully developed.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds only purpose and usage context, not additional behavioral details like return shape or side effects; 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 focused sentence with no filler. The key trigger condition is front-loaded, and every word 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 simple tool with one well-documented parameter and strong annotations, the description covers the essential 'when to call' guidance. However, it does not clarify what happens after the call (e.g., that new tool definitions are returned or injected), and with no output schema this could leave some ambiguity.

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

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

The input schema fully documents the 'context' parameter with examples and a clear explanation, so the description does not need to repeat parameter details. Baseline 3 applies because schema coverage is 100%.

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

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

The description names a specific action ('Check for additional tools') and a resource ('tools'), which clearly positions it as a meta-tool rather than a domain-specific sibling. It doesn't fully spell out the exact mechanics, but it is enough to distinguish it from the find/book siblings.

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

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

The description gives a clear trigger: use it 'whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.' This is explicit about when to call it, though it doesn't describe exclusions or name alternative tools directly.

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

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

Despite annotations already marking the call read-only, idempotent, and non-destructive, the description adds meaningful behavioral detail: it can return ok, error, or auth_required, and prescribes what to do on auth_required. This goes beyond the annotations and matches the read-only safety profile without contradiction.

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

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

The description is front-loaded with purpose and usage, and the later field list is mostly actionable (e.g., search_location must be a ZIP, never City or street). It is longer than strictly necessary because it restates return fields that an output schema would cover, but each section earns its place with operational guidance.

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 one well-documented parameter, strong annotations, and an output schema, the description supplies the missing orchestration: when to call, how to interpret auth_required, how to turn address.postalCode into search_providers.location, and what to do when postalCode is absent. An agent has everything needed 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 only parameter, context, is fully specified by the input schema (always include, 15-25 words, third person, no PII), so schema coverage is 100%. The tool description itself adds no new parameter-level semantics, so the baseline 3 is appropriate.

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

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

The description opens with a specific action and resource: 'Load the authenticated homeowner profile.' It then states the exact niche (fill saved service address before search) and explicitly what not to use it for (anonymous discovery, phone/OTP), so it is easily distinguished from siblings like search_providers and create_booking.

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 explicit when-to-use and when-not-to-use conditions: only when the HireNimbus account is already connected, only to fill the saved service address before search, never for anonymous discovery or OTP. It also names the alternative flow with create_booking for the auth_required case.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by stating 'Requires authentication' and 'does not create a booking,' which are behavioral traits not present in the annotations. It could go further by describing pagination or return format, but the output schema exists and the description is sufficient for a read-only list operation.

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 with no wasted words. It front-loads the core function, then adds authentication and usage context, then clarifies read-only behavior. 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 read-only list tool with a full output schema and annotations covering safety, the description is nearly complete. It covers authentication, read-only behavior, and usage timing. The only minor gap is that it doesn't mention whether results are ordered or limited, but the output schema likely covers return structure, and the tool is simple enough that this is not a significant omission.

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 fully documents the single 'context' parameter. The description does not add parameter-specific meaning beyond the schema, but it doesn't need to because the schema already provides detailed guidance including examples and PII restrictions. 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 states a specific verb ('Return') and resource ('past and active jobs for the authenticated homeowner'), and clearly distinguishes this from sibling tools by noting it is read-only and does not create a booking. It also names the intended use case (augmenting recommendations, job history), which differentiates it from booking/search 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 says when to use this tool: 'Use after search when augmenting recommendations, or when the user asks about job history.' It also implicitly excludes booking creation by stating 'does not create a booking,' which helps an agent avoid confusing it with book_* siblings. This is clear, actionable 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 mark the tool as readOnly, idempotent, and non-destructive, lowering the bar. The description adds useful behavioral context beyond annotations: it 'does not create a booking,' returns ratings/reviews/past work/availability 'where available,' and explains that omitting context does not fail the call and that an empty string should not be sent. No contradictions with annotations exist.

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?

Five sentences that are each purposeful, with the core 'fetch full profile' statement front-loaded. The context instructions are detailed and somewhat repetitive of the schema, but they earn their place by clarifying non-failure and empty-string constraints.

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?

An output schema exists, so the description needn't detail the return structure. It explains what the call returns, when to call it, and the analytics context policy. It does not mention invalid-slug behavior or pagination, but those are minor for a read-only detail lookup.

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 50% (context documented, slug not). The description compensates by explaining the slug is the provider identifier and by giving detailed semantics for context: 15-25 words, third person, abstract purpose only, no PII, always pass even though technically optional, and never empty.

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 opens with a specific verb and object: 'Fetch the full profile for a HireNimbus service provider by slug.' It also names the preceding sibling tools (find_handyman, find_hvac, etc.) and positions itself as a detail drill-down, clearly distinguishing it from search/find 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 it: after any find_* or search_providers call 'when the homeowner wants more detail about a specific provider.' It also rules out booking by stating 'does not create a booking,' though it does not explicitly name alternative read-heavy tools like get_provider_reviews.

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, idempotentHint=true, and destructiveHint=false, so the description's reinforcement of 'Read-only; does not create a booking' adds little. However, the description discloses the context parameter's optional-yet-required nature ('Always pass optional context', 'Omitting it does not fail the call; do not send an empty string') which is not covered by annotations. This is valuable behavioral nuance for the 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?

The description is two sentences, tightly packed with the core action, usage context, and a behavioral note about the context parameter. It is front-loaded with the primary function and avoids any filler or redundant wording. Every clause contributes to agent decision-making.

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 that an output schema exists (so return format is covered), the description sufficiently explains the tool's purpose, when to use it, and the critical context parameter behavior. It does not describe pagination limits or results ordering, but those are inferable from parameter names and the output schema. The context quirk is well documented, making the tool callable correctly without additional assumptions.

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 clarifies that `slug` identifies the provider ('by slug'), but the schema already provides a detailed description for `context` (which the description echoes). The pagination parameters `page` and `page_size` are not described in either the schema or the description, relying only on their names. With schema coverage at 25%, the description partially compensates for the missing parameter explanations but does not fully address pagination semantics.

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 explicitly states 'Fetch reviews for a HireNimbus service provider by slug,' which is a specific verb (fetch), resource (reviews), and identifier (slug). It is clearly distinguishable from sibling tools like booking (book_plumber) or provider info (get_provider_details) because it focuses solely on reviews. The purpose is unambiguous and action-oriented.

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 a clear use case ('Use when the homeowner wants to see what other homeowners have said about a provider before booking') and explicitly notes it is read-only and 'does not create a booking,' which helps avoid confusion with booking tools. However, it does not explicitly name alternative tools such as get_provider_details or search_providers, leaving some inference required about when to use those 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?

Annotations already declare read-only, idempotent, and non-destructive behavior, but the description adds valuable behavioral context: no booking creation, launch-market booking caveats, preserving empty results, the search_result_id contract for create_booking, and the context analytics requirement. This goes well beyond annotation coverage.

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

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

The description is dense but well organized, front-loading the use case before caveats. Some statements repeat information already in the schema or annotations, such as read-only status and ZIP preference, so it is not maximally concise, but every sentence carries useful decision or safety 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 the output schema exists and the sibling set is rich, the description covers the critical decisions: when to use this tool, when to defer to find_* tools, location constraints, empty-result behavior, booking integration, and analytics context. An agent has enough to call it correctly and avoid common mistakes.

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 60% schema description coverage, the description adds meaningful parameter context: it reinforces the preferred 5-digit ZIP format, forbids street addresses, and clarifies that context should always be passed but that omitting it will not fail the call. It doesn't detail page or limit, but those have schema defaults and are lower-risk.

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 defines the tool as the general home-services search for anything outside the five dedicated find_* categories, with concrete examples like cleaning, landscaping, and roofing. It also names the sibling find_* tools it is not, so an agent can disambiguate 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 states when to use this tool versus the find_* alternatives, including the ambiguous-category case. It also gives specific location guidance, warns against street addresses, and instructs not to substitute providers for empty results—strong, actionable routing.

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