Nadveo — book air-conditioning service

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

Annotations declare idempotentHint=true, but the description goes well beyond them by spelling out the exact idempotency semantics: same key or same data returns the same booking, and the token is only re-issued with the same idempotency_key. It also discloses a real side effect the annotations don't capture — the company messages the client on WhatsApp or e-mail — and states the return values.

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

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

Front-loaded with the action and its prerequisites, and nearly every sentence carries information. The final idempotency/retry sentence is long and clause-dense, which costs a little readability, but nothing is genuinely redundant.

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 14-parameter mutation with a nested `diagnosis` object and no output schema, the description covers the missing pieces: it explains the return (request number + status token), the chain of prerequisite calls, and the retry contract. Nothing an agent needs to invoke or recover from this call is absent.

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 already 93%, so most parameters are self-documenting and the baseline is 3. The description still adds genuine meaning on top: it explains what `company` must be sourced from, why to send an `idempotency_key`, and how email vs. WhatsApp delivery is selected. It stops short of touching the less obvious params like district, units, and answers, leaving those entirely to 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?

States a specific verb and resource ("Books the visit") and anchors both inputs to their producing siblings (company from find_companies, slot from check_availability). An agent can distinguish this from get_quote, diagnose, and check_availability without opening any schema.

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

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

Gives an explicit precondition chain — only after the client confirmed the service, time, address and price — and names the sibling calls that must precede it. It also names the downstream tools (get_request_status, cancel_request) whose token this returns, which routes the agent forward.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds useful provenance context (token comes from book_appointment, company from find_companies) but doesn't disclose what the cancellation destroys or whether previously booked data is recoverable, so it adds only modest value beyond annotations.

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

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

Short, so nothing is padded, but it reads as three disconnected fragments and the main purpose ('Cancels the booking') is buried in the second sentence rather than front-loaded. Structure is functional but not clean.

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

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

For a simple 2-parameter, no-output-schema tool with annotations present, the description supplies the two things an agent actually needs: where the parameters come from and the precondition for calling it. Return format need not be explained since no output schema exists and the effect is a cancellation.

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 50% and the token param has no schema description, so the description carries real weight here. It explains both parameters' origins: `company` comes from a find_companies result and token comes from book_appointment, which goes beyond what the schema states.

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

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

States a specific verb and resource ('Cancels the booking') and situates it in a workflow by naming siblings find_companies and book_appointment. An agent can tell this apart from read tools like get_request_status. Slightly weakened by the fragmented structure and the fact that the first sentence leads with a parameter concern rather than the action.

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

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

Gives one precondition — '(only when the client asked to)' — which constrains when to invoke it, plus a flow dependency on book_appointment's token. But it names no explicit alternative (e.g. get_request_status for tracking an existing request), so the when-not guidance is only partially 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=true and openWorldHint=false, so the safety profile is covered. The description adds real behavior the annotations don't: results start tomorrow, the horizon is day-count based, times are the company's local timezone, and each entry carries a slot_id consumable by book_appointment.

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?

Short and front-loaded, with the prerequisite and the downstream consumer stated early. The telegraphic fragments and stacked parentheticals (e.g. 'At the company chosen from find_companies (pass its `company`).') make it slightly harder to parse than needed but nothing is 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?

For a 5-parameter read tool with a nested answers object and no output schema, the description covers all the non-obvious requirements: where inputs come from, that nested answers/units change slot duration, the timezone of returned times, the starting day, and the slot_id return field. Nothing essential to a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the causal relationship the schema only hints at — answers and units determine how long the work takes, which is why they affect availability. It also reinforces the provenance of `company` and `service`.

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

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

States the resource precisely (free start times for a service at a company) with scope qualifiers: from tomorrow, over the next N days, in the company's local time. It also distinguishes itself from siblings by naming find_companies as the input source and book_appointment as the consumer of the returned slot_id.

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 call chain is explicit: get `company` from find_companies, `service` from list_services, then pass the returned slot_id to book_appointment. That gives clear when-to-use context, though there are no explicit exclusions or failure-mode guidance (e.g. what to do when no slots exist).

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 openWorldHint=false, consistent with a lookup of a chosen company. The description adds real value beyond them by enumerating what is returned (name/location, currency, languages, contacts, rating, districts with service-level meaning, current local date, booking page).

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 usage precondition is front-loaded and the field inventory is one dense sentence with no filler. It is slightly list-heavy but every clause describes actual returned data.

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

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

