Keepp

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

Adds substantial behavior beyond the annotations: the call returns a link rather than completing the connection, the user must open and approve it, and no password or key is ever transmitted. That async, user-mediated, credential-free profile is exactly the kind of context annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true) cannot convey.

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

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

Three short sentences, each carrying distinct information: the action, the deferred-approval semantics, and the follow-up step. The most decision-relevant fact (nothing connects until approval) 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?

An output schema exists so return values need not be explained, yet the description still clarifies that the return is an approval link. Combined with the follow-up pointer to list_connectors, an agent has everything needed to call this correctly and set user expectations.

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 a single parameter with full schema description coverage, so the schema already explains the 'business' handle with an example. The description adds no syntax or format detail about the parameter, which matches the baseline for high-coverage single-param tools.

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 ('Starts connecting Google Calendar to a page') and is immediately distinguishable from siblings like connect_stripe, connect_telegram and connect_zoom. It also names the completing action (approval link) rather than leaving the outcome 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?

Gives clear operational context — this begins a flow, nothing is connected until the user approves, and list_connectors should be checked afterwards. It stops short of an explicit when-not or a named alternative, but the resource-scoped name already separates it from the other connect_* tools.

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 (non-destructive, idempotent, open-world), but the description adds what the annotations cannot: nothing is connected until the person approves, no password or key is passed through the tool, and the country is immutable after account creation. These are material operational facts an agent must know.

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, each earning its place: action and return, the approval caveat, then the follow-up and the immutability warning. The verb and return are 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?

Given an output schema already exists, the description needn't detail return fields, yet it still characterizes the return (a link to approve) and warns about the irreversible country choice. Nothing needed 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% and the country property already documents "Ask them — never infer it" and the first-time-only behavior, so the description's note about immutability largely repeats structured data. It adds emphasis but not new syntax or meaning 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?

States a specific verb and resource ("Starts connecting Stripe to a page") and describes the two-step approval flow. It is trivially distinguishable from siblings like connect_google, connect_telegram, and connect_zoom.

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 follow-up alternative explicitly ("Check list_connectors afterwards") and gives a concrete precondition: confirm the country with the person before calling. It also clarifies that nothing is connected until the user approves, which tells the agent this is a kickoff step, not a completed action.

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, destructive, non-idempotent behavior, and the description adds real substance beyond them: the code is one-time, expires in 24 hours, and a new code cancels the previous one (which explains the non-idempotent flag), plus prerequisites (bot present, Topics on, bot admin). It stops short of saying what the destructive action actually removes.

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, all carrying information: outcome, deliverable, prerequisites, code semantics, and follow-up. The only soft spot is the pronoun-heavy opening ('This gives...'), which is slightly less front-loaded than it could be.

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

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

An output schema exists so return values need not be described, and the description covers the call's purpose, required setup steps, code lifetime, and the follow-up verification call. It leaves failure modes (e.g., invalid handle) unaddressed, but nothing essential for correct invocation is missing.

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

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

There is a single parameter and schema coverage is 100%, with the schema itself documenting the 'business' handle format (keepp.link/<handle>). The description adds no further parameter-level detail, 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?

The title supplies the verb+resource (connect a Telegram group) and the description explains the resulting behavior: chat replies land in a Telegram group with one topic per conversation, and the call returns a one-time /link code. It is clearly distinguished from the sibling connectors (connect_google, connect_stripe, connect_zoom) as the Telegram-specific one, though the opening sentence describes the outcome before the action.

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

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

It tells the agent what to do with the result ('Relay the steps as given') and names an explicit follow-up tool and its purpose ('Call get_chat_settings afterwards to see whether the group is linked'). There is no explicit when-not-to-use or comparison against the other connect_* tools, but the context is unambiguous.

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

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

Annotations already declare readOnly=false, openWorld=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the operation is a two-step flow that returns a link, nothing is connected until the user approves, and no password/key is passed — meaningful behavioral 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?

Two tight sentences with the core action front-loaded, followed by the important approval caveat and a follow-up hint. Every clause earns its place, though it is quite terse.

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

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

