Entervista

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

Goes well past the annotations (readOnly=false, openWorld=true, non-idempotent) by disclosing the state machine outcome: the request is submitted to the business, and if online payment is enabled the result is awaiting_payment with a payment_url the agent must hand to the customer. This is exactly the kind of operational detail annotations cannot express.

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

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

Three short sentences, front-loaded with the gating condition and then the two runtime branches. Every sentence earns its place and none repeats the schema or 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?

With no output schema, the description correctly compensates by describing the resulting status and payment_url. The only gap is the unexplained ref and customer_token parameters, which an agent must infer from the sibling toolchain.

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

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

Schema description coverage is 0%, so the description must carry the burden for all three params. It does well for slot_start (pass the chosen slot_start when offered_slots is present), but ref and customer_token receive no semantic explanation at all, leaving two required-ish inputs undocumented.

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

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

Specific verb (approve) plus resource (the request/quote), with the precondition and the downstream effect ('Sends it to the business') spelled out. It is clearly distinct from cancel_request and request_quote, though it never names a sibling explicitly to route the agent.

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?

'Use only after the customer explicitly approves the total / quote / final price' is an explicit when/when-not gate, and the offered_slots clause tells the agent exactly what to pass in that condition. Nothing about the trigger is left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds a genuinely non-obvious behavioral trait: the result is a draft awaiting customer approval, not a committed booking, which materially changes how an agent should treat the response.

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 dense sentences, front-loaded with what the tool does and immediately followed by the outcome (draft). No filler.

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

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

For a mutation tool with no output schema, the description usefully discloses the return (a draft pending approval), which is the key completeness win. However, gaps remain: the required slug/customer inputs and any failure modes (slot taken, service-area mismatch) are unaddressed, and 40% schema coverage leaves required fields under-explained.

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 40% across 5 params, so the schema undersells several fields. The description indirectly clarifies slot_start ('slot from get_availability') and loosely maps service_sku to the flat-rate service, but slug and the required customer fields get no meaning beyond the schema's own partial description. It helps but doesn't fully compensate.

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 ('Book a flat-rate service') and scopes it to fixed-price/services contrasted against siblings like request_quote and place_order. The parenthetical example ('e.g. drain cleaning') makes the service class concrete without opening the schema.

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

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