With no output schema, the description must convey return values, and it does enumerate them well for a simple two-parameter read tool. Only minor gaps remain, such as whether the call can fail for an unknown company.

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

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

Schema coverage is 100%, so both parameters are already documented, including the lang enum list. The description reinforces where `company` comes from but adds no syntax or format detail beyond the schema, matching the baseline-3 case.

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 makes clear this is a read/return-details tool scoped to a single company, and explicitly ties it to find_companies ('company chosen from find_companies'). That gives sibling differentiation, though the opening phrasing 'At the company chosen from...' is grammatically odd rather than a crisp verb+resource statement.

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 the selection context and precondition: use the company picked from find_companies and pass its `company` value. Coverage is clear but there are no exclusions or named alternatives, so it stops short of full when/when-not guidance.

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

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

With readOnlyHint=true already covering safety, the description adds real behavioral context: the output is a preliminary hint, the technician confirms cause and final price on site, and a consent precondition (client_accepted_disclaimer) is mandatory. That consent-and-caveat workflow is nowhere in the annotations or schema and is essential to invoking it correctly.

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

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

Dense but front-loaded: the core purpose and the find_companies dependency lead, and the consent instruction follows. It is a single long passage rather than cleanly segmented sentences, so it is slightly harder to scan than it could be, but no sentence is filler.

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

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

For a 5-parameter, no-output-schema tool this is complete: it names the inputs' origins, the brand vocabulary, the consent workflow, the cross-tool linkage to book_appointment, and what the response conceptually contains (probable cause plus starting price). An agent has everything needed to call it and to sequence it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema lacks: the full enumerated set of brand keys (the schema declares no enum and only says 'see the description'), and the provenance of `company` (a find_companies result). `code`, `lang`, and the consent flag are already well documented in 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?

States a specific verb+resource: returns a probable cause (breakdown type) and starting price given an AC brand and display error code. It also explicitly frames what it is NOT ('It is not a diagnosis'), which separates it from an authoritative diagnosis in a way an agent can act on.

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

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

Gives clear preconditions: the company must come from find_companies, the client must be told it is an automatic hint and must agree before the call, and the flag must be reused in book_appointment. It does not name any sibling to use instead nor any exclusion case beyond 'not a diagnosis', so it stops short of the top of the scale.

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 openWorldHint=false. The description adds substantial context beyond that: it explains returned attributes such as districts, from-prices, next free day, ratings, and the meaning of badges like quote_hours and amc. It does not mention pagination, result limits, or how 'best first' is computed.

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 front-loads the core purpose and resource. The badge definitions are long but earn their place because no output schema exists. The single long sentence could be split for readability, but there is no wasted filler.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly by naming districts, prices, availability, ratings, and badges. It lacks pagination or limit details, but the schema also has no such parameters, so the remaining gaps are minor.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema. The description reinforces the country filter with an ISO example but adds no parameter-specific meaning beyond what the schema provides, making 3 the correct baseline.

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

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

The description clearly states a specific verb and resource: service companies in the Nadveo catalog, filtered by several attributes and returned best-first. It does not explicitly distinguish itself from the sibling company_info tool, so it misses the top mark.

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

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

Usage is implied by the list of filters and the phrase 'filtered by', but the description never states when to choose this search tool over company_info or list_services. An agent can infer it is for discovery, but explicit routing guidance is absent.

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 openWorldHint=false, so safety is covered. The description adds real behavioral value by disclosing the error-reporting contract: a missing or wrong answer surfaces in a "problem" field naming the question, which an agent needs in order to retry correctly.

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 prerequisite and the return contract front-loaded; nothing is padding. The opening clause is a sentence fragment ("At the company chosen from find_companies (pass its company)") that reads awkwardly, but it is still efficient.

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 calculator with a nested answers object and no output schema, the description covers the essentials: inputs' provenance, the returned price/duration, and the "problem" validation output. It could say more about how units/answers interact for counted services, but nothing critical to 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?

Schema description coverage is 100%, so all five parameters (including lang, units, and the nested answers object) are already documented. The description's note that answers are checked against the service's questions echoes the schema rather than adding new semantics — baseline 3 applies.

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

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

States a specific verb and outcome: it checks the client's answers and returns price and duration. It also names its upstream dependency (find_companies) and the failure field ("problem"), so an agent can tell exactly what this tool produces versus siblings like list_services or book_appointment.

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?