An output schema exists so return-value explanation isn't required, and the description still clarifies the link/approval semantics. For a single-param connect tool the agent has enough to invoke it correctly, with only minor guidance gaps around prerequisites.

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 'business' param is fully documented in the schema. The description implies the target is 'a page' but adds no format or syntax detail beyond the schema, 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?

States a specific verb+resource ('Starts connecting Zoom to a page'), which clearly distinguishes it from the sibling connect_google/connect_stripe/connect_telegram tools by naming the target service and the page it binds to.

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

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

Provides a post-action pointer ('Check list_connectors afterwards') and an approval-flow context, but gives no explicit when-to-use vs alternatives or prerequisites for invoking it relative to the other connect_* tools.

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 tell the agent this is a non-idempotent, open-world, non-destructive write. The description adds substantial unannotated behavior: the created offering is invisible until put_page links it, mixed mode/config combinations are rejected, validation errors name the offending field and are safe to retry, and a wrong timezone silently shifts all slots. That is exactly the kind of consequence-level disclosure annotations cannot carry.

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 core action and mode split, then ordered by risk (publication, mode config, timezone, confirmation). Dense but every sentence carries an operational instruction; the imperative tone is appropriate for a write tool, though the confirmation and currency guidance is repeated in both the description and the pricing 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?

Rich nested schema plus an output schema means the description need not explain return values, and it correctly focuses on preconditions, failure behavior, and user-confirmation duties. The one gap is that it never surfaces the mode-dependent required fields (schedule/durationMinutes in slots mode) at the description level, leaving mode branching entirely to the schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds decision-relevant emphasis the schema buries in prose — the timezone is the seller's zone and drives every slot, and currency must be asked for, never defaulted to USD. It does not restate the mode-specific required fields (durationMinutes, schedule) at the top level, so the agent must still read the schema for mode branching.

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 and resource ('Adds something people can book') and immediately disambiguates the two modes: appointments on a weekly schedule vs. stays. It also distinguishes itself from the sibling that publishes it ('It is not on the page until a booking block places it there with put_page'), so an agent can separate create_booking_unit from put_page/update_booking_unit without reading 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 a clear precondition ('not on the page until put_page') and an explicit gating step ('show the person exactly what will be saved and get their explicit yes'). It does not name update_booking_unit as the alternative for modifying an existing offering, so the when-to-use story is clear but not exhaustive.

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?

Discloses a real behavioral trait beyond annotations: the handle is effectively permanent because changing it breaks every existing link, which is why approval must precede the call. Annotations only cover the read-only/idempotency/destructive flags, so this warning is genuine added value. It stops short of describing what the response contains or what happens on handle collision, 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?

Two sentences, front-loaded with the effect (page at keepp.link/<handle>) before the constraint. The second sentence is long but each clause carries a distinct instruction; minor overlap with the schema's 'as the person approved it' wording is the only redundancy.

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

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

For a two-parameter create tool with full schema coverage, an output schema, and annotations covering safety flags, the description supplies the one missing piece an agent needs: the mandatory human confirmation step and the permanence of the handle. Nothing required to call it safely 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 would be 3, but the description adds meaning the schema does not: the handle must be user-approved and is immutable in practice, and the agent may propose one. That reframes both parameters as consent artifacts rather than plain strings.

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 plus the resulting URL shape: 'Creates a page at keepp.link/<handle>'. That resource identity is distinct from siblings such as create_product or create_booking_unit, so an agent can route correctly without opening schemas.

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

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

Gives an explicit pre-call protocol: always show the exact handle and display name, obtain an explicit yes in the conversation, and propose a handle only if the user has none but never create an unapproved one. This is when/how-to-use guidance with a hard gate, not an implied hint.

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 write/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's job is to add context — and it does: the product is inert until a block places it, a human confirmation is required, and currency must never be assumed. It stops short of disclosing duplicate-creation/retry behavior implied by idempotentHint=false, so it is not a full 5.

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

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

