HireNimbus MCP Server

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read-only operation. The description adds valuable context by clarifying that this tool runs a provider search and prompts the user, but does not itself create the booking (that goes to create_booking). This explains its role beyond what annotations state, with no 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 a moderate-length paragraph that front-loads the primary use case, then provides a structured workflow and an exclusion clause. It lists many examples but each serves to clarify scope. No filler sentences; every clause adds value.

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 (per context signals) and annotations cover the safety profile, the description needn't discuss return values or mutations. It fully explains the tool's role in the booking flow, what triggers it, and what it does not do. The only minor gaps are the undocumented page/limit parameters, but those are schema-level and the description's focus on user intent is sufficient for an agent to call 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?

Schema description coverage is only 33% (only 'location' has a detailed description). The tool description does not mention 'page' or 'limit' at all, and does not reinforce the location guidance beyond what's already in the schema. Since coverage is low, the description should compensate but doesn't, leaving agents to guess about the optional parameters. Only the schema's own location description is helpful, but the tool description itself adds no parameter 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 states a very specific verb-resource pair ('book or hire an electrician') and enumerates many concrete scenarios (dead outlet, breaker tripping, panel upgrade, etc.), making it unmistakable what the tool does. It also explicitly differentiates from siblings: it mentions running provider search and then using create_booking, and is clearly distinct from find_electrician (mere search) and create_booking (final 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 provides explicit when-to-use guidance ('Use when the user wants to book or hire an electrician'), includes a clear exclusion ('Do not use for DIY how-to advice or price research with no hiring intent'), and even outlines the workflow ('Runs the provider search first... ask which pro... then use create_booking'). This leaves no ambiguity about when to invoke this tool versus alternatives.

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

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

The description discloses the internal orchestration: it runs a provider search with a pre-filled query, then prompts for pro selection, and delegates the actual booking to create_booking. This adds meaningful context beyond the readOnlyHint annotation. It doesn't cover failure modes (e.g., no providers found) but that is minor for a read-only orchestration 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 average, but every sentence earns its place: the example list is scenario-relevant, the workflow step is essential, and the exclusion clause prevents misuse. It is front-loaded with the 'Use when' trigger and flows logically. Slightly verbose, but not padded.

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 (which presumably documents return shape), the description covers all necessary context: when to use, workflow, exclusions, and even the mechanism for supplying location (via get_my_profile postalCode, described in the schema). An agent has everything it needs to decide and execute correctly. No significant 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?

