Awning

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses the consequential side effect an agent must surface: a possible late fee governed by the business's cancellation policy, with the exact field to read afterwards (applied_policy). It doesn't spell out reversibility or error cases (e.g., what happens past the policy window), which keeps it 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?

Three sentences with no filler: scope first, then the confirm-and-warn-the-user instruction, then the sibling disambiguation. Each sentence carries distinct operational information.

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

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

With an output schema present and annotations covering the safety profile, the description supplies exactly the missing pieces: the user-confirmation step, the fee-warning obligation, and where the applied policy appears in the response. Nothing needed to invoke it correctly 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 description coverage is 100%, so booking_id, reason, and manage_token are already documented in the schema, including the manage_token auth nuance. The description adds nothing parameter-level; the cancellation_policy/applied_policy references concern returns, not inputs, so the 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 resource ('Cancels a booking as the customer') and immediately scopes it against the sibling 'owner_cancel_booking', which handles the business-side variant. An agent can distinguish the two without inspecting either 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?

Explicit routing rule: use this for the user's own booking, use owner_cancel_booking when an owner cancels on behalf of their business. It also imposes a procedural precondition ('Confirm with the user first') and points at get_booking's cancellation_policy before acting.

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 cover idempotency and read/write hints, but the description adds substantive behavioral context beyond them: retry guidance with the same idempotency_key, the account auto-fill fallback for contacts/name, and the critical pending-status semantics for businesses that confirm requests themselves. This is exactly the kind of non-obvious behavior an agent needs to avoid misreporting a booking as confirmed.

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 the confirmation gate, then layers required data, fallback behavior, and the pending-status caveat. Every sentence carries operational weight, though the density of distinct rules in five sentences makes it slightly heavy for a single read.

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 output schema present, annotations covering idempotency and mutation safety, and 100% schema coverage, the description fills the remaining gaps: prerequisites, confirmation gating, auto-fill behavior, retry keys, and the pending-status misinterpretation risk. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema: it restates the customer requirement (name + at least one of phone/email/telegram), explains that signed-in account fields are auto-filled, and clarifies the idempotency_key's retry semantics. This climbs above baseline for a well-covered 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 opens with a specific verb+resource ('Creates a REAL booking from a hold') and explicitly ties the operation to its prerequisite (create_hold), making it distinguishable from siblings like create_hold and get_booking. The uppercase emphasis on 'REAL' signals the mutation consequence immediately.

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 explicit when-to-use conditions ('only after create_hold and the user's explicit yes'), a required precondition ('after the user explicitly confirmed time and price'), and an explicit when-not/verification rule ('do not tell the user it is confirmed until get_booking says so'). The alternative for user/workspace filtering is implied through the sibling reference.

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 readOnlyHint=false, destructiveHint=false and idempotentHint=false, and the description goes well beyond them by disclosing the 10-minute expiry, that the hold lapses on its own, and that nothing must be undone if the user backs out — the key behavioral fact for a non-destructive mutation. It falls short of 5 because it doesn't say whether a second call creates a duplicate hold (relevant given idempotentHint=false) or whether a hold can be released early.

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?

Four short sentences, front-loaded with what the tool does, then mode parameters, then the mandatory user-confirmation flow, then the hold-vs-booking reassurance. No sentence is redundant and nothing is buried.

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, mode-dependent mutation the description covers the prerequisite read call, the per-mode parameter selection, the expiry behavior and the handoff to create_booking. Return values are documented by the output schema, so no further explanation is owed.

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 100% schema coverage the baseline is 3, but the description adds real routing value by mapping parameters to booking modes ("Pass start (slots), session_id (sessions) or from+to (rentals)"), which the schema does not state. It doesn't add anything about party_size, tickets, options or resource_id, which remain schema-only.

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?

"Reserves the chosen time, seats or units for 10 minutes and fixes the price" gives a specific verb (reserves), the resource (time/seats/units), the duration and the side effect (price locked). It explicitly separates itself from create_booking with "A hold is not a booking," so the agent can distinguish the two sibling tools without opening either 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?

It names the prerequisite ("Use it after get_availability, with a time or class taken from its answer"), the exact parameter routing per mode (start for slots, session_id for sessions, from+to for rentals), and the required follow-up sequence (show time/price/cancellation policy, get an explicit yes, then call create_booking). Alternatives and ordering are fully spelled out.

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 readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context: it reserves nothing and explains what each mode returns, but it does not cover auth needs 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?

The description is four tight sentences with no waste, and the core purpose and mode behavior are front-loaded before the usage guidance.

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

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

For a seven-parameter, three-mode availability tool with no output schema, it explains the key return shapes per mode and the critical pre-call condition (reserves nothing). The fully documented schema covers the remaining parameter details.

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 documented in the schema. The description only hints at mode-to-parameter mapping (from/to for period mode) and does not add meaningful parameter semantics beyond the schema.

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

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

The description states a specific action and resource: checking real free time for one offering. It also clearly distinguishes the three modes (slots, sessions, period) and explicitly separates this from get_business weekly hours.

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 timing and alternatives: use before create_hold once an offering and day are chosen, it reserves nothing, and it is not for weekly business hours, which are in get_business. The agent is told both when to use it and when not to.

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 access-control semantics beyond that: the manage_token can be omitted when the user is signed in and owns the booking, which is genuinely useful invocation context. It does not say what happens if neither credential applies (error shape), a minor remaining gap.

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, front-loaded with the core purpose, then usage cases, then the alternative-tool disambiguation. Every clause carries information; nothing is redundant padding.

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 two-parameter read tool with a full output schema, the description covers purpose, both invocation paths, auth conditionality, and the sibling alternative. Return values need not be described because an output schema exists, so nothing an agent needs 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 both parameters are already documented, establishing a baseline of 3. The description reinforces the conditional semantics of manage_token ('pass ... or nothing if the user is signed in and the booking is theirs'), which helps the agent decide when to supply it rather than merely what it is.

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 and scope precisely ('Status of one booking'), then extends it to 'show one booking in full', so the agent knows both the status-check and detail-view uses. It also names the sibling it supersedes for multi-booking retrieval (my_bookings), making it distinguishable from the 35 other tools at a glance.

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 explicit when-to-use cases: checking whether a pending booking was confirmed, or displaying one booking in full. It names the alternative for the list case ('for a list of all the user's bookings use my_bookings'), and states the auth condition for the optional token, leaving nothing 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 and openWorldHint=false, so the description adds context rather than carrying the safety profile: it discloses the fields returned, the meaning of the demo:true flag (a sample listing that is not a real place), and that offering_id values originate here. It does not cover error behavior for invalid identifiers, but the extra disclosure is substantial.

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 content list leads, followed by the demo flag, usage routing, dependency note, and exclusion. Every sentence earns its place, though the content enumeration is a long clause that borders on packing too much into one sentence.

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

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

No output schema exists, so the description must explain returns, and it does: it enumerates the full card contents and explains the demo flag. Combined with the usage routing and offering_id provenance, an agent has everything needed 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 coverage is 100% and the single parameter is fully documented there (business_id UUID or slug, page address format). The description adds only the example page address and reinforces the offering_id relationship, so 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?

Opens with a specific verb+resource ('Full card of one business') and enumerates exactly what the card contains (offerings, prices, extras, booking rules, intake questions, hours, cancellation policy, contacts). It explicitly contrasts with sibling get_availability ('Not for free times'), so the agent can distinguish it 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?

States the two entry conditions explicitly: 'Use it after search_businesses, or when you already have a business_id, a slug or an Awning page address'. It also names the alternative for availability and explains the downstream dependency ('The offering_id values the booking tools need come from here').

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 destructive=true, idempotent=true, readOnly=false. The description adds real context beyond that: the effect is scoped per assistant unless everywhere=true, the next personal request re-prompts sign-in, and 'it changes no bookings' pre-empts the false inference that a destructive tool mutates booking data.

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 tight sentences, all front-loaded: default behavior first, the everywhere escalation second, the invocation gate last. No filler and 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?

For a single optional boolean with no output schema, the description covers default scope, escalated scope, re-authentication consequence, invocation condition, and side-effect boundary. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already explains that everywhere ends every sign-in of the account with a default of false. The description restates the same semantic in prose, adding emphasis but no new format or edge-case detail.

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 concrete verb and resource ('Signs the user out of Awning') and immediately narrows scope: 'in this assistant only' versus 'every assistant, device and browser'. An agent can tell exactly what this does and how far it reaches 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 restricts invocation: 'Use it only when the user asks to sign out', which is a clear when-to-use gate. It doesn't name alternatives, but no sibling tool offers competing sign-out behavior, so the gap is minor.

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 the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds context annotations cannot carry: the tool requires an authenticated Awning session and will prompt the user to sign in if not. It also hints at returned content (status per booking, suggested next action), though it says nothing about ordering, volume, 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?

Three short sentences, each doing distinct work: what the tool returns, the auth prerequisite, and the sibling routing. The most selection-critical information is front-loaded.

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 describe the shape of results (per-booking status and next action) and the sign-in failure mode, which is what an agent needs to call it correctly. Some minor gaps remain around result volume/ordering and how the default 'upcoming' period behaves, but nothing blocking.

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

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

Schema description coverage is 100% and the single 'period' enum is fully documented in the schema, so the baseline applies. The description never mentions the period filter, adding no syntax or default-behavior information beyond what the schema already 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?

Names a specific resource and scope ('the signed-in user's bookings across all businesses') plus what each item carries ('status and what to do next'). It also explicitly distinguishes itself from get_booking, so an agent can choose between them without reading either 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 a concrete use case ('answer "what have I booked?"') and names the alternative for the adjacent case ('for one booking by id use get_booking'). The routing condition is explicit, not inferred.

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-read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond them: it supports either reading or partial updating, says to pass only fields that should change, and clarifies that it operates on the personally signed-in user rather than a business.

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 core read/update behavior, then adds usage context and sibling differentiation. Every sentence contributes to correct tool selection or invocation, with no redundant restatement of the name or 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?

For a four-parameter profile tool with no output schema, the description covers the main fields, read/update modes, and sibling alternatives. It does not describe what an update returns or whether read responses are shaped differently, which is a minor remaining gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds useful invocation semantics by explaining partial updates and that passing no fields performs a read, which is not fully captured by the schema alone.

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: read or update the signed-in user's own profile. It lists the profile domains covered (name, email, phone, language, contact channel) and explicitly distinguishes the person from a business, naming sibling tools for the business case.

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 clear when-to-use guidance: learn what contact details booking can reuse. It also names explicit alternatives, owner_status and owner_update_business, for business details, and explains the read-vs-update invocation pattern.

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 already covering safety, the description adds substantial behavioral context: Umami visitor data versus server-side all_visits, the people/assistants/crawlers split, and the fact that assistants do not run scripts. It also instructs comparison against the previous period, which is valuable analytical behavior not captured by 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 restriction and purpose are front-loaded, and the data-source sections are useful rather than filler. The final use-case sentence partly repeats what the earlier description already established, and the long 'people:'/'all_visits:' sentences could be more clearly structured.

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 no output schema, the description adequately covers what data categories are returned and how people versus all_visits differ. It could be clearer about whether both sections are always returned together, but an agent has enough to call and interpret 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?

There is only one parameter and schema coverage is 100%, so the schema already explains the days range and default. The description only implies a lookback window through 'over the last days' and 'previous period', adding little beyond the parameter 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 precise resource and scope: website performance over the last days, restricted to the Awning team. It names concrete analytics dimensions such as sources, channels, devices, and lead-form events, making it unmistakable among the booking and business-management siblings.

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

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

It gives a hard eligibility rule ('Only for the Awning team') and explicit use cases ('questions about traffic, sources and how far people get with the business form'). It does not name alternative tools, but no sibling appears to overlap with this analytics purpose.

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?

readOnlyHint already covers the safety profile, but the description goes well beyond it: it discloses the access restriction (Awning team only) and decodes the domain-specific route values (review, known_owner, auto_branch, rename) that determine how each row must be interpreted. With no output schema, this field-level semantic decoding is the only place an agent can learn what the rows mean.

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 sentences, front-loaded with the audience restriction, then the payload, then the route legend. The dense middle sentence uses arrows and parentheticals to compress four route definitions without wasted words.

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

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

For a domain-specific ops queue with a non-obvious route enum and warnings, the description supplies the interpretation key that no structured field provides, and there is no output schema to defer to. What it omits is modest: nothing about volume, ordering, or pagination of the returned queue.

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% and the single enum parameter is fully documented there, so the baseline of 3 applies. The description only obliquely touches the parameter via 'see status approved' in the auto_branch note, adding no real syntax or default information beyond the schema.

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

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

Names a specific resource ('queue of business applications') plus the payload it carries ('owner contacts and warnings'), and separates itself from op_businesses ('for every business whatever its state') and op_decide_application. An agent can route correctly without opening a 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 when-to-use ('see what waits for a decision'), names the follow-up tool (op_decide_application), and names the sibling to use for the broader case (op_businesses). It also states the audience restriction ('Only for the Awning team'), which is a genuine eligibility gate rather than a nicety.

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 only declare readOnlyHint=true, so the description carries the rest and does so well: it discloses the access restriction ('Only for the Awning team') and explains the return payload, including that the link resolves to the private preview when a business is not live. It does not mention pagination or result-count limits, which is the only gap.

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?

Opens with the audience restriction, then the payload, then the filters, then the alternative – a sensible front-loaded order with no filler. The status parenthetical is a little dense but each element maps to real information.

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

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

With only two optional parameters, a read-only annotation, and no output schema, the description covers everything an agent needs: who may call it, what comes back, how to filter, and which sibling handles the adjacent case.

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, and the description only restates the filter intent. It also introduces a mild mismatch: the status list mentions 'needs changes', which has no counterpart in the enum (draft, review, published, suspended), so the mapping is not fully reliable.

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 resource (every business on Awning) together with the exact fields returned: status, owner, and link. The public-page-versus-private-preview distinction further pins down what the tool yields, so an agent can distinguish it from get_business or search_businesses without opening a 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 two concrete use cases (find a business by name, or enumerate every business in a given state) and names the boundary case: applications awaiting a decision belong to op_applications. This is explicit when-to-use plus a named alternative, leaving little to infer.

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

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

Beyond annotations, the description discloses the required human step of opening the link and confirming in the bot, the server-side allowlisting prerequisite for moderation, and the one-time setup nature. These details explain the non-idempotent and non-destructive mutation behavior in practical terms.

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

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

The description is four tight sentences, front-loads the audience restriction, then gives the action, the follow-up step, the prerequisite, and the usage cadence. Every sentence carries actionable information with no waste.

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 zero parameters, no output schema, and annotations that establish safety profile, the description fills the remaining gaps: who should call it, what it creates, the human confirmation step, the server allowlist prerequisite, and that it is one-time setup. Nothing an agent needs to call it correctly appears 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 takes zero parameters, so the baseline applies. The description confirms this with 'it takes no input,' adding a small bit of clarity, but there are no parameter semantics to elaborate.

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 action and resource: 'Create a link to bind your Telegram to your signed-in operator account.' It is clearly an operator-only setup tool and is distinguishable from sibling tools like op_analytics or op_applications, which do not involve Telegram binding.

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 audience restriction ('Only for the Awning team'), usage cadence ('Use it once, to set up Telegram for the operator'), and a prerequisite ('A server administrator must also allow your numeric ID in OPERATOR_TELEGRAM_IDS before moderation is enabled'). There is no direct alternative among the siblings, so no alternative routing is needed.

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

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

Beyond the destructiveHint/openWorldHint annotations, it discloses consequences that matter: approval makes the business publicly live, rejection sends the note to the owner, approval is refused if the name changed, and recall removes the business from the catalogue and recreates the application. It also names the access restriction ('Only for the Awning team'), which the annotations do not capture.

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 nearly every sentence carries a distinct rule; the expected_name rationale is front-loaded with its consequence. Slightly long-winded in places ('list the applications again, check the name, then decide') but no filler paragraphs.

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 and four fully documented parameters, it covers decision outcomes, the stale-name failure mode, the rename special case, and recall's effect. Route concepts like 'auto_branch' and 'rename' are used without definition, relying on op_applications for that vocabulary.

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 real meaning: expected_name must be the exact name shown by op_applications (business.name), is unnecessary for the rename route, and is validated against the current name. It also explains the owner-visible effect of note on reject.

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 the three outcomes concretely: 'approve publishes the business', 'reject needs a note the owner will see', and recall returns an auto_branch location to the queue. It is clearly distinct from op_applications (which lists) and op_decide_lead (different resource). It loses a point only because it opens with an audience restriction rather than a one-line statement of 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 gives explicit when-to-use rules per decision, including the expected_name requirement and its exception for the rename route, and the narrow condition for recall ('only for an application op_applications listed, after checking its warnings'). It also gives a recovery path when approval is refused: list applications again, re-check the name, then decide.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent), and the description adds real value beyond that: it discloses that invite triggers an immediate outbound email to the business, and that close discards the enquiry with an optional internal note. It doesn't say whether close is irreversible or whether invite can be repeated — with idempotentHint=false already declared, this is a modest gap rather than a failure.

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 compact sentences, front-loaded with the audience restriction, which is good. But the content is slightly redundant — the invite/close mechanics appear in the schema parameter descriptions too — and the final clause about immediate email is tacked on rather than integrated.

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?

A three-parameter mutation with no output schema and no confirmation of what the tool returns (a status? the updated enquiry?). The description covers eligibility and both branches but leaves the agent guessing what to report back after a successful invite, which matters for a tool with real-world side effects like sending mail.

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% and each parameter already has its own description including the enum meaning and note's close-only restriction. The description restates the same invite/close semantics and adds the 'optional note for us' framing, but contributes no syntax or format detail beyond the schema.

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

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

The description states a specific verb pair (invite/close) on a specific resource (an enquiry listed by op_leads), and explains what each branch does behaviorally — invite emails setup instructions, close drops it. It's clear apart from siblings like op_decide_application, though the title alone would be ambiguous.

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 names the audience ('Only for the Awning team') and the precondition ('an enquiry op_leads listed'), which tells the agent to call op_leads first. What's missing is guidance on choosing invite vs close — no criteria for when each decision is appropriate beyond the bare mechanics.

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 readOnlyHint=true, and the description is consistent, adding the access restriction and the important default behavior (only new enquiries unless status is given). It doesn't say anything about result volume or ordering, which would matter for an ops inbox listing.

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 every clause carries information: restriction, source, fields, default, status semantics, next step, exclusion. Slightly run-on in the middle with parenthetical asides, but the access restriction is front-loaded.

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-only list tool, an agent has enough to call it correctly and route afterwards. Missing only peripheral details such as ordering, pagination or maximum number of enquiries returned.

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% and already enumerates the status values, so the bar is a baseline 3; the description goes beyond it by naming the default ('new') and explaining that converted means the person filled in the questionnaire, which is business meaning the enum label alone doesn't convey.

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 concrete resource (enquiries from the awning.help/business page) plus what each record contains (email, optional business name), and explicitly separates it from the two nearest siblings, op_decide_lead and op_applications.

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 when to use it ('see who asked to join'), what to do next ('then op_decide_lead') and an explicit exclusion ('Not for applications that are already filled in (op_applications)'). It also states the access precondition (Awning team only).

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 destructive/idempotent/non-readonly, and the description adds the timer of the effect ('leaves the catalogue and search at once'), the authorization restriction, and the reversal path via recall. These are exactly the behavioral facts an agent cannot get from the structured fields.

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 audience restriction, then effect, then the routing alternative. No filler and no repetition of schema content.

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

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

Covers authorization, immediate side effect, and recovery path for a destructive two-param tool with no output schema. It stops short of describing what happens to existing bookings or what the call returns, which would round it out.

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%, with both parameters fully documented in the schema (reason length bounds and audience, business_id source). The description adds no additional syntax or format guidance, so 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?

Names a specific verb and resource (hide a business from clients) and states the concrete effect: it leaves the catalogue and search immediately. It also distinguishes itself from the sibling op_decide_application, which handles returning a business to review.

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?

Explicit when-to-use (complaints, ownership dispute), when-not (only for the Awning team, only on the operator's explicit instruction), and an alternative for the inverse operation (op_decide_application with recall). An agent has no inference left to do about routing.

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, so mutation status is covered. The description adds real value beyond that: it discloses the auth requirement, that the offering is attached to an existing business whether live or not, and that on a live business it becomes immediately bookable — a meaningful side effect. It stops short of describing failure modes 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?

Four short sentences, front-loaded with the precondition, then the action, then the constraint, then the sibling routing. Every sentence contributes; the only mild redundancy is 'live or not' versus 'On a live business it can be booked at once', which are complementary rather than duplicative.

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 two-parameter mutation on a deeply nested object, the description covers auth, scope, create-vs-update routing, and the immediate-visibility side effect. Since no output schema exists, it does not say what the call returns (e.g. the created offering or its id), which is the one gap an agent would want.

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

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

Schema description coverage is 100% and the nested offering object is thoroughly documented (units, price_unit, quote_only, schedule format), so the schema carries the parameter burden. The description's 'described the same way as in owner_setup' adds a useful cross-reference but no field-level detail beyond the schema. 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 and resource ('Add a new offering to a business') and scopes it to businesses the owner already has. It also explicitly excludes the sibling case ('to change one that exists use owner_update_offering'), so the agent can distinguish it from owner_update_offering without reading either 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 ('Only for business owners signed in to Awning'), an explicit create-vs-update routing rule, and a workflow constraint ('Confirm the details with the owner first; never invent a price'). This is the full when/when-not/alternatives set.

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 flag destructive=true and non-idempotent, and the description adds material context beyond that: existing bookings in the blocked window are NOT cancelled but returned as existing_bookings_in_this_time, and how to undo a block via remove_exception_id. This is exactly the kind of side-effect disclosure an agent needs before a destructive call.

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-loads the action and scope, then the alternates, then the side effect. Dense but purposeful; the only mild redundancy is restating the open/remove_exception_id semantics already in the schema.

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

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

Covers the destructive-write scenario fully: purpose, alternatives, permission gate (business owner signed in), and the returned field for conflicting bookings, which compensates for the absence of an 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 coverage is 100%, so every parameter is already documented with format, defaults and interdependencies. The description echoes open=true and the remove_exception_id removal path but adds no syntax or constraint detail beyond the schema, making baseline 3 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 action (close/open time) plus scope (whole business or one staff member/room) and explicitly contrasts with the sibling owner_set_schedule which handles regular weekly hours. An agent can distinguish it from owner_set_schedule and owner_get_schedule 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 says when to use it (one-off closures or extra hours) versus the alternative (regular weekly hours with owner_set_schedule), and adds a precondition: confirm with the owner first. It also routes removal to remove_exception_id.

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 openWorldHint=true, and the description adds real context beyond them: the client is notified and the reason text is delivered to the client. It does not spell out reversibility or what happens if the booking is already cancelled, which is the remaining behavioral gap.

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?

Four short sentences, each carrying a distinct decision-relevant fact, with the audience constraint front-loaded. No filler or restatement of 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?

For a two-parameter destructive mutation with rich annotations, the description covers who can call it, which booking state it applies to, notification side effects, and the confirmation etiquette. Only edge-case behavior (booking already cancelled, unknown booking_id) is left implicit.

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%, with both required parameters documented in-schema (booking_id sourced from owner_list_bookings, reason shown to the client). The description adds no parameter-level detail of its own, so the 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 (cancels) and resource (a booking) with the acting party pinned down: 'on behalf of the business.' It explicitly distinguishes itself from both cancel_booking (customer self-cancel) and owner_decide_booking (pending requests), so an agent can route without opening a 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 audience precondition (business owners signed in to Awning), a positive trigger (a booking already confirmed), the state-based exclusion (pending requests go to owner_decide_booking), and the sibling alternative (customer cancel uses cancel_booking). It also prescribes an interaction step: ask the owner to confirm 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 flag destructiveHint=true, idempotentHint=true and openWorldHint=true, yet the description adds real behavioral context the annotations cannot: the client is notified, and the decline reason is shown to the client. It stops short of saying whether confirm or decline is reversible, or whether repeated calls re-notify the client, which is relevant given idempotentHint=true.

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 definition is short and front-loads the caller scope and decision set, and every clause (notification, precondition, sibling routing) earns its place. The mid-section is a run-on of semicolon-separated clauses, which slightly hurts scanability.

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 mutating 4-parameter tool with no output schema, the definition covers who may call it, the full decision state machine (pending vs. post-visit), the client-facing side effects, and sibling routing. Nothing an agent needs in order to choose or 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?

Schema coverage is 100% and every parameter already carries a description, so the schema does the heavy lifting. The description only restates the reason/price pairing that the schema already documents, adding no format or edge-case detail beyond it. 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?

The description names the exact verb set (confirm / decline / quote / complete / no_show) and the resource (a pending request or a past visit), which is far more precise than the title's 'Confirm or decline'. It also explicitly excludes the sibling owner_cancel_booking, so an agent can place it in the booking lifecycle 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?

It states the caller precondition ('Only for business owners signed in to Awning'), the source of the input ('requests found with owner_list_bookings'), and the alternative for a different state ('to cancel a booking already confirmed use owner_cancel_booking'). It also imposes a safety precondition, 'Confirm with the owner before declining.'

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, so the description doesn't need to prove safety. It adds the audience gate ('Only for business owners signed in to Awning') and clarifies that 'resources' entries carry ids that feed resource_id here and mutation tools elsewhere – real context beyond the structured fields.

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?

Four sentences, each carrying distinct information: audience, view scope, id chaining, and sibling routing. The audience restriction is front-loaded, though the id-chaining sentence is slightly long-winded for what it conveys.

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 audience, the granularity of the view, what data appears in it, and how resource_id connects to other tools. With no output schema, a brief note on response shape would help, but nothing essential for calling it correctly is missing.

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

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

Schema coverage is 100%, so date, days, business_id and resource_id are already documented with defaults and formats. The description's note about resource_id echoes what the schema already says ('an id from resources in an earlier answer'), adding little new meaning. 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-resource ('Day or week view per staff member, room or rental pool') and enumerates what the view contains: bookings, classes, blocked time and free windows. An agent can distinguish it from get_availability or owner_list_bookings 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?

Gives an explicit use case ('Use it to see how a day or week looks') and names the alternative for a related need ('for requests waiting for an answer use owner_list_bookings'). It does not address the other near-neighbours such as get_availability, but the primary routing decision is covered.

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?

It adds meaningful context beyond annotations: the page is third-party content, must be treated as data rather than instructions, and prices or hours must not be invented from it. It also describes the return shape as readable text and candidate photos. The only gap is that it does not reconcile the read-only framing with readOnlyHint=false.

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 access prerequisite and core action, then layers in workflow, safety, and skip guidance. Every sentence adds a distinct operational rule with 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 one-parameter read/import tool with no output schema, it covers the essentials: auth scope, input expectation, return contents, follow-up workflow, prompt-injection caution, and when not to call it. Nothing material is missing 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?

The schema already has 100% description coverage for the single url parameter, including its format and rate limit. The description reinforces the expected page types (website, listing, public profile) but does not add syntax or format details beyond the schema.

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

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

The description states a specific action and resource: it takes the address of a page the business already has and returns readable text and candidate photos. It also distinguishes the tool from owner_setup by positioning this as the input step before a single owner_setup submission.

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 guidance: use at the start when the owner has a web page. It also states when to skip it: when the owner describes the business in their own words, and it limits use to signed-in business owners.

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 only declare readOnlyHint=true; the description adds real context beyond that — audience restriction (signed-in business owners), result ordering (pending requests first, then remaining bookings), default window, and inclusion of client contact details. It stops short of describing pagination or result limits, so not 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?

Two sentences, both dense with actionable content: the first covers audience, ordering, defaults and return content; the second covers use cases and alternatives. Nothing is padding and the key scoping facts come first.

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, no-output-schema list tool with fully documented optional parameters, the description covers audience, ordering, defaults, and sibling routing — enough to call correctly. The only gap is the slightly imprecise description of the default date window.

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 all four parameters are already documented in the schema itself. The description adds the ordering semantics around the status filter and the default window, but its 'default: next 7 days' gloss is slightly at odds with the schema's from=24 hours ago / to=seven days from now pair, so it does not add clean value above 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?

States a specific verb and resource ('list bookings', 'check booking requests') plus scope: pending requests first, then bookings in a period, with client contacts. It explicitly distinguishes itself from owner_decide_booking and owner_get_schedule, so an agent can pick it without opening sibling 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?

Gives explicit routing: use it to find requests to answer (then call owner_decide_booking) or to see who is coming; for a calendar view by staff or room use owner_get_schedule. The alternative and the condition that selects it are both 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?

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds the key reassurance that 'existing bookings stay' — clarifying what the destructive hint does not touch. It does not explain whether pausing is reversible beyond toggling, nor what happens to availability visibility while paused, so it stops short of full disclosure.

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: eligibility first, effect second, routing third. 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?

For a two-parameter toggle with full schema coverage and no output schema, the description covers scope, effect on existing bookings, and the alternative tool. Minor gaps remain around what a pause changes for customers viewing the business, but nothing an agent needs in order 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?

Schema coverage is 100%, so both parameters are already documented, including the paused boolean semantics that the description restates. The description adds no business_id guidance of its own; 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 pair (stop taking / resume) and the resource (new bookings), plus the scope restriction to business owners signed in to Awning. The sibling owner_block_time is named with the exact condition that separates the two.

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 eligibility gate ('only for business owners signed in to Awning'), a duration-based rule of thumb ('break of days or weeks'), and an explicit redirect to owner_block_time for a single day or a few hours. No inference required.

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 (readOnly=false, openWorld=true, idempotent=false, destructive=false) only sketch the write profile; the description adds the zero-argument upload-widget behavior, the upload_url fallback, the response shape (current with photo_id), the semantic effect of ai_generated (shown as illustrations, never as real premises), and failure handling (resolve failed uploads before photos_done). It also names the one hard prohibition: never invent a URL or send a local file path.

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?

Nearly every sentence carries procedural weight, and the audience restriction and core save/list behavior are front-loaded. It is dense to the point of overload, though: generation policy, cost disclosure, error recovery, and the photos_done gate are packed into one unbroken block, and the list-photos fallback sits mid-paragraph rather than being surfaced early.

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 five optional parameters, no output schema, and mutations involved, the description covers what is missing elsewhere: the return value (upload widget, upload_url, or the current photo list), the ownership/sign-in prerequisite, and the failure path. Nothing an agent needs to call this correctly 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 100%, so the baseline is 3; the description still adds meaning beyond the schema by constraining urls to downloadable image addresses with a never-invent rule and supported attachment links for files, and by explaining that ai_generated changes how the page presents the images. It does not address the draft_id vs business_id distinction, which is left 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?

Opens with a specific verb+resource and an audience gate ("Only for business owners signed in to Awning"), then states the dual behavior: saves photos and, when called with nothing, returns an upload widget plus the current photo list. The final sentence explicitly separates it from owner_remove_photos, so the agent can route without opening either 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 explicit when-to-use and when-not ("to take photos off use owner_remove_photos"), a preference ordering (owner's own photos of the actual place first, generated illustrations only if none or more wanted), a prerequisite flow (owner must approve each picture; explain image-tool cost first), and a completion gate (mark photos_done only after successful uploads).

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 the description reinforces that it changes nothing. It adds valuable context about showing draft or existing versions and what blocks submission, though it doesn't detail return format or any rate limits.

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 sentences, front-loaded with purpose and usage, with no wasted words. Each sentence adds distinct value: scope, action, and usage guidance.

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

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

For a simple read-only preview tool with one optional parameter and no output schema, the description covers all essential aspects: what it shows, when to use it, and that it changes nothing.

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 fully documents the single optional business_id parameter, including when to omit it. The description adds no further parameter guidance, which is acceptable given 100% schema coverage.

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

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

The description clearly states the tool's verb (shows preview) and resource (business as clients see it, draft or existing), and explicitly distinguishes it from owner_submit by saying it's used before submission and changes nothing.

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 conditions: only for business owners signed in, use before owner_submit to show the owner their page and ask for approval, and that it changes nothing. This clearly guides when to use it versus the submit tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds context annotations cannot carry: 'The files are deleted' signals permanent, unrecoverable removal, and 'Confirm with the owner which ones first' imposes a confirmation step before invocation. The auth scope ('signed in to Awning') is also stated explicitly.

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 precondition is front-loaded in the first clause, the action follows, and the alternative plus confirmation guidance close it out. Every sentence carries distinct operational information with no repetition of 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?

For a 3-parameter destructive mutation with no output schema, the description covers the actor, the precondition, the two target contexts, the identifier source, irreversibility, and the confirmation workflow. Nothing an agent needs to invoke this safely 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 photo_ids, draft_id and business_id are all already documented in the schema with the same provenance hints ('current list of owner_photos', 'from owner_status'). The description reinforces the photo_id source but adds no new format, ordering, or batching guidance (e.g., the 50-item cap) beyond what the schema provides.

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

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

States a specific verb and resource ('Take photos off the business page') plus the two scopes it operates on (live business page vs. business being set up) and the identifier source ('by photo_id from owner_photos current'). It also explicitly distinguishes itself from the sibling that does the opposite ('to add photos use owner_photos').

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

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

Gives an explicit precondition ('Only for business owners signed in to Awning'), an explicit trigger ('when the owner wants pictures taken down'), an explicit alternative ('to add photos use owner_photos'), and a procedural instruction ('Confirm with the owner which ones first'). No inference is required to pick this tool over owner_photos.

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 annotations only say destructive=true and idempotent=true; the description adds the crucial detail of what is actually destroyed — old hours are fully replaced while existing bookings are kept — plus the owner-only auth precondition. That is exactly the context an agent needs before committing a destructive write.

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

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

Five short sentences, front-loaded with the audience gate and the core replace semantics, then the alternative and the whole-week warning. Zero 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?

Auth, replacement semantics, booking preservation and the sibling alternative are all covered, which is nearly everything an agent needs for a destructive write. There is no output schema, and the description never says what comes back or how invalid/overlapping ranges are handled — a minor remaining gap.

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

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

Schema description coverage is 100%: hours format, business_id provenance and resource_id source are all documented in the schema. The description only gestures at resource_id scoping, so it adds little beyond the structured fields. A 3 baseline is appropriate here.

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 (replace) and resource (weekly hours), and scopes it to the whole business or one resource via resource_id. It explicitly contrasts with owner_block_time, so an agent can pick the right tool without opening either 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?

It gives an explicit audience gate (business owners signed in to Awning), an explicit when (regular weekly pattern), and an explicit when-not with the alternative named (one-off day off or extra hours → owner_block_time). Nothing 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 cover the safety profile (idempotent, non-destructive, closed-world), and the description adds genuinely behavioral context: this is a multi-turn guided flow that must not invent details, must preserve draft_id, and returns instructions_for_assistant explaining what is missing. It does not spell out what happens on new_business or copy_from_business_id, which keeps it from 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?

Four dense sentences with zero filler, and the gating condition is front-loaded before the description of the guided behavior and the sibling alternatives. Every sentence earns its place.

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

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

For a complex nested guided-setup tool with no output schema, the description covers the essential context an agent needs: auth precondition, multi-turn draft handling, anti-hallucination constraint, response guidance and routing to other tools. It could go further on the live-business boundary and on starting additional businesses/locations, but nothing critical is missing.

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

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

Schema coverage is 100%, and the nested schema already documents answers, draft_id, new_business and copy_from_business_id in detail. The description adds only the operational reminder to keep draft_id and the constraint to use only what the owner said — useful but limited beyond the schema 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?

States a specific verb and resource ('Creates or continues a business's setup') and immediately scopes it to signed-in business owners. It explicitly names the sibling tools that handle a live business, so an agent can distinguish it 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 ('Only for business owners signed in to Awning') and an explicit exclusion with alternatives ('Not for a live business: use owner_update_business, owner_add_offering, owner_update_offering or owner_set_schedule instead'). No inference is required.

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 cover the safety profile (readOnlyHint=true) and the description does not contradict them. It adds real context beyond the annotation: an authentication/role prerequisite and a field-level preview of the response (pending request count, pending_rename, draft). It stops short of describing shape or edge cases, hence 4 rather than 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?

Three short sentences, front-loaded with the audience constraint and then the payload, with the exclusion last. Slightly dense with parentheticals but every clause carries information.

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

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

Read-only tool with no output schema and one optional parameter; the description enumerates the key returned fields, states the auth prerequisite, and routes away from booking tools. Missing only error/empty-state behavior, which is minor here.

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% and the single optional business_id is already documented there, including the 'leave out when there is only one' rule. The description's note that business_id values originate here is useful chaining context but largely duplicates the schema text, so 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?

Names the specific resource (owner's businesses and applications) and enumerates the concrete payload: pending requests count, pending_rename, unfinished draft. An agent can distinguish it from op_applications or owner_list_bookings 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 states when to call it ('use it first when the owner signs in or asks how things stand'), states the audience gate ('only for business owners signed in'), and names an exclusion with the correct alternative ('not for bookings (owner_list_bookings)'). Nothing 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?

Adds context beyond the annotations: auth requirement (signed in as business owner), the fact some submissions go live immediately ('A new location... goes live at once') and to report the returned status verbatim, plus the once-only nature. These are meaningful operational traits not expressed by readOnly/openWorld/idempotent hints.

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-loads the audience restriction and the core action, then the sequencing and alternatives. Slightly dense with multiple caution clauses, but every sentence carries operational value rather than padding.

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 2-param write tool with no output schema, the description covers auth, sequencing, alternatives, and the unusual 'goes live at once / report status as-is' behavior. Nothing an agent needs to call correctly appears missing; the lack of output schema is mitigated by the 'report the returned status' guidance.

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 both draft_id and business_id are already fully documented, setting the baseline at 3. The description notes the rejection case and the multi-business context, echoing the schema rather than adding new syntax or format 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?

States a specific verb and resource ('Submits the finished onboarding... for review') with the audience scoped ('Only for business owners signed in to Awning'). It explicitly contrasts with owner_update_* tools, so an agent can distinguish it from siblings without opening a 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 the precise call sequence ('Use it once, after owner_preview and the owner's yes'), a precondition ('Confirm with the owner first'), and an explicit alternative ('to change a live business use the owner_update_* tools instead'). When-to-use and when-not-to-use are both covered.

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 destructiveHint=true, and the description explains exactly what makes it destructive: 'What is sent replaces what is there' and dropping lat/lng discards the old map point. It additionally discloses a behavior no annotation could convey — a new name on a live business is moderated, customers see the old name until approval, the response flags it under rename, and resending the current name withdraws a pending rename.

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 access precondition and the change surface, then the high-risk rename and map-point caveats, then sibling routing. Every sentence carries information, though the rename paragraph is dense enough that the moderation rule and the withdrawal rule run together and cost a little readability.

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

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

For a 10-parameter destructive mutation with no output schema, the description covers permissions, replace-not-merge semantics, the async rename outcome and where it appears in the response, the map-point side effect, and confirmation expectations. Nothing an agent needs to call it safely 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, but the description adds genuine semantics beyond it: the lat/lng pair must accompany a new address and omitting them drops the existing map point, and name changes have case-only fast-path versus moderated behavior. It does not add anything for contacts, late_fee_pct, or free_cancel_hours beyond what the schema already says.

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 (update business details) and enumerates the mutable surface: name, description, address and map point, contacts, cancellation rules, auto confirmation. It explicitly carves out the sibling tools for setup and offerings, so an agent can route 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?

Gives a hard precondition ('Only for business owners signed in to Awning') and explicit alternatives with the conditions that select them: owner_setup during setup, owner_add_offering/owner_update_offering for services and prices. It also tells the agent to confirm with the owner before calling, which is a usage constraint, not just 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 destructiveHint=true, but the description adds crucial context: 'Confirm with the owner first; archiving cannot be undone.' It also specifies authentication ('business owners signed in to Awning') and partial-update semantics, going beyond the 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?

Four tight sentences, front-loaded with the primary purpose and constraints. No redundant or filler text; every sentence adds useful guidance.

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

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

Given the mutation complexity, destructive nature, and absent output schema, the description covers authentication, confirmation, irreversibility, alternative tools, and partial updates. It provides everything an agent needs 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 100%, so the baseline is 3. The description adds useful meaning by listing the editable fields and clarifying 'Send only what changes', which communicates partial-update behavior not explicit in the schema. However, it doesn't add further parameter-level detail beyond what the schema already provides.

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

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

States a specific verb and resource: 'Change ... a service that exists', lists editable fields, and explicitly distinguishes from the sibling tool owner_add_offering. An agent can tell exactly what it 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?

Explicitly states when to use (business owners signed in to Awning, to change existing services), when not to use (archiving requires confirmation, adding a new service uses owner_add_offering), and how to call it ('Send only what changes').

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 say destructiveHint=true and idempotentHint=true, but the description earns its keep by explaining the mechanics: the submitted timetable replaces the old weekly pattern wholesale, and already-generated classes survive. That replacement semantics is exactly the destructive behavior an agent needs to understand before calling.

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 and largely front-loaded, with the replacement caveat and the sibling exclusion stated early. The auth precondition leads ahead of the core purpose, which slightly delays the key verb, 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?

A destructive mutation with no output schema and no annotation detail on returns is adequately covered: replacement behavior, retention of generated classes, and the correct alternative are all present. Return shape and what happens on invalid day patterns are unstated, a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real semantic weight to the schedule parameter by saying the full timetable must be sent because it replaces the prior pattern. The offering_id/business_id meaning is left to the schema, so it stops short of a 5.

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 ("Set when a class runs") and immediately scopes it to sessions-mode offerings whose weekly timetable changes. It explicitly separates itself from owner_set_schedule, which covers appointments and rentals, so an agent can route correctly without reading either 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?

Names the precondition (business owners signed in, sessions-mode class), the trigger condition (weekly timetable changes), and the explicit exclusion with the alternative tool named ("Not for appointments or rentals (owner_set_schedule sets their hours)"). When-to-use and when-not-to-use are both stated.

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 the safety profile (readOnlyHint=true, openWorldHint=false); the description adds real behavioral context beyond them: results come back as cards containing business_id, offerings and page_url, and any card with demo:true is sample data that should be disclosed and de-prioritized. It also explains that location is not inferred from the request but comes from the server.

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 what the tool finds and how to filter, then demo-flag handling, then routing. Four dense sentences with no filler; even the parenthetical category list earns its place by scoping expectations.

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, and the description compensates by naming the returned fields (business_id, offerings, page_url) and the demo:true caveat. For a 7-parameter, optional-only search tool, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining the filtering modes at a conceptual level (text, city/country, coordinates/category) and, importantly, clarifying the semantics of location — 'Awning does not guess where the user is from the request... so pass their city or near coordinates when you know them'. It does not restate limits or radius formatting, but that is already 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 ('Find') and resource ('local businesses that take bookings'), then enumerates the concrete verticals it covers (salons, courts, rentals, tours). It also distinguishes itself from three siblings by name — get_business for follow-up, my_bookings for the user's own bookings, owner_status for owners.

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 says 'Use this first when the user wants a place or a service; when they pick one, continue with get_business', giving both the entry condition and the handoff. Closes with two named exclusions (my_bookings, owner_status), so an agent need not infer routing.

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