Purpose is front-loaded and no sentence is filler — placement, deliveryUrl, the confirmation gate, and the currency rule each carry a distinct instruction. Slightly dense em-dash phrasing and the terse fragment 'Show the title, price and currency' keep it off a 5.

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

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

For a 12-parameter nested creation tool with an output schema and 92% field coverage, the description supplies what structured fields cannot: the page-placement precondition, the confirmation requirement, and the anti-assumption currency rule. Remaining gaps (retry/duplicate semantics, pagination-free confirmation of results) are minor given the output schema exists.

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 92%, so the baseline is 3 and the schema does most of the work. The description still adds meaning beyond the schema by tying deliveryUrl to a business scenario (course or download delivered after payment) and flagging the minimal visible fields (title, price, currency) and the currency constraint that spans parameters.

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

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

States a concrete verb and resource ('Adds a product to a page's catalogue') and immediately clarifies the boundary against both put_page and the pre-existing page state. It also distinguishes itself from update_product/delete_product by framing the creation semantics (page placement, delivery artifacts). An agent can identify this tool 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 names the alternative ('use put_page for that') and the condition that selects it, defines the deliveryUrl use case ('something delivered after payment'), and adds hard preconditions: confirm exactly what will be saved, get an explicit yes, never assume a currency. This is when-to-use, when-not-to-use, and prerequisites in five sentences.

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 readOnlyHint=false, but the description adds material context: there is no undo, and the call will REFUSE under two specific conditions. This tells the agent both the consequence and the failure modes, well beyond what the structured hints provide.

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

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

The irreversible-action warning is correctly front-loaded, but the middle sentences shift into assistant-facing talk-track instructions ("Say which offering and that there is no undo") rather than tool behavior. The trailing "Never assume a currency" is confusing noise for a tool with no currency parameter, diluting an otherwise tight description.

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

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

An output schema exists and annotations cover the safety profile, so return values need no explanation. The description supplies the preconditions, irreversibility, and confirmation flow an agent needs; only the irrelevant currency remark and absent sibling routing keep it from full completeness.

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 `business` and `bookingUnitId` are already documented in the schema. The description's "Say which offering" hint gestures at bookingUnitId but adds no syntax or format detail, so the baseline of 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 ("Removes a bookable offering") that is unambiguous against siblings like get_booking_unit or update_booking_unit. It does not explicitly differentiate itself from delete_product, but the resource name and title make the target clear.

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

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

Gives concrete preconditions for refusal (offering still on the page, bookings ahead of it) and prescribes a confirmation workflow before calling. It stops short of naming alternative tools (e.g., update_booking_unit when a modify is intended), so it is strong context without full alternative 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 destructiveHint=true and idempotentHint=true, but the description adds material context beyond them: no undo, a refusal condition tied to page membership, the side effect that existing buyer orders are preserved, and a mandatory explicit user confirmation. These are exactly the behavioral traits an agent needs before a destructive mutation.

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 permanence warning and the put_page precondition are front-loaded well, but the closing 'Never assume a currency' is irrelevant to a tool with no currency parameter and reads as leakage from another tool, adding noise to an otherwise tight description.

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

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

With an output schema present, return values need not be described, and the description covers permanence, the refusal precondition, side effects, and confirmation requirements. The stray currency instruction is the only element that muddies an otherwise complete picture.

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 'business' (page handle) and 'productId' (from list_catalog) are already documented in the schema. The description only gestures at 'Say which product' and adds no format, source, or constraints beyond what the schema states, which is the baseline case.

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

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

States a specific verb and resource ('Removes a product from the catalogue for good') and makes the permanence explicit. An agent can immediately distinguish it from update_product and get_product 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 ('It will REFUSE while the product is still on the page: take its block out with put_page first'), names the alternative tool (put_page), and prescribes a confirmation workflow with the user before calling. This is unusually complete routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds real context beyond that: the read payload is round-trip compatible with update_booking_unit, which tells the agent it can read-then-write with the same shape. It does not discuss auth or pagination, but neither is implied by the tool.

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

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

Two sentences, front-loaded with the payload scope and followed by the usage condition. Every clause earns its place; nothing is repeated from the title or schema.

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

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

An output schema exists, so return values needn't be spelled out, yet the description still signals the payload shape as a write-compatible contract. Purpose, timing, and round-trip relationship to update_booking_unit are all covered for a simple two-param read.

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 both parameters (business, bookingUnitId) are documented in the schema, including their provenance (page handle, from list_catalog). The description adds no parameter-level detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb (read) and resource (one offering/booking unit), and enumerates the substantive fields it returns — schedule, timezone, price, meeting setup, questions, images, policy. The reference to 'the shape update_booking_unit takes' implicitly distinguishes it from the write sibling, though no other read tool is explicitly contrasted.

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 clear call condition: read before changing an offering, and to answer questions about it. This ties it directly to update_booking_unit as the natural predecessor. It lacks an explicit when-not / alternative clause, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-openWorld), so the bar is lower. The description adds the precondition relationship with update_chat_settings and the scope of returned settings, but says nothing about permissions, whether settings can be absent/empty, or any access constraints beyond what the annotations state.

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 field inventory and closing with the actionable routing directive. The field list is dense but every item corresponds to a setting the caller needs to know exists; only the parenthetical aiContext gloss is slightly expendable.

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

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