Implies the required workflow order by saying the company comes from find_companies and the service key from list_services, which is genuine when-to-use guidance. It does not state any exclusions (e.g., that it does not reserve a slot — use book_appointment for that), so it falls 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: what data is returned and the fact that the technician field is only populated 'once assigned'. It does not discuss token expiry, rate limits, or error 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?

Two short sentences with no filler, and the dependency (which company) is front-loaded. The phrasing is somewhat telegraphic and fragmented, costing a little clarity, but nothing extraneous is included.

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, two-parameter tool with no output schema, the description covers inputs and the shape of the return, which is the main thing missing from structured fields. Minor gaps remain around failure/error cases and token lifetime.

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 coverage, the description compensates by explaining the provenance of both parameters: `company` comes from a find_companies result and `token` comes from book_appointment, topics absent from the schema itself (the token property has no description at all).

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: retrieve where a booking stands, enumerating the returned fields (status, time, technician, price). It is clearly distinguishable from siblings like cancel_request or book_appointment, though it doesn't explicitly contrast itself against them.

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

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

It implies the prerequisite workflow by stating the inputs must come from find_companies and book_appointment, which tells an agent when the tool is callable. However, it never states when NOT to use it or names a competing sibling (e.g., cancel_request) for adjacent needs.

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 openWorldHint=false, and the description is consistent with a pure read. Beyond that it discloses return-field semantics that annotations cannot carry — that questions affect price and time, that `shown_if` creates answer-dependent branching, and that `?` is valid where `unknown_allowed` is set. It does not mention currency or pagination, so it is not fully exhaustive.

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 content is dense but front-loaded: the required input source comes first, then the return payload, then the edge-case vocabulary. The opening is a sentence fragment and the parentheticals make it slightly telegraphic, but every clause carries information and nothing is 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?

There is no output schema, so the description bears the burden of describing the return shape, and it does so concretely (price, duration, bookable flag, question list, conditional questions, `unknown_allowed`). Minor gaps remain around currency/units and whether the list is complete or paged.

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

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

Schema description coverage is 100% and both parameters are already documented in the schema, including the `company` field's origin in a find_companies result. The description's note about passing `company` largely restates the schema, and it never mentions `lang`. Baseline 3 applies when the schema does the heavy lifting.

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 enumerates exactly what is returned per service: starting price, duration, bookability, and the client intake questions, plus the semantics of `shown_if` and `unknown_allowed`. It does not literally name the listing verb, but the resource and payload are unambiguous and it is clearly distinguished from siblings like get_quote or check_availability, which return computed/availability data rather than the catalog.

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 ties itself to the preceding step ('At the company chosen from find_companies (pass its `company`)'), establishing the workflow ordering and the required input source. It stops short of naming when NOT to use it or contrasting with company_info/get_quote, so no exclusions are present.

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 a non-readonly, open-world, non-idempotent, non-destructive mutation. The description adds real context beyond that: the company writes the quote itself, delivery goes to the client over WhatsApp or e-mail when supplied, and the agent should tell the client so. It doesn't touch duplicate submissions or failure modes, so it stops short of a 5.

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 scope and the routing to find_companies/list_services are front-loaded, and the fallback to book_appointment comes after the primary path. It is dense and long for a single call, and the terse '— say so' instruction costs a moment of parsing, but no sentence is pure 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?

For a 10-parameter mutation with a nested answers object and no output schema, the description covers the full pre-call chain (select company, select service, confirm with client) and the alternative flow. What it omits is what the call yields — a request identifier the agent would need for get_request_status — leaving the post-call step unstated.

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 90% schema coverage the baseline is 3; the description still adds meaning by tying `company` to the find_companies result, restricting `service` to quote-request bookings from list_services and noting it may be omitted when only one exists, and noting photos and e-mail are optional/conditional. The nested `answers` object is left to 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 concrete verb and resource — it sends a job description, contact data and photos to a chosen company so that the company itself writes a quote. It explicitly separates this from fixed-price work and names the sibling escape hatch (book_appointment with an «assessment visit» service), so an agent can tell it apart from get_quote and book_appointment.

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 preconditions (company chosen from find_companies, only after the client confirmed the description and contact), the required service selection rule ('required when it lists more than one'), and a named alternative path for companies without a quote-request service. When-to-use and when-not-to-use are both present.

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