Explicitly ties slot_start to 'from get_availability', routing the agent through the sibling prerequisite, which is real when-to-use guidance. It doesn't state when NOT to use it (e.g. vs place_service_request or request_quote), so it stops short of the top band.

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=false, openWorldHint=true, so the safety profile is covered structurally. The description adds the authorization framing ('on the customer's behalf'), which hints that a customer identity is required, but says nothing about reversibility, side effects on the order/booking, or whether the action can be undone.

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?

A single front-loaded sentence with no filler or repetition. It is efficiently sized, though the brevity reflects under-specification rather than deliberate economy.

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

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

For a destructive, non-idempotent mutation with three undocumented parameters and no output schema, the description is too thin. It omits the meaning of the required ref and customer_token, whether reason is optional or recorded, and what happens to the cancelled resource.

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% across three parameters, so the schema documents nothing and the description must compensate — yet it never mentions 'ref', 'reason', or 'customer_token'. At best it implies that the ref targets an order, quote, or booking, which is only marginal semantic value.

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

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

The description states a specific verb ('Cancel') and concrete resources ('an order, quote or booking'), which is far more informative than the tautological title. It does not, however, explicitly differentiate itself from the sibling approve_request or other request-manipulation 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?

There is no statement of when to use this tool versus alternatives, no prerequisites, and no exclusions. The phrase 'on the customer's behalf' hints at the actor but gives no guidance on the conditions under which cancellation is appropriate.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is low. The description adds real value beyond that: it characterizes the answer as deterministic and discloses the response shape (reason, served zips, excluded zips, alternative businesses on a no).

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?

A single front-loaded sentence with the verdict semantics first and the return payload second. No filler, no redundancy with the title.

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 usefully covers what comes back and does so in one clause. However, for a 3-parameter tool it leaves the emergency parameter's semantics entirely unaddressed, which is a meaningful gap for correctness.

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%: zip is documented in the schema, but slug and especially emergency are not. The description implicitly ties 'this business' to slug and 'customer's zip' to zip, but it says nothing about what the emergency flag does, so the largest documentation gap goes unfilled.

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 precise verb and resource: a deterministic yes/no on whether a business serves the customer's zip. This is uniquely distinguishable from siblings like get_business or search_businesses, which return entity or list data rather than a coverage verdict.

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 yes/no framing, but there is no explicit statement of when to call this versus search_businesses, get_service_requirements, or get_availability, and no stated prerequisites. It is adequate but leaves routing to inference.

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

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

Annotations already cover read-only, idempotent, non-destructive semantics, so the bar is lower, and the description adds real value: the confidence field can be 'stale with a note', and critically it warns that 'the slot is held the moment the draft is created'. That hold side-effect is exactly the kind of context annotations cannot 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?

Purpose is front-loaded and every sentence carries information, but the inline enumeration of operating_state values makes the middle dense and run-on. Slightly overloaded, yet no sentence is wasted.

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 does the work of describing returns (operating_state, confidence, earliest, price, auto-book behavior). This is thorough for an availability tool; the main remaining gap is the unexplained required slug 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?

Schema coverage is only 50% (slug and service_sku are undocumented in the schema). The description compensates well for service_sku by explaining it sizes windows for the service's duration and crew, but leaves slug entirely unexplained and adds nothing about date/days beyond their schema text.

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 precise verb+resource: it returns 'live bookable windows over the next days' and names the underlying schedule sources (hours, crew, jobs, holds, blocks). This distinguishes it clearly from siblings like get_business or get_services.

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 explains when to pass service_sku (to get windows sized for that service's duration and crew) and routes the agent downstream to place_service_request or book_slot using a slot's start. It doesn't explicitly state when NOT to use it, but the context and alternatives are clear.

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

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

Annotations already establish readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. With no output schema, the description usefully carries the return-value burden by itemizing what the profile contains, though it says nothing about auth requirements, missing-slug failure behavior, or payload size.

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?

One dense sentence that front-loads the payload contents; every listed item maps to a real section of the profile. It is slightly list-heavy but wastes no words on boilerplate.

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 tool with no output schema, the description adequately conveys what comes back and where it fits in the order/quote/book flow. The remaining gap is the undocumented slug parameter and the lack of sibling differentiation, both relatively minor given the annotations carry the safety profile.

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% — the single required 'slug' parameter is undocumented in both schema and description. The description never mentions the identifier at all, so it fails to compensate for the coverage gap by explaining how a slug is obtained or formatted.

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 the resource clear — a single business's full agent-readable profile — and enumerates the payload (identity/license, services with prices, hours, zips, delivery rules, policies, next actions). However it never states an explicit retrieval verb and does nothing to distinguish itself from siblings like get_services, get_service_requirements, or search_businesses.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no mention of how this differs from get_services or search_businesses. The phrase 'exactly how to act (order, quote, or book)' only implicitly signals that this is the discovery step before place_order/request_quote/book_slot, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description's polling instruction is consistent with idempotency and adds mild context, but it says nothing about authentication (customer_token) or rate limits on polling.

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 tight sentences: the return payload is front-loaded and the usage cue follows. No filler, nothing repeated from the title.

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?

Annotations carry the safety profile and there is no output schema, so the description covers returns and polling adequately. However, with 0% parameter coverage it leaves the meaning and source of 'ref' and 'customer_token' unexplained, which is a real gap for a required-parameter 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 0% and the description mentions neither parameter. The required 'ref' is never explained (request reference? order id?) and 'customer_token' is entirely undocumented, so the agent must guess at both.

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

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

The description names a specific resource (a request) and enumerates what the read returns: current status, ETA/arrival window, business response, and next step. It is clear what the tool does, though it never contrasts itself with siblings like get_business or get_service_requirements.

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?

'Poll this while waiting on a business' gives a concrete usage context and implies repeated invocation is expected. It stops short of naming when not to use it or which sibling to prefer 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, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful context the annotations cannot: that the response enumerates the exact fields to ask the customer, their types/options, the pricing flow, and the follow-up steps. With no output schema, this return-shape disclosure carries real weight.

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

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

One densely packed sentence with the usage cue front-loaded and zero filler. It is efficient, though the parenthetical enumeration of return fields makes it slightly harder to scan than a purely front-loaded statement.

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 sensibly explains what comes back, and it conveys the pre-request purpose. The remaining gap is input-side: two required, undocumented parameters are left ambiguous, which matters for a lookup keyed on identifiers.

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% and neither parameter (slug, service_sku) is explained anywhere. The phrase "for this service" hints that the params identify a service, but it gives no indication of why both a slug and a service_sku are required or where each comes from, so the description fails to compensate for the documentation 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 concrete resource (the questions/requirements for a specific service) and what payload it returns (required_fields/optional_fields with type and options, plus pricing flow and next steps). It reads as a read/lookup tool and is distinguishable from get_services (which lists services) and place_service_request (which consumes these requirements), though it never names those siblings explicitly.

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?

"Before creating a request" gives a clear temporal trigger that maps onto the sibling place_service_request, so an agent knows the ordering. It does not, however, state any exclusions or name the alternative tools directly, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered elsewhere. The description adds the useful return-shape detail (pricing modes, inclusions, intake fields) in the absence of an output schema, but says nothing about pagination, scoping, or what happens if the slug is unknown.

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?

A single efficient sentence with no filler, and the most decision-relevant content (pricing mode) is front-loaded. It is diminished only by the missing verb, which makes the sentence read as a fragment.

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, enumerating returned fields is the right move and it is done reasonably well. However, the required slug parameter and its meaning are entirely undocumented, leaving a real gap 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?

The only parameter, slug, has 0% schema description coverage and is never mentioned in the description. The description cannot compensate for the gap because it does not explain what the slug identifies or whether results are scoped/filtered by it.

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 returned fields (pricing mode, price, inclusions, intake requirements) but never states the action as a verb; it reads as a noun phrase about returned data rather than 'list services for a business.' It also blurs with the sibling get_service_requirements, which appears to cover the 'required intake fields' this description claims.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives despite several nearby read siblings (get_business, get_service_requirements, search_businesses). The agent must infer selection context entirely from the name.

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

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

Annotations declare non-read-only, non-idempotent, open-world, non-destructive, but the description adds the crucial trait they do not: this is a draft that has no effect on the business until approval. It also previews the returned ref/customer_token, which helps the agent chain calls.

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, front-loaded with the core behavior, then the approval dependency, then the confirmation step. No filler.

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

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

Covers the lifecycle and return shape well for a tool with no output schema, but with nested objects and low schema description coverage it leaves key input semantics (slug meaning, fulfillment choice, item/option modeling) to inference.

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 40% across 5 params (4 required, one nested item array and a nested customer object), so the description must compensate and does not. It never explains slug, items, fulfillment, requested_time, or the customer structure beyond a schema-level hint.

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

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

Specific verb+resource ('Draft an order') with the domain scoped as food/retail, and it distinguishes itself from the finalizing sibling by noting nothing reaches the business until approve_request. Clear, though it never disambiguates against place_service_request or request_quote in the sibling list.

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 concrete workflow context: draft here, then approve_request to send, and 'Ask the customer to confirm the total first.' That is real when-to-use guidance, but there is no explicit when-not or comparison against the other request-creation siblings.

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

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

Annotations already declare non-readOnly, non-destructive, non-idempotent and open-world, so the safety profile is covered. The description adds genuinely useful context beyond that: the call returns a draft (with total or estimate, windows, ref, customer_token) and nothing is committed to the business until approve_request is called.

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?

A single dense paragraph that front-loads the core purpose ('One call for any trade job') then lists inputs and return behavior. It is information-rich with little waste, though the run-on parameter enumeration is somewhat heavy.

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 an 11-parameter, nested-object tool with no output schema, the description does explain return shape and the draft/approve lifecycle, which is valuable. But it omits the required 'slug' parameter and several optional inputs, so an agent cannot fully assemble a valid call from the description alone.

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 55% and 11 parameters exist, so the description carries meaningful burden. It explains service_sku vs description matching, intake_answers field ids, customer, preferred_time and slot_start, but never mentions the required 'slug' parameter nor notes, photos, urgency or referred_by, leaving key inputs undocumented.

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

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

States a specific verb (place) and resource (service request) and scopes it as 'one call for any trade job (repair, quote, booking)', which helps distinguish it from narrower siblings like request_quote and book_slot. It does not fully differentiate from place_order, but the trade-service framing is clear.

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?

Implied usage is conveyed through cross-references ('intake_answers keyed by the field ids from get_service_requirements', 'slot_start when the flow is book_then_pay', 'Nothing reaches the business until approve_request'), which sketches the workflow. However, it never explicitly says when to choose this over the sibling alternatives place_order or request_quote.

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 the write-safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description adds genuinely new behavioral context: that responses are asynchronous and split between instant estimates with bookable slots and delayed replies governed by a stated response time. That is real value beyond the annotations.

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

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

Three short sentences with the primary action front-loaded and the next-step hint trailing naturally. No filler, though the parenthetical poll instruction is slightly compressed and could name the tool context more explicitly.

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 usefully sketches the possible response shapes (estimate + slots vs. delayed reply), which is the right thing to cover. But for a 7-parameter mutation with a nested customer object and 57% schema coverage, too many inputs and behaviors (auth needs, idempotency implications) remain unexplained.

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 57%, and the description only touches the 'description' parameter obliquely via 'plain English'. It says nothing about slug, urgency, photos, preferred_times, service_sku, or the nested customer/address object, so it does not compensate for the coverage gap. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Ask a service business... for a price') with a concrete domain example. It is clearly distinguishable from retrieval siblings like get_business or search_businesses, though it does not explicitly differentiate from the closely-named place_service_request or place_order.

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 usage ('Describe the problem in plain English') and routes the agent to a follow-up action ('poll get_request_status'), which is useful. However, it never states when to prefer this over the near-identical siblings place_service_request or place_order, leaving the core selection choice to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine value with the return content ('starting prices and whether they serve the zip'), which matters because there is no output schema. It stops short of describing result limits, ranking, or pagination.

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

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

Two sentences, zero filler: the core purpose and examples come first, followed by the filters and the return summary. Every clause earns its place.

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

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

For a 7-parameter search tool with no output schema, the description covers the query intent and return fields well but leaves the accepts enum, the lat/lng vs zip vs location relationship, and result-size behavior unexplained. Minimum viable, with clear remaining gaps.

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

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

Schema coverage is 57%, so the description must compensate for some gaps. It clarifies the free-text q parameter with need-based examples ('smoothie', 'clogged sink') and names category, zip, location, and open-now, but says nothing about accepts (the enum) or how lat/lng interact with zip/location.

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 ('Find') and resource ('businesses in the network') with concrete query examples ('plumber', 'clogged sink'), and the 'Returns summaries with starting prices' clause clarifies the output shape. It implicitly separates itself from the singular sibling get_business (bulk search vs single fetch) but never names an alternative explicitly.

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

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

The description implies the use case (searching by customer need with optional filters), but gives no explicit when-to-use guidance and never routes the agent to or away from siblings like get_business, get_services, or check_service_area. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description adds that the image is persisted and that a URL is produced as output, which is real behavioral context beyond the annotations. It stops short of stating retention/expiry, size limits, or that repeat uploads produce distinct URLs, so it is not a full 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?

Two sentences, zero filler, with the primary action and output front-loaded and the dependency/requirement hint second. Every clause earns its place.

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

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

For a no-output-schema tool, the description covers the essential contract: what it stores, what it returns, and how the result is consumed downstream. Missing constraints (max image size, accepted dimensions, permanence of the upload) keep it from being fully complete.

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

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

Schema coverage is 50%: media_type carries defaults and an accepted-value list in the schema, but image_base64 has no description and the tool description adds no encoding, size, or format guidance for it. The baseline of 3 is appropriate given the schema does most of the work and the description does not compensate for the 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?

States a specific verb+resource ('Stores an image') plus the concrete output ('returns a URL') and where that URL goes ('photos[] of place_service_request'). An agent can distinguish this from siblings like place_service_request or get_service_requirements 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?

Explicitly routes the agent: use the returned URL in photos[] of place_service_request, and consult get_service_requirements to learn whether a photo is mandatory for a given service. It names the alternative tool and the condition that determines need.

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