With an output schema present, the description need not explain return values, and the annotations carry the safety profile. For a single-parameter read tool this is complete enough to invoke correctly; only the absence of any auth/permission note keeps it from a 5.

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 'business' parameter is fully documented in the schema as the page handle. The description alludes to 'a page' but adds no syntax, format, or validation detail beyond that, 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?

The description enumerates exactly what this read returns for a page's chat: enabled state, who answers, live status, pre-chat questions, and aiContext. That specificity makes the resource unambiguous and it names the sibling it pairs with (update_chat_settings), though the read verb itself is only implied from the title.

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 sequencing rule: 'Read it before changing anything with update_chat_settings,' which routes the agent to this tool ahead of the mutation sibling. There is no when-not guidance, but for a paired read-before-write pair the trigger condition is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavioral context: the returned version token is state that put_page depends on (an optimistic-concurrency contract), and that `url` changes meaning once an owner domain is connected. It stops short of auth/rate-limit details, so a 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?

Front-loads the resource and scope, then the workflow dependency, then field semantics — a sensible ordering with no filler. It is somewhat run-on in the back half, and the `url`/`pages` explanation partly duplicates what the output schema already provides.

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 single-parameter tool with an output schema and full annotation coverage, the description supplies the one thing structured data cannot: the put_page version handshake. Return-field semantics are explained even though the output schema exists, which is mildly redundant but not harmful.

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 one parameter and schema_description_coverage is 100% — the handle format and example ('janedoe', keepp.link/<handle>) are already fully documented in the schema. The description adds nothing about the `business` parameter itself, 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?

Opens with a precise scope statement — 'The whole page document: every block in order, and the theme' — naming both the resource and its contents, and contrasts the operation with its write counterpart put_page. An agent can distinguish it from get_product/get_booking_unit/put_page 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 ('Read this before writing') and an explicit workflow dependency ('keep the `version` it returns — put_page needs it'), which tells the agent both when to call it and what to do with the result. This is the same class of routing guidance as naming an alternative sibling.

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

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

Annotations already cover read-only, idempotent, closed-world and non-destructive semantics, so the bar is lower; the description still adds a genuinely useful trait — the response matches update_product's input shape, enabling read-modify-write round-tripping. It doesn't add much beyond that about errors or permissions.

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

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

Two tight sentences, front-loaded with what the tool returns, followed by when to call it. 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 2-parameter read tool with full schema coverage, rich annotations and an output schema, the description covers content, shape and workflow adequately. Only a minor gap remains around listing versus single-fetch scope.

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 both parameters are documented (handle format, productId source from list_catalog), so the baseline of 3 applies. The description adds no parameter-level 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?