The tool description contributes zero parameter-level clarity; it never mentions location, page, or limit. The schema provides a detailed description for location (ZIP preference, how to derive from get_my_profile), but page and limit are undocumented. With schema coverage at only 33%, the description should compensate but does not. The page and limit are simple, but an agent still has no guidance on when to change them.

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 the exact purpose ('book or hire a handyman'), backs it with a concrete list of example jobs (TV mounting, drywall, etc.), and explicitly separates it from DIY advice or price-only research. This clearly distinguishes it from sibling tools like find_handyman (search without booking intent) and book_electrician (different trade).

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 ('when the user wants to book or hire a handyman — including when they describe a problem to fix'), what not to use for ('Do not use for DIY how-to advice or price research with no hiring intent'), and a step-by-step workflow ('Runs the provider search first... ask which pro... then use create_booking'). This is model guidance for when/why to invoke.

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 warn it is read-only and idempotent, so the safety profile is covered. The description adds valuable context: it does not directly create the booking; it runs a search, then delegates to create_booking. This goes beyond annotations, clarifying the tool's role as an initial step rather than a complete booking action. 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 long but information-dense, with a logical structure: when to use, then the flow steps, then when not to use. Every sentence adds value; over-specification of problem types is arguably useful for classification. It could be trimmed slightly, but it is not verbose or redundant. Front-loads the main intent.

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 output schema covers return values, so that is not needed in the description. The tool's flow is well explained, and annotations cover safety. However, the description omits any guidance on parameters, which are central to invocation. It also does not clarify the relationship to find_hvac or other find tools, leaving part of the context incomplete.

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 low at 33% (only location is described in detail). The description does not mention any parameters at all, failing to compensate for the gap. Page and limit lack any explanation in both description and schema (beyond defaults), leaving the agent to guess their semantics. Though location has a thorough schema description, the overall lack of parameter guidance is a significant weakness.

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 purpose: booking or hiring an HVAC professional, with a long list of specific scenarios that qualify (AC not cooling, furnace won't turn on, etc.). It names the verb 'book' and the resource 'HVAC', and distinguishes itself from the find_* siblings by framing itself as a booking-oriented flow that runs a provider search first.

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 (booking or hiring with a problem to fix) and when not to use (DIY advice or price research without hiring intent). It outlines the flow: run search, ask which pro, then use create_booking. However, it does not explicitly compare with sibling tools like find_hvac, though the exclusion of non-booking intents implies those should use the find_* tools. A clear 'when not to use' is present, but the alternative tool is not named.

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 discloses the tool's orchestration behavior: it runs a provider search with a prefilled query='plumber', asks for pro selection, and then delegates booking to create_booking. This is beyond the annotations (which already cover read-only, idempotent, non-destructive). It also provides detailed location-parameter instructions, adding context the schema does not. 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 longer than average but every sentence earns its place: purpose, examples, workflow, exclusions, and critical location guidance. It is front-loaded with the primary use case and avoids redundancy, though it does repeat some location details already in the schema. Overall, it is efficiently structured without fluff.

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

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

The description is complete enough for an agent to use the tool correctly. It covers when to invoke, the step-by-step process, the handoff to create_booking, and the precise location-input rules. The existence of an output schema reduces the need to describe return values. No essential information appears missing for a booking-orchestration 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?

The description substantially clarifies the required 'location' parameter: prefers ZIP, instructs to pass postalCode from get_my_profile after confirming the address, and explicitly says never to pass street address or search_location. This adds meaning beyond the schema's description. However, the optional 'page' and 'limit' parameters are not mentioned at all, and schema coverage is only 33%, so they remain undocumented. Still, they are trivial with defaults, so the description's focus on the critical parameter justifies a 4.

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

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

The description states a specific verb (book/hire) and resource (plumber), enumerates many example problems that trigger its use, and clearly differentiates from sibling tools like book_electrician and book_handyman by naming the profession and typical tasks. It also distinguishes from find_plumber by implying the booking intent.

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 states when to use (user wants to book/hire a plumber, including a long list of problems) and when not to use (DIY advice or price research with no hiring intent). It also outlines the workflow: run provider search first, ask which pro, then use create_booking. This gives clear routing and step 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 discloses that the tool runs a provider search with a prefilled query and then guides the user toward booking, which aligns with the readOnlyHint annotation. It adds valuable context about the step sequence and the exclusion, going beyond what the annotations alone 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 moderately concise, front-loading the primary use condition, then giving examples, the flow, and the exclusion. It is not overly verbose, though it could be tightened by trimming redundant phrasing.

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 an output schema and a clearly described flow. The description explains when to use it and the sequential steps, but it omits pagination behavior (page/limit), which is a minor gap given the output schema likely covers result structure.

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 33%; only 'location' is described, while 'page' and 'limit' are undocumented in both the schema and the description. The description does not mention pagination or add any meaning for those parameters, failing to compensate for the low coverage as required.

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 when to use this tool ('when the user wants to book or hire a renovation'), enumerates specific renovation types, and distinguishes it from DIY advice or price research. It also conveys the flow (provider search → ask → create_booking), clearly separating it from siblings like find_renovation.

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 a clear when-to-use and an explicit exclusion ('Do not use for DIY how-to advice or price research with no hiring intent'). It additionally describes the required sequence of actions (run provider search, ask which pro, then use create_booking), leaving no ambiguity about how to proceed.

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 discloses that the tool may create a real booking request, including for out-of-market addresses, and explains why (provider is verified against the homeowner's owned prior job). It also clarifies the preview/confirm distinction, which is a critical side effect. This matches annotations (readOnlyHint=false, openWorldHint=true) and adds value beyond them by explaining the verification mechanism and the two-step 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 three sentences, with the purpose front-loaded and no wasted words. It efficiently conveys the core action, the authentication requirement, the two-step flow, and the potential side effect—all essential information in a compact form.

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 (8 parameters, output schema present), the description covers the critical behavioral aspects: the preview/confirm flow, the out-of-market caveat, and the verification rationale. It does not detail the output schema, but the presence of an output schema excuses that. It also doesn't enumerate every parameter, but the schema descriptions are comprehensive. The only minor gap is not mentioning how the tool handles the address/location override edge cases, though these are covered in the schema.

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

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

Schema coverage is 88%, and the schema descriptions already provide detailed guidance for most parameters. The main description adds key semantics for `job_id` (from get_previous_jobs) and the `confirm_booking` preview/confirm behavior, which are not apparent from the schema alone. While it doesn't discuss address/location constraints (those are in the schema), it goes beyond the baseline by explaining the most important parameter interactions.

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

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

The description clearly states the verb 'rebook' and the resource: a provider the homeowner has used before, identified by job ID. This distinctly separates it from sibling tools like book_electrician which likely handle new bookings, and from create_booking which may be for new 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 instructs a two-step flow: call with confirm_booking=false to preview, then confirm_booking=true after approval. It also implies when to use this tool (when the homeowner has a prior job with the provider) but does not explicitly contrast it with alternatives like create_booking or book_* tools for new hires. This is sufficient guidance for selecting it in most cases.

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, readOnlyHint=false, and idempotentHint=true. The description goes beyond these by explaining the two-step confirmation workflow and that the reason is delivered to the provider. This adds valuable behavioral context that the annotations alone don't convey, such as the need for explicit approval and the side effect of notifying the provider. It stops short of describing error handling, but for a cancellation tool this is sufficient.

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 and front-loaded with the core purpose. The first sentence states the action; the second explains the two-step flow. Every sentence contributes essential information, with no filler or repetition of schema details. This is an ideal length and structure for an MCP tool description.

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

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

Given that the tool has an output schema (not shown but present) and comprehensive annotations, the description only needs to cover the crucial workflow, which it does. It explains the confirmation step and the provider notification. It does not mention edge cases like when a booking cannot be cancelled (e.g., already completed) or what happens to payments, but these are typically outside the scope of a tool description and can be inferred from the schema and the overall system. The description is complete enough for an agent to correctly invoke the tool in the intended sequence.

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 already provides full descriptions for all three parameters (job_id, reason, confirm_cancellation), including the exact behavior of confirm_cancellation. Since schema coverage is 100%, the baseline is 3. The description adds extra value by framing the workflow across calls (preview then confirm), which clarifies the semantic interaction between confirm_cancellation and the overall cancellation process. This enriches the parameter understanding beyond the individual field descriptions.

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

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

The description states exactly what the tool does: 'Cancel one of the authenticated homeowner's bookings.' It names the actor (homeowner), the action (cancel), and the object (booking). This is specific and distinct from the sibling tools (none of which handle cancellation). The description also hints at the two-step confirmation, which is essential 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 gives clear usage instructions: first call with confirm_cancellation=false to preview, then call again with true after explicit approval. It does not explicitly mention when not to use this tool or compare to alternatives, but since no sibling tool handles cancellation, this is low-risk. The guidance is practical and directly applicable to the tool's domain.

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 idempotentHint=false, but the description elaborates on what that means: confirmed calls are not idempotent and 'may create duplicate requests.' It also discloses authentication requirements, market limitations, and the disclosure to homeowners. This goes well beyond the structured hints, adding genuine 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 a dense but well-structured block. Each sentence adds value, and critical caveats (non-idempotency, market disclosure, ambiguous intent) are front-loaded. It is slightly long but not padded; every clause earns its space.

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 9 parameters, an output schema, and nuanced behavior (preview vs. submit, out-of-market handling, non-idempotency), the description covers all essential usage scenarios, constraints, and prerequisites. Nothing critical is missing for an agent to invoke it correctly.

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

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

The schema already documents every parameter, so the baseline is 3. The description adds extra meaning for confirm_booking (preview vs. submit) and search_result_id (required for confirmed out-of-market bookings), and hints at location usage. This lifts it above baseline for key parameters, but it does not cover all 9 thoroughly.

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

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

The description explicitly states it is a 'Lower-level booking creation' and names five preferred siblings (book_handyman, book_hvac, etc.) for standard workflows. This makes the tool's purpose and differentiation clear without needing to inspect other 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 tells agents to prefer sibling tools for standard categories, warns against ambiguous intent, and describes when to use confirm_booking and search_result_id for out-of-market bookings. This is textbook when-to-use guidance with clear exclusions.

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

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

Annotations already declare read-only/idempotent/non-destructive; description adds that it does not create a booking (distinguishing from book_* siblings) and instructs to call get_my_profile first. No contradiction.

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

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

The description is long but front-loaded with the primary use case, followed by exclusions and behavioral notes. Every sentence adds value; no redundancy.

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

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

Covers when/how to use, exclusions, prerequisites, and location specifics. Output schema handles return shape. Nothing critical missing for an agent to call correctly.

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

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

Schema covers location with detailed description; description reinforces ZIP preference. However, page and limit lack descriptions both in schema (only defaults) and description, leaving 2 of 3 params underdocumented.

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 finds/searches/compares electrician professionals and lists example problems. Distinguishes from sibling trade tools by explicitly naming the electrician 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?

Provides explicit when-to-use (user wants electrician or describes electrician-related problem), when-not-to-use (DIY, cost research without hiring, emergencies), and a prerequisite (call get_my_profile first).

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, idempotentHint, and destructiveHint, so the bar for additional disclosure is lower. The description adds valuable behavior beyond that: it states 'Read-only; does not create a booking' (reinforcing but also specifying the no-booking consequence) and instructs to call get_my_profile first, which gives sequencing behavior. No contradiction with annotations is present.

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-structured; it front-loads the primary use case, includes a comprehensive list of examples to clarify scope, and then explicitly lists exclusions and operational details (read-only, get_my_profile, ZIP preference). Every sentence earns its place, although the example list could be trimmed without losing intent.

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 externally defined) and annotations cover safety profile, the description is remarkably complete. It covers usage triggers, exclusions, read-only nature, a sequencing dependency, and location preference. No critical operational detail is missing for an agent to correctly invoke the tool.

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

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

Schema description coverage is only 33% (only 'location' has a description, and it is quite detailed). The tool description merely repeats 'Prefer a 5-digit ZIP for location' without adding any meaning beyond what the schema already provides. Page and limit are undocumented in both the schema and the description, and since coverage is low, the description fails to compensate for these 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 clearly states the tool's purpose: 'find, search, or compare handyman professionals' and elaborates with specific examples of handyman problems (TV mounting, drywall repair, etc.). It distinguishes from sibling trade tools like find_electrician and find_hvac by explicitly narrowing to handyman services, making it easy for an agent to select the correct tool.

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

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

The description explicitly tells when to use the tool ('when the user wants to find, search, or compare handyman professionals...') and when not to use it ('Do not use for DIY how-to advice, cost research with no hiring intent, auto or appliance retail questions, or emergencies...'). It also provides a prerequisite ('If the user is signed in, call get_my_profile first') and a location preference ('Prefer a 5-digit ZIP for location'), leaving no ambiguity about invocation context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces with 'Read-only; does not create a booking.' It adds the dependency on get_my_profile and location preference, which are useful behavioral details beyond the annotations. No contradiction.

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

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

The description is long but front-loaded with the core usage directive and exclusions. It reads as a structured list of conditions rather than rambling prose. Each sentence adds value; the length is justified by the breadth of HVAC scenarios. Could be tightened but is effective.

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 an output schema present, the return format is covered elsewhere. The description covers usage scope, exclusions, a prerequisite call, and location format. The only gap is lack of guidance on pagination (page/limit), though defaults exist. Overall adequate for correct invocation.

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

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

Schema coverage is only 33%, so the description must compensate. It richly explains the `location` parameter (ZIP preference, postalCode from get_my_profile, forbidden inputs) which is the required param. However, `page` and `limit` have no description in either schema or description; their semantics (pagination) are left unexplained. This is a partial compensation gap.

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

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

The description states a specific verb ('find, search, or compare') and resource ('HVAC professionals'), and enumerates concrete problem scenarios (AC not cooling, furnace won't turn on, etc.). It clearly differentiates from sibling tools like find_electrician and find_plumber by naming the domain. The exclusion for DIY/cost research further clarifies its scope.

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

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

Explicitly states when to use (HVAC problems list) and when not to use (DIY, emergency, retail). It also provides a prerequisite workflow: call get_my_profile first if signed in, and prefer 5-digit ZIP. This is direct, actionable guidance that leaves no ambiguity about 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. The description reinforces this with 'Read-only; does not create a booking', adding specificity about the tool's side-effect-free nature. It also discloses behavioral context about calling get_my_profile first and the location input handling. While it repeats the read-only hint, it adds useful sequencing and input constraints 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 front-loaded with the main purpose and then flows logically: scenarios, exclusions, read-only note, profile call, ZIP preference. The list of problem examples is comprehensive but slightly verbose, yet every sentence adds value. The structure is clear and scannable, with no redundancy beyond the read-only emphasis that is already in annotations.

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 an output schema and rich annotations, the description covers all essential context: when to use, when not to, prerequisites (get_my_profile), input format constraints (ZIP), and side-effect transparency. Pagination defaults are evident from the schema, and the output schema obviates the need to describe return values. The description is complete for the agent to 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?

Schema coverage is only 33% (only location has a description), so the description must compensate. It does thoroughly for the critical location parameter, explaining the preferred 5-digit ZIP format, how to use the postalCode from get_my_profile, and explicitly forbidding street addresses. However, the other two parameters (page and limit) are not mentioned in the tool description at all, relying on their defaults and common meaning. Since location is the primary parameter and is well covered, this is strong compensation, but the omission of pagination semantics prevents a perfect score.

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: 'find, search, or compare plumber professionals' and lists concrete problem examples (leaky faucet, clogged drain, water heater repair, etc.). It is clearly distinguished from siblings like find_electrician and find_hvac by the explicit plumber focus and the problem list, making selection 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 states when to use the tool ('Use when the user wants to find, search, or compare plumber professionals, or describes a problem a plumber solves'), and gives clear exclusions ('Do not use for DIY how-to advice, cost research with no hiring intent, auto or appliance retail questions, or emergencies requiring 911'). It also provides sequencing guidance ('If the user is signed in, call get_my_profile first') and a location preference ('Prefer a 5-digit ZIP'). This is exemplary guidance with no ambiguity.

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=true, so the description's 'Read-only; does not create a booking' reinforces that fact. However, the description adds valuable behavioral context beyond annotations: 'If the user is signed in, call get_my_profile first' and the preference for ZIPs. This goes beyond the structured data, though the core read-only nature is already annotated.

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 bit long but front-loads the primary use case and exclusions. Every sentence serves a purpose: defining the tool, listing use cases, listing exclusions, stating read-only behavior, and giving call-sequence guidance. It is structured and efficient, though slightly 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?

Given the tool's simplicity and the presence of an output schema, the description covers the critical aspects: when to use, when not, read-only nature, location handling, and the get_my_profile prerequisite. It does not explain pagination or output structure, but those are minor given the output schema and defaults. Overall, an agent has enough to call correctly.

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

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

The schema covers the location parameter well with examples and a note about preferring a 5-digit ZIP, and the description amplifies that. But page and limit have no description in the schema and are not mentioned in the tool description. With only 33% schema coverage, the description should at least acknowledge pagination parameters. It does not, leaving the agent to guess their meaning.

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

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

The description states a specific verb set ('find, search, or compare renovation professionals') and a resource (renovation professionals), then enumerates concrete scenarios (kitchen remodel, bathroom remodel, etc.) that clearly distinguish it from sibling find_* tools like find_electrician. It leaves no ambiguity about scope.

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

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

Explicitly states when to use (user wants to find/search/compare renovation pros or describes a renovation problem) and when not to (DIY advice, cost research without hiring intent, auto/appliance retail, emergencies). It also gives actionable preconditions: call get_my_profile first and prefer a 5-digit ZIP. This is exemplary guidance for an 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 declare readOnlyHint=true and destructiveHint=false, and the description restates this ('Read-only; does not create a booking') with little added value. The genuine addition is 'Requires authentication,' which is useful operational context not present in the annotations. The bar is lowered by the richer annotations, so a 3 reflects the one meaningful behavioral disclosure 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 short sentences with the core action front-loaded and zero filler. Each sentence earns its place: the action, the auth requirement, and the safety clarification. Nothing is redundant enough to warrant cutting.

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

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

For a single-parameter read tool with an output schema that covers return values, the description is largely complete: it states the action, the auth prerequisite, and the read-only behavior that annotations reinforce. The only gap is the undocumented booking_id format, which is minor given the schema already declares the required string parameter.

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 must carry parameter meaning, but it only adds 'by ID,' which merely reinforces the existing parameter name booking_id and title 'Booking Id'. It offers no format guidance (e.g., UUID, numeric, or where the ID originates), so it fails to compensate for the schema gap.

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

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

The description states a specific verb and resource ('Check the current status of a HireNimbus booking by ID') that exactly matches the tool name and identifies the lookup scope. It clearly separates this from all siblings: none of the book_* or find_* tools read a booking's status, so an agent can disambiguate without inspecting 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?

The description gives an explicit prerequisite ('Requires authentication') and an explicit exclusion ('does not create a booking') that routes the agent away from create_booking when the goal is creation. It does not name a direct alternative, but no sibling performs this exact read, so the guidance 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 read-only and idempotent, and the description reaffirms this. It adds rich behavioral detail: the exact JSON fields, status/error handling, and the specific logic for extracting and validating the ZIP from the address. This goes well beyond structured 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 minimal, but every sentence carries functional weight: usage context, output schema, and decision logic are clearly separated with bullets. It is front-loaded with the 'when to use' instruction. Slightly verbose but efficient for the complexity it covers.

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 fully explains the output schema (with field names and types), error semantics, and the exact next-step logic for both presence and absence of postalCode. An agent has everything needed to call and correctly use the result without ambiguity.

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

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

The tool has zero parameters, so there is nothing to explain. The description instead focuses on output semantics and usage, which is the natural substitute. Baseline for no params is high, and the description completely handles the tool's input-less nature.

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 returns the authenticated homeowner profile and explicitly positions it as the first call in find, search, compare, or book flows. It distinguishes itself from siblings by naming search_providers and create_booking as subsequent steps, making its role 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 gives explicit when-to-use instructions (start of any flow, before asking for ZIP, before search_providers or create_booking) and detailed step-by-step handling of the return value, including what to do if postalCode is missing. It effectively routes the agent and explains decision points.

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 read-only, idempotent, and non-destructive. The description adds the behavioral requirement of authentication ('Requires authentication'), which is not present in the annotations, and reinforces the read-only nature. This adds value beyond structured fields without contradicting them.

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

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

The description is three sentences long, with the core purpose front-loaded in the first sentence. Every sentence earns its place: purpose, usage context, and a clarifying safety note. There is no redundancy or filler.

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

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

Given the tool's simplicity (no parameters, no nested objects) and the presence of an output schema (so return format is already specified), the description is fully sufficient. It covers what the tool does, when to use it, authentication needs, and its read-only nature — nothing an agent needs to invoke it correctly is missing.

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

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

The tool has zero parameters, and schema coverage is trivially 100%. With no parameters to document, the description has no obligation to explain them. Per the calibration rules, the baseline for zero parameters is 4, and the description appropriately avoids adding unnecessary parameter details.

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: 'Return past and active jobs for the authenticated homeowner.' It clearly distinguishes this tool from the sibling booking/search tools by focusing on job history, and explicitly sets its scope to past and active jobs.

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

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

The description provides explicit usage contexts: 'Use after search when augmenting recommendations, or when the user asks about job history.' It also clarifies a negative use case by noting it 'does not create a booking,' effectively routing the agent away from misuse.

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 destructiveHint, so the safety profile is covered. The description adds valuable context: it confirms the read-only nature and explicitly states it does not create a booking, and it describes the return content (ratings, reviews, past work, availability) with a caveat that some fields are 'where available'. This goes beyond annotations without contradicting them.

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

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

The description is two sentences with zero redundancy. It front-loads the core purpose, then gives usage context and return highlights, and closes with a read-only note. Every clause adds value and the structure is easy to parse for an agent.

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 param) and the presence of an output schema, the description covers the essential aspects: what it does, when to use it, what it returns (with 'where available' caveat), and its non-destructive nature. It omits details like authentication or error handling, but these are not critical for a read-only detail fetch and are likely implied by the output schema.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter meaning. It mentions 'by slug' but does not define what a slug is or its format. However, the instruction to use it after find/search tools implies the slug comes from those tools, providing indirect context. For a single simple string parameter, this is adequate but not thorough.

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 action ('Fetch the full profile'), the resource ('HireNimbus service provider'), and the method ('by slug'). It explicitly differentiates from sibling tools by naming the find/search tools it follows and the context when it is needed, making the tool's 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 provides explicit usage guidance: use after specific find/search tools when more detail is desired. It also mentions what the tool does not do ('does not create a booking'), effectively giving a when-not-to-use signal. This exceeds the minimum by naming alternatives and the intended workflow sequence.

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 and destructiveHint=false, covering safety. The description adds 'does not create a booking,' which reinforces but does not extend beyond the annotations. It does not discuss pagination behavior or potential side effects, but given the annotations and simple read-only nature, this is adequate. No contradiction exists.

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 long, front-loaded with the core purpose, and contains no fluff. Every sentence earns its place, making it easy 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 is simple (3 parameters, 1 required), has an output schema, and annotations cover safety. The description provides the essential usage context and clearly indicates read-only behavior. Missing details about pagination or edge cases are minor given the output schema and self-explanatory parameters. Overall, it is sufficiently complete for an agent to call correctly.

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

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

Schema description coverage is 0%, so the schema provides no parameter explanations. The description only mentions 'slug' and does not address 'page' or 'page_size.' While the parameter names are somewhat self-explanatory, the description fails to compensate for the lack of schema descriptions, especially for pagination parameters. This is a notable gap.

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

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

The description clearly states 'Fetch reviews for a HireNimbus service provider by slug.' It specifies the verb (fetch), the resource (reviews), and the key input (slug). This distinguishes it from sibling tools like booking or provider-finding tools, leaving no ambiguity about what the tool does.

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

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

It provides context: 'Use when the homeowner wants to see what other homeowners have said about a provider before booking.' This indicates a typical use case. It does not explicitly name alternative tools, but the presence of distinct sibling tools for booking and searching makes the intent clear. The statement 'Read-only; does not create a booking' further clarifies that it should not be used for actions.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description aligns without contradiction. It adds supplementary operational details: explicitly states 'Read-only; does not create a booking,' notes that results outside supported launch markets can still be booked, and instructs telling the homeowner about launch markets. It also mentions the search_result_id in the response, adding context beyond the safety profile.

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 multi-sentence but well-structured and front-loaded with the core purpose and usage context. Each sentence delivers distinct information: category scope, location rules, safety note, alternative tools, market caveat, and booking link. The length is justified by the need to cover multiple operational aspects 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?

This is a complete specification for a search tool. It covers when to call, how to format location, how to handle ambiguity, what to do about launch markets, and the booking follow-up using search_result_id. Since an output schema exists, the description needn't detail return values beyond usage, and it does so. No critical information is missing for an agent to make correct decisions.

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 covers 50% of parameters with detailed descriptions for query and location, including examples and constraints. The description repeats and reinforces these (e.g., location format, postalCode fallback) but introduces no new parameter semantics. For page and limit, no additional meaning is provided. Since the schema already handles the critical parameters well, the description adds marginal value, aligning with the baseline for moderate 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 function: searching for home service providers outside the five dedicated find_* categories, with explicit examples (cleaning, landscaping, roofing, etc.) and the 'ambiguous' case. It distinguishes itself from sibling tools by naming the find_* alternatives and specifying when each should be used, satisfying the verb+resource+scope requirement.

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 (non-find categories or ambiguous) and when not to (prefer dedicated find_* tools for handyman, HVAC, plumber, electrician, renovation). It also gives concrete location guidance (5-digit ZIP, never street address) and explains the follow-up action (pass search_result_id to create_booking), fully covering when and how to use it.

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