States a concrete verb (read) and resource (one product) and enumerates what the payload covers — price, images, policy, questions, settings — which separates it from list_catalog. It also ties the shape to update_product, though it doesn't explicitly say 'do not use this to list'.

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

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

Gives a clear usage condition: 'Read it before changing a product, and to answer questions about it', which implicitly routes mutations to update_product. It lacks an explicit when-not or a named alternative, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint false, and destructiveHint false, so the safety profile is covered. The description adds useful behavioral context: it surfaces the handle needed by other tools and instructs the agent to ask the user when multiple pages exist. It does not discuss pagination, auth, or rate limits, but those are less critical here given the output schema.

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 what the tool returns and followed by usage guidance. Every sentence adds distinct value with no repetition or filler.

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

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

Given zero parameters, rich annotations, and an output schema, the description covers everything an agent needs: what the tool lists, what the returned handle is for, and when to call it. No important gap remains.

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?

This tool takes zero parameters, so the baseline is 4. The description mentions a `business` handle for other tools, which is useful context for the broader workflow, but there are no parameters of this tool for it to clarify.

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 resource and scope: 'Every Keepp page this account can manage.' It also explains the result's purpose, including the handle to pass as `business` to other tools, making it clear this is a listing tool rather than a single-page getter or a mutation.

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

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

It explicitly says when to call it first ('when the person has not said which page they mean') and gives a concrete decision rule for multiple results ('ask them rather than guessing if there is more than one'). This directly guides agent behavior.

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 this read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the operation is a lookup that returns ids referenced by blocks, and it clarifies the boundary of mutation (placement is a page edit, pricing/creation happen elsewhere).

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

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

Two tight sentences that front-load the returned resource before the boundary conditions. The second sentence is slightly indirect ("Placing one on the page is a page edit") but every clause carries information, 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 single-parameter read with an output schema and full annotation coverage, the description supplies enough: what it returns, what the ids are for, and where adjacent operations live. Nothing an agent needs to invoke it correctly is missing, though it could be slightly more explicit about the listing scope.

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 a single parameter with 100% schema description coverage, so the schema fully documents the business handle. The description's phrase "on this page" is consistent with the handle concept but adds no syntax or format detail beyond the schema, 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?

The description names the resource precisely ("products and bookable offerings on this page") and states what it yields ("the ids a product or booking block refers to"), which separates it from create_product and get_product. It never uses an explicit verb like "list," relying on the name/title for that, so it falls just short of the fully self-contained 5.

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 routes the agent away from two adjacent operations: "Placing one on the page is a page edit" points to put_page, and "creating or pricing one is not done here" points to create_product/update_product. These are clear exclusions, though the alternatives are described by activity rather than named, so it stops short of explicit when-to-use/when-not guidance.

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

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

The description adds domain meaning that annotations cannot carry – that Stripe enables paid products/bookings and Telegram handles owner chats – which helps interpret 'connected' and 'ready'. However, it discloses nothing about how readiness is determined, whether live service calls are made, or what permissions are needed; note the tension that a purely informational 'see which' tool carries readOnlyHint=false in the annotations, unexplained by the description.

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

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

Two short sentences with no filler; the status question is front-loaded and the second sentence supplies just enough domain context. Slightly more could be trimmed but nothing is wasted.

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

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

With one fully documented parameter and an output schema handling return values, the description supplies what an agent needs to call it and to interpret the four boolean-style answers. The only gap is the absence of any note on usage relative to the connect_* tools.

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 'business' parameter is fully documented in the schema, including the handle format example. The description contributes no additional parameter guidance, so the baseline of 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 concrete resources (Stripe, Google, Zoom, Telegram) and states that it reports connection and readiness status for a page, which is a specific, recognizable operation. It is distinguishable from the connect_* siblings by being a status query rather than an action, though it never uses an explicit verb like 'list' or 'check'.

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

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

Usage is only implied: an agent can infer it should be called to check state before or instead of calling connect_google/connect_stripe/etc. There is no explicit statement of when to use this versus those siblings, and no mention of prerequisites or error cases such as an unknown handle.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description goes further by disclosing the shape of what is returned (links, open targets, remaining quota), including the `targets` concept, which clarifies behavior beyond the annotations.

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

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

A single dense sentence with the resource and return contents front-loaded, followed by the routing instruction. Slightly heavy with inline code and colons, but no sentence is wasted.

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

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

With an output schema present, the description need not enumerate return values, and annotations cover the safety profile. For a one-parameter read tool, the purpose, return gist, and pre-write usage guidance together are sufficient to invoke it correctly.

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

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

The single `business` parameter is documented in the schema as the page handle at 100% coverage, so the description adds little parameter detail. The phrase "this page" implicitly ties the input to a page, but the schema already carries that meaning, so the baseline of 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 a specific resource (the page's custom links) and enumerates the payload: the links, what each opens, remaining quota, and the `targets` blocks. It draws a clear line against set_custom_links, so the agent can distinguish read from write 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?

"Read this before set_custom_links" states the sequencing condition and names the alternative explicitly, which is more than most list tools offer. It stops short of stating when not to use it, but the routing purpose is unambiguous.

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 read-only, idempotent, non-destructive safety, so the bar is lower; the description still adds real behavioral value by disclosing that both paid plans carry a 7-day free trial for new customers and instructing the agent to surface that to the person. It also notes that the optional business argument changes the returned information (which plan that page is on). It does not discuss error behavior for unknown handles.

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?

It is three front-loaded sentences that move from what the tool returns to when to call it to the trial caveat, with no filler. The sentences are somewhat clause-dense and pack multiple instructions (route to upgrade_plan, disclose trial, pass business) into one paragraph, which slightly reduces 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?

An output schema exists, so the description need not document return values, and annotations cover the safety profile. It supplies the trial detail, the upgrade_plan handoff, and the optional parameter's effect, leaving only edge cases like invalid handles unaddressed.

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 schema already explains the business handle format, giving a baseline of 3. The description goes beyond that by explaining the effect of passing it: it reveals which plan the referenced page is on, information the schema does not 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?

The first sentence states a specific resource and scope: what each Keepp plan costs and includes. It also names the sibling it hands off to (upgrade_plan), so an agent can distinguish the informational plan tool from the checkout 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 trigger ('call this when something needs an upgrade'), the goal ('so the person can choose knowing what they get'), and the next step in the chain ('then upgrade_plan for their checkout link'). The only missing piece is a when-not, which is minor for a read-only lookup.

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?

Goes well beyond the annotations: omitted blocks are deleted with no warning, concurrency is guarded by version, image URLs are downloaded and stored (with a failing-write behavior naming the offending block), and nothing needs uploading. This surfaces destructive and side-effect detail the destructiveHint/idempotentHint flags cannot convey.

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

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

Front-loads the replace semantics, then layers warnings, workflow, image behavior, and return values in a tight sequence. Four dense sentences with no filler, though the final return-value sentence is somewhat redundant given an output schema exists.

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

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

For a destructive, nested-object, whole-document write, it covers the data-loss risk, concurrency protection, side effects, prerequisite read, and even return shape. An output schema exists, so the brief mention of url/pages is bonus rather than necessity.

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: version's role as a stale-write guard, blocks must be the complete list, and the pointers into the keepp://capabilities resource and keepp.link/<handle> handle format. It stops short of documenting the theme object's contents.

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 with scope: 'Writes the WHOLE page document at once.' The word WHOLE plus 'a block you leave out is deleted' makes the replace semantics unambiguous and distinguishes it from partial-update siblings. It also names get_page as the paired read tool.

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

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

Gives an explicit workflow: call get_page first, edit what it returned, send the version it gave you. It explains why (stale writes fail loudly) and covers the image-handling case, so the agent knows both when to use it and what prerequisites to satisfy.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: these images are free to use and should not replace owner photos. It does not describe pagination or return behavior, but those are covered by the output schema.

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 purpose, then moves directly to usage rules and a critical constraint. Every sentence adds actionable information with no repetition or filler.

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

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

Given five parameters, nested filters, an output schema, and full annotations, the description supplies exactly the extra context an agent needs: when to use, how to apply the result, and when to avoid it. Nothing essential is missing.

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

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

Schema description coverage is 100%, and the schema itself explains every parameter including nested filter values and enums. The description adds workflow guidance (how to use the returned URL) but does not add meaning beyond the schema for the parameters themselves, so the baseline of 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 states a specific verb and resource: searching a gallery of images stored on Keepp, and clarifies the categories (backgrounds vs. card/product/offering pictures). It also distinguishes the tool from the owner's own photos, leaving no ambiguity about what this tool does.

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

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

It gives an explicit condition for use ("Use one when the owner has no photo of their own for a spot") and an explicit prohibition ("never replace one with a gallery image"). It also names the consuming tool (put_page) and tells exactly where to place the returned URL.

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 and idempotentHint, but the description adds the consequence detail annotations cannot convey: omitted links are deleted and their addresses stop resolving even where already printed or shared. It also discloses that changes take effect immediately without a page publish, and that re-pointing a link preserves its address.

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 whole-list semantics before the mechanics, and each sentence carries non-obvious information. The printed-link explanation is slightly redundant with the earlier omission warning, and the prose is dense enough to require careful reading.

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 prerequisites (put_page, published blocks), destructive consequences, address-preservation behavior, and timing (immediate, no publish). Since an output schema exists, no return-value explanation is needed, leaving nothing material 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?

Schema coverage is only 50%, and the description compensates well for the most consequential parameter by explaining that `links` is a whole-list replacement, where `id` comes from, and what null `blockId` means. It says nothing about the `business` handle parameter, but that is documented in the schema, so the gap is minor.

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

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

Opens with a specific verb+resource plus the critical scope qualifier: 'Saves the WHOLE list of custom links at once.' That immediately distinguishes it from the sibling list_custom_links and signals replacement rather than incremental update.

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

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

Explicitly routes the agent: get ids from list_custom_links, get valid targets from its `targets` output, and call put_page first because only blocks on the published page qualify. It also states when to use null blockId, covering the main decision points an agent faces.

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 critical behavior: omitted fields preserve existing values, nested config fields also merge, mode changes need the full new-mode config, existing bookings are not moved, and page publication is a side effect. It also adds the required human confirmation and currency behavior, so the agent knows the operational risk profile.

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

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

The description is front-loaded with the core action and then moves through merge semantics, mode changes, side effects, and confirmation requirements. Every sentence adds practical guidance, and there is no redundant restatement of schema details.

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 mutation with nested objects, side effects, and a destructive annotation, the description covers the important gaps: partial-update behavior, mode transitions, booking preservation, page republishing, and confirmation before saving. With a full schema and output schema present, no essential invocation context is missing.

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

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

Schema description coverage is 100%, so the schema already documents most parameter meanings. The description still adds important update semantics not fully captured elsewhere: omitted top-level and nested config fields keep their values, and a mode change requires the whole config for the new mode.

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 gives a clear verb and resource: it "Changes an offering." Combined with the title "Change a bookable offering" and required business/bookingUnitId identifiers, an agent can tell what object is being updated. It does not explicitly differentiate this from siblings like update_product, which keeps it from a 5.

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 concrete operating guidance: send only changed fields, config is merged key by key, changing mode requires the whole new config, and the user must be shown the exact save and explicitly confirm. It does not name alternative tools or state when not to use this one, so it is strong but not a full alternative-routing guideline.

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 reinforces exactly that: it discloses partial-update semantics ("the rest keeps its value") and the replace-wholesale behavior of questions and aiContext, which is what makes this destructive. It goes further by stating cross-tool prerequisites and a human-in-the-loop instruction ("show it to the person before saving") that no annotation conveys.

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 core action and partial-update rule are front-loaded vacuously well, and every sentence roughly earns its place by adding a prerequisite or a constraint. It is slightly long at five sentences, with the aiContext workflow instruction partially duplicating the schema's own aiContext text.

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 a rich input schema, an output schema, and full annotations, the description covers the essentials: what changes, what is preserved, what is replaced, and which sibling tools must run first. Remaining gaps are minor — no mention of the required business handle or of what happens to the live published chat when enabled is toggled, but nothing an agent needs to call it 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 each parameter already carries a rich description, so the baseline is 3. The description earns an extra point by adding authoring guidance the schema does not contain (how to source aiContext content, and that replacement is total), though most of the mode/enabled semantics are restated from the schema and the required "business" handle is never mentioned in prose.

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 concrete verbs and objects ("Switch chat on or off, choose who answers, and set the questions and aiContext"), which maps one-to-one onto the parameters and clearly separates this tool from sibling get_chat_settings (read) and put_page (page content). It also names the related sibling tools it depends on, so an agent can place it in the workflow without opening any other 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 explicit prerequisites with named alternatives: the chat needs a chat block via put_page, and owner-answering modes require connect_telegram first, plus partial-update guidance ("Send only what should change"). What it lacks is any direction to read current state first with get_chat_settings or guidance on when not to change settings, so it falls just short of the highest bar.

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 annotations (destructiveHint true, idempotentHint true), the description discloses genuine behavioral traits: omitted fields are preserved, null clears optional fields, pricing objects are replaced whole rather than merged, already-placed orders retain their purchase price, and the page is republished on change. This is exactly the mutation semantics an agent needs.

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 core patch semantics in the first sentence and stays tightly focused. Slight redundancy — the 'never assume a currency' instruction is echoed from the pricing schema description, and the price/currency caution is restated — keeps it from a 5.

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

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

For a 13-parameter mutation tool with nested objects, an output schema, and annotations covering safety hints, the description covers the missing pieces: patch vs replace semantics, side effects (republish), order-price immutability, and the confirmation-before-write requirement. Nothing critical is left to inference.

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

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

Schema coverage is already 92% (baseline 3), but the description adds non-schema semantics: whole-pricing replacement on send and the hard rule to never assume a currency. That meaningfully augments the schema for the pricing field.

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 ("Changes a product") and immediately clarifies that it is a partial/patch update, which distinguishes it from create_product and delete_product. It does not name those siblings explicitly, so it stops short of a 5.

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

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

Gives clear operational guidance: send only the changed fields, show the person the exact diff (especially price and currency) and get an explicit yes before calling. It lacks explicit routing to alternatives like update_booking_unit, but the when/how-to-invoke context is strong.

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

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

Annotations already declare readOnly=false, destructive=false and openWorld=true, so the bar is lower; the description still adds real value by clarifying that nothing is charged until the Stripe page is completed, that the plan changes only then, and that the caller should retry the blocked action afterward. It does not disclose that repeated calls likely mint new links (idempotentHint=false) or what happens if the page is already on a plan.

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, front-loaded with the return value and the money-safety fact, each carrying distinct information (charge timing, plan change, trial, trigger). The 'say so' and 'tell the person' imperatives are slightly prescriptive but still earn their 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?

An output schema exists so return shape needn't be explained, and the description covers the payment flow, trial terms, trigger condition, and post-payment retry. Remaining gaps — behavior when already subscribed and re-invocation semantics — are minor but real for a mutating, open-world billing tool.

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

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

Schema description coverage is 100% and both params are documented there, including the enum ('pro'/'influencer') and the handle format, so no gap needs compensating. The description adds no new meaning about the parameters beyond the mandate to explain the plan choice to the user.

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

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

The description states the concrete output and outcome — it returns a Stripe link and the plan changes after payment — which is distinguishable from siblings like list_plans or get_page. The core 'upgrade this page to a paid plan' framing leans on the name and title rather than the description itself, so it is clear but not fully self-contained.

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 concrete trigger: 'Call this when a tool says a feature needs Pro,' plus the instruction to tell the person which plan and why. There is no explicit when-not-to-use or named alternative, but the trigger condition is unusually specific for this toolset.

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