Aide

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

Annotations only declare readOnly=false, destructive=false, openWorld=true; the description goes well beyond by disclosing that articles are published immediately to a public help section unless saved as a draft, that snippets are live as soon as saved with no draft option, and that content will subsequently be used in Aide answers. That is the material side effect for a write tool. It does not discuss permissions or whether a mistaken public publish can be undone, which keeps it off a 5.

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

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

The publish-vs-draft behavior is front-loaded and useful, but the snippet/article contrast is stated three times in slightly different words ('A snippet is internal...', 'Use a snippet for notes...', and the schema's own enum description), which is redundant for the reader. It is readable but could shed a sentence without loss.

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

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

With no output schema, the description correctly notes that it returns the document with its id, and there are no nested objects to explain. For a 7-parameter create tool with full schema coverage, the only real gap is the missing boundary against add_note and update_knowledge_article, which is a usage rather than a completeness defect.

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 every parameter including kind, draft, slug, sourceId and collectionId is already documented in the schema at comparable depth. The description restates the kind default and the draft behavior without adding syntax, constraints, or cross-parameter rules the schema lacks. 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?

A concrete verb plus resource ('Write knowledge ... articles') followed by an explicit two-way taxonomy (article vs snippet) that no sibling tool name alone would reveal. An agent can immediately tell this creates customer-facing or internal knowledge content, distinct from update/publish/list knowledge tools.

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

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

Gives clear selection criteria ('Use a snippet for notes only Aide should read, an article for help customers should be able to read') and a content criterion ('what the website doesn't say, or what the user tells you directly'). It stops short of naming alternatives — notably add_note, which overlaps heavily with the 'snippet' concept, and update_knowledge_article for editing existing content — leaving the agent to infer that boundary.

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 this is a non-read-only, non-destructive, closed-world write; the description adds genuinely new context beyond them — the note is attributed to the signed-in teammate and is never surfaced to customers. It stops short of describing mention/notification side effects.

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 the action and resource, with the visibility constraint second. Nothing is redundant or 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 simple additive write with a fully documented schema and no output schema, the description covers author identity and audience visibility, which is what an agent most needs to call it correctly. Mention/notification behavior is left 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 description coverage is 100%, so all three parameters are already documented in the schema, including mentions and the cnv_… id format. The description adds no parameter-level detail, which is acceptable at this coverage level.

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 an internal note to a conversation) and clarifies the actor is the signed-in teammate. The line 'Customers never see notes' implicitly distinguishes it from reply_to_conversation, though that sibling is never named explicitly.

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

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

Usage is implied rather than stated: an agent can infer this is for internal-only commentary and that customer-facing text belongs elsewhere, but no explicit when-to-use or alternative tool (e.g. reply_to_conversation) is 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 readOnly=false, destructive=false, openWorld=false, so the safety profile is covered. The description adds real behavioral context beyond that: it returns a mailbox with `id` and `inboundAddress`, requires the user to perform manual forwarding, and may be blocked by an external-forwarding admin policy. It stops short of stating authentication/authorization requirements, which keeps it below 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-loaded correctly: purpose, the Gmail alternative, and the return/follow-up behavior come before the provider instructions. The trailing Gmail/Outlook menu-path detail is verbose but each step is actionable and non-redundant, so it earns its length, though the block could be tightened.

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

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

With no output schema, the description carries the return contract (mailbox `id` and `inboundAddress`) and the required next step (send_forwarding_test), plus prerequisite workflows for both Gmail and Microsoft 365. 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 description coverage is 100% with only two parameters, so the schema already documents supportAddress and displayName fully. The description implies the address the customer emails but adds no syntax, format, or meaning beyond the schema — 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 concrete action and resource — setting up Aide on the address customers email at (e.g. support@example.com) — and explicitly distinguishes itself from the sibling connect_integration with a Gmail inbox. An agent can tell what this does and when it is not the right 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?

Gives explicit routing: prefer connect_integration with `gmail` for Gmail/Workspace instead of forwarding, otherwise use this tool. It also sequences the workflow (call send_forwarding_test afterwards, use get_support_email for the confirmation code), and includes provider-specific prerequisites including the Microsoft 365 admin caveat.

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 not read-only, open-world and non-destructive, so the description focuses on traits the annotations can't express: the import runs in the background for a few minutes, the return carries `id` and `status`, and a duplicate site is refused with a `duplicate` error. It stops short of covering the `articles` kind or failure modes other than duplicates, so it is strong rather than exhaustive.

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

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

Front-loaded with what the tool does, then the kind choice, then the async/return behavior, then duplicate handling – a logical order with no filler. It is a single dense block, though, and the duplicate-handling sentence is long enough that it takes a careful read to parse.

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

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

For a 5-parameter mutation tool with no output schema, the description covers what matters most for correct invocation: background import timing, the `id`/`status` return, and duplicate recovery paths. The gap is that it neither explains the `articles` kind nor any non-duplicate failure, leaving a modest blind spot.

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 earns a notch above it by giving the crawl scope ('pages at and under `baseUrl`') and the practical meaning of each `kind` value. It does not mention `maxPages` or `excludePaths`, which the schema already documents, and it never addresses the `articles` enum value that the schema itself also under-describes.

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: it teaches Aide a website by crawling pages at and under `baseUrl`, and answers customers from the imported content. It distinguishes the two relevant kinds (`website` vs `help_center`) and clearly separates itself from sibling readers like get_knowledge_source or reimport_knowledge_source.

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

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

Explicitly routes the agent: use `website` for the company site, `help_center` for Zendesk/Intercom, use get_knowledge_source to check status later, and on a `duplicate` refusal look up the id via get_setup_status or list_knowledge_sources then retry with reimport_knowledge_source. Alternatives and their triggering conditions are named, not implied.

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 and openWorldHint=true, yet the description still adds substantial context: the approval executes immediately on the live Shopify store, produces a paid refund or an active cancellation, is gated by a per-workspace approval limit, and is idempotent-safe with a documented refusal code. That is well beyond what the annotations 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 verb and precondition, then consequences, limits, and idempotency in a compact run of sentences with no filler. The clause about the signed-in teammate and Aide running on the Shopify store is dense but carries real behavioral 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?

Covers the precondition, the real-world effect, the permission ceiling, the return value ('the action with its new status'), and the failure mode, which is everything needed for a one-parameter mutation tool with no output schema.

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

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

Schema description coverage is 100% for the single actionId parameter, and the schema already points to list_order_actions / list_conversation_order_actions as sources. The description adds no format, prefix, or provenance detail beyond that, 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 ('Approve') plus the resource and its required precondition state ('order action waiting for approval (status `pending_approval')'), and describes the downstream effect (refund paid, cancellation happens). It does not explicitly name the contrasting sibling reject_order_action, so differentiation is left partly to inference.

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 conditions: only actions in `pending_approval` can be approved, agents are limited to refunds within the workspace approval limit, and re-calling is refused with `not_pending_approval`. It stops short of directly telling the agent to use reject_order_action for the declining case, which is the one obvious alternative in this sibling 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 declare destructiveHint=true, but the description adds genuinely non-derivable behavior: the workspace approval rules that may park the call for an admin, the fact that the result reports whether it ran or waits, and the non-deduplication rule (a repeat call while awaiting approval queues another request, while an already-cancelled order is refused). This is exactly the operational context an agent needs before mutating 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?

Three sentences, zero filler, and front-loaded: purpose first, then approval behavior, then idempotency semantics. The longer final sentence is dense but every clause carries distinct, actionable 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?

For an eight-parameter destructive mutation with no output schema, the description covers the highest-risk unknowns: approval gating, result meaning, and repeat-call behavior. Remaining parameter semantics (refund, restock, notify) are fully carried by the schema, so 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 description coverage is 100%, so all eight parameters — including the reason enum and the requestApproval flag — are already documented in the schema. The description only indirectly touches requestApproval via the approval-rules sentence and adds no syntax or format detail beyond it, 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?

The description gives a precise verb+resource (cancel an order) plus the scope and actor ('from a conversation', 'as the signed-in teammate'), which is well beyond a restatement of the name. It does not, however, explicitly distinguish itself from the sibling refund_order or approve_order_action, which is the only thing keeping 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?

Usage is implied by the phrase 'from a conversation on the Shopify store' and the approval-path sentence, but the description never states when to choose this over refund_order, or when cancellation is inappropriate. No explicit alternatives or exclusions are named, leaving routing to the agent's 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 only flag destructiveHint=true and openWorldHint=true; the description goes far beyond by disclosing that a card is entered via an external Stripe Checkout url, that the first payment is deferred by a 7-day trial, that upgrades charge a prorated difference immediately, and that downgrades defer to period end. That is exactly the financial consequence an agent needs before invoking a destructive billing 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?

Front-loaded with the primary action, then branch behaviors, then pricing context; no filler sentences. The final sentence on features and overage is slightly tangential to the call mechanics but still helps the agent explain the outcome to a user.

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 three-parameter destructive mutation with no output schema, the description covers return values (Checkout url vs. billing summary), charge timing, trial, and proration. It omits permission/ownership requirements and what happens on failure, which are the remaining gaps for an 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 coverage is 100% with enums on all three parameters, so the schema already documents interval, planSlug, and returnTo including omission semantics. The description adds business meaning to the plan choice (every plan has every feature; a paid plan adds monthly AI replies with overage) but adds nothing about parameter formats 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 a specific verb and resource ('Start a paid plan, or switch the plan or billing interval') and immediately distinguishes the two modes (first-time checkout vs. plan change). An agent can tell this apart from update_workspace or set_inbox_ai 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 clearly states the two conditions that select different behavior: no paid plan yet yields a Checkout url, while an existing plan applies the change immediately or at period end. It does not name sibling alternatives or exclusions, but the when-to-use 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 establish readOnly and non-destructive, but the description adds real value: it discloses the live Shopify lookup, the `permission: missing` condition meaning the store withheld returns permission, and reinforces 'Changes nothing'. It stops short of rate-limit or auth details, but coverage is strong.

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 verb and the live-check framing, then a tight enumeration of returned facts. The single compound sentence is dense but every clause carries information; the trailing 'Changes nothing' is a useful safety note 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?

With no output schema, the description must convey the return contents, and it does so thoroughly (per-line quantities, rule blocks, reasons, policy, open-return flag, permission-missing case). An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so both parameters are already documented with their origins (get_conversation_orders/lookup_orders and find_conversation). The description adds no parameter-level detail beyond what the schema provides, 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 (check) and resource (return eligibility) and then details exactly what is returned per line: returnable quantity, rule blocks, return reasons, policy applied, and open-return status. This clearly distinguishes it from write siblings like refund_order and cancel_order.

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

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

Provides clear context for when it applies: verifying what can be returned on an order originating from a conversation, live against Shopify. It does not name alternative siblings or exclusions, but the scope 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 declare a non-read-only, non-destructive, closed-world operation, and the description adds genuinely new behavior: the human completes sign-in out-of-band via a returned url and the agent must relay both url and tellUser. That hand-off pattern is not inferable from annotations or schema. It stops short of saying what happens to an existing connection or how long the pending state lasts.

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 target services, then the return contract, then conditional parameter rules. Dense but each clause carries information; it is slightly crammed into three long sentences but wastes nothing.

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, yet the description still supplies the agent-facing next action (show url + tellUser, then poll get_setup_status), which is the piece the schema cannot convey. With 4 params at full coverage and annotations present, nothing needed to call 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; the description earns above that by mapping each optional field to its service (Zendesk→subdomain, Gorgias→account, Shopify→shop) and clarifying that omission is safe because the dashboard page will prompt. That conditional-omission semantics is real added 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?

Opens with a specific verb and enumerated resources ('Start connecting Gmail, Shopify, Zendesk, Front or Gorgias'), and the return-value sentence pins down what the call produces (a dashboard url). An agent can separate this from list_integrations or set_up_helpdesk 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 clear follow-up routing: check get_setup_status once the user finishes, and set_up_helpdesk completes a helpdesk afterward. It also says to pass subdomain/account/shop 'when known; otherwise the page asks.' What's missing is any exclusion — e.g., what to do if the service is already connected.

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 state this is non-destructive and not open-world; the description adds the valuable non-structured detail that the call blocks for up to ~25 seconds and can return degraded states (stillLearning, empty sources) with prescribed remediation. It does not say whether the sent message persists in the preview conversation or how failures surface, keeping it below a 5.

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

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

The core action is front-loaded, but the remainder is a dense run-on chain of branches with awkward phrasing ('When `sources` is empty otherwise') and undefined terms (stillLearning, sources, 'the minutes it gives') that make it harder to parse than it needs to 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 needn't be enumerated, and the description instead explains how to interpret key output states and what to do next. For a 3-parameter, non-destructive call with full annotation coverage, nothing critical is missing, though the undefined 'pending'/'sources' references leave slight ambiguity.

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

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

Schema description coverage is 100% and already documents all three parameters (text as the customer's message, agentId from list_agents, conversationId from test_agent). The description adds no additional meaning about parameter formats or constraints beyond the schema, 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+resource ('send a follow-up message in a preview conversation test_agent started') and explicitly anchors itself to the sibling test_agent, so an agent can tell this is the second-turn continuation rather than a new test. The 25-second wait behavior is stated up front.

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 conditional routing: use list_messages (don't ask again) for a pending answer, use add_knowledge_article then retest when stillLearning or when sources is empty. The only friction is the reference to 'pending: true', which is not an input parameter in the schema and could be misread as something to pass; otherwise the when/when-not guidance is unusually complete.

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 and openWorldHint=true, but the description adds meaningful context: deployment makes the agent respond to real customers, mentions assigned channels and inboxes, and requires user confirmation. It also discloses the returned status `deployed`. This is strong behavioral context beyond the annotations, though it does not discuss edge cases like deploying an already-live agent.

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 action, then adds the live-customer impact, confirmation requirement, return status, and stopping alternative in a compact two-sentence form. Every clause carries useful 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?

For a one-parameter deployment tool, the description covers the action, effect, confirmation requirement, return value, and inverse operation. Annotations already cover the risk profile, so no important behavioral detail is missing.

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

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

The single `agentId` parameter has 100% schema description coverage and is documented as coming from list_agents. The description does not add any parameter-specific details beyond the schema, which is acceptable at this coverage level.

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: putting an AI agent live, with the concrete effect that it answers real customers on assigned channels. It also names the inverse action, pause_agent, which clearly distinguishes it from siblings such as update_agent, test_agent, and pause_agent.

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

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

Gives a clear usage condition and an explicit alternative for the reverse action: use this to go live, use pause_agent to stop it. It also adds a required confirmation step before calling. It does not mention prerequisites like existing deployment state, but the context is otherwise 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 a non-destructive mutation, and the description adds the consequential behavioral fact: dismissal suppresses future proposals for this gap and the updated gap is returned. It doesn't say whether dismissal is reversible or how to undo it, which is the main 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 short sentences, zero waste, with the effect and the return value front-loaded. 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?

For a small 3-parameter mutation with full schema coverage, the description supplies the trigger and the post-state effect, and even notes the return value despite no output schema. Only error/precondition handling (already dismissed, unknown id) is left 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% with a documented enum and a pointer to list_knowledge_gaps for gapId, so the schema carries the detail. The description only reinforces that a reason accompanies the dismissal; it adds no format or constraint 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 (dismiss) on a specific resource (open knowledge gap) plus the outcome ('Aide stops proposing it') and return value. The condition 'whose fix the user doesn't want' implicitly separates it from mark_knowledge_gap_done, though that sibling is never named.

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 trigger: use when the gap is open and the user has declined the fix. It stops short of explicitly contrasting with mark_knowledge_gap_done or stating what to do if the gap is already closed, so the boundary with the closest sibling must still be 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 readOnlyHint, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds that the full text is returned (not a snippet) and lists metadata fields, but does not disclose error behavior, permissions, or rate limits 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 sentence that is front-loaded with the core action. The enumeration of return fields is somewhat redundant given the output schema, but the sentence remains efficient overall.

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 operation with rich annotations, full schema coverage, and an output schema, the description covers the essential action and prerequisite. The only minor gap is not clarifying its relationship to the similar sibling get_knowledge_document.

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 single id parameter is fully documented in the schema. The description's phrase 'by the id search returned' mirrors the schema description without adding new syntax or format details, 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?

States a specific verb (Read) and resource (knowledge document) with scope (one, in full, by id). This distinguishes it from list and search siblings, but it does not explicitly differentiate from the similar sibling get_knowledge_document.

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

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

Implies usage when an id has been returned from search, but provides no explicit when-to-use guidance, no exclusions, and no named alternative tool for browsing or listing documents.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the result shape (id, subject, status, priority, channel, requester, assignee, team, preview, timestamps) and the pagination contract, useful for a tool with no 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, no filler: the targeting modes come first, then result contents, then pagination. Every clause carries information an agent needs.

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 17-parameter, no-output-schema tool it covers purpose, return fields and pagination adequately. Minor gaps remain: default behavior with no filters, and default sort/perPage are left 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, but the description adds genuine meaning by stating that externalId, q and filters combine (conjunctive semantics not expressed in the schema) and by explaining that the next page reuses 'same filters and sort'.

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 three ways to target a conversation (externalId, q, filters) and enumerates the returned fields. It does not explicitly distinguish itself from the sibling get_conversation or search, so it falls 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?

Usage is implied rather than stated: 'filters, which combine' tells the agent this is the list/filter entry point, but there is no explicit when-to-use-this-vs-get_conversation or vs search, and no warning about unfiltered calls returning a broad result 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 declare readOnlyHint, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds useful context that it returns the full agent representation, including instructions, greeting, signature, contact information, and used knowledge.

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 action and then the update_agent usage note. Every clause adds value 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 simple one-parameter read tool, the description covers purpose, returned fields, and the key relationship to update_agent. With no output schema, listing the return contents makes the definition complete enough 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 description coverage is 100%, and the schema already explains that agentId comes from list_agents. The description adds no additional parameter meaning, so the baseline of 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: read one AI agent in full. It enumerates the returned fields and contrasts with list_agents by specifying a single agent, so an agent can distinguish it from 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?

Explicitly says to read it before update_agent when changing instructions rather than replacing them. This names the relevant alternative and gives the condition that selects this 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered without description help. The description adds genuine behavioral context beyond that: a state-dependent branch (`answering` false = agent not deployed) with a required next action. It doesn't discuss freshness or whether the link is stable/revocable, which keeps it off a 5.

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

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

The purpose is front-loaded, but the body is a long, clause-chained sentence that mixes return-value documentation (`url`, `tellUser`, `answering`, `installSnippet`) with sales-style instructions ('a bio, an email signature, order emails, a help center'). Since an output schema exists, the field-by-field enumeration is partly redundant, and the installSnippet explanation arrives after the workflow advice rather than alongside its counterpart.

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 zero parameters, the remaining burden is workflow context, and the description supplies it: when to offer the link, the deploy prerequisite branch, and what the second artifact is for. An agent could act on this without consulting a sibling or guessing at preconditions.

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 there is nothing for the description to disambiguate and the baseline of 4 applies. The description instead spends its words on output fields, which is not a parameter concern.

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 ('Get the workspace's Aide chat page') and immediately defines it as 'a public link (`url`) where anyone chats with Aide.' It also separates that from the `installSnippet` artifact, so the agent can distinguish the two outputs. It stops short of a clean one-line definition because the purpose statement is intertwined with workflow prescriptions.

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 sequencing: 'Offer it right after test_agent,' then handle `answering` false by asking for the OK and calling deploy_agent in the same turn. It also names the follow-up (installSnippet) as 'second,' so both ordering and the exclusion of the website path from the first step are 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, destructiveHint=false and closed-world scope, so the description doesn't need to re-argue safety. It adds real value beyond them by disclosing that the response carries permission state ('whether it may only read or also make changes') and a diagnostic/recovery signal for refused calls. It stops short of describing error shapes or the format of the attention items.

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?

Content is front-loaded with the identity/context payload and closes with the call trigger, so an agent gets the essential framing immediately. The opening sentence is long and clause-stacked, which slightly hurts scanability, but every clause carries distinct 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?

There is no output schema, so the description bears the burden of explaining return content — and it enumerates the payload (workspace, app, teammate, role, permissions, attention items) thoroughly. Combined with the usage triggers, an agent has enough to call it and interpret the result, though return-shape detail (flat vs nested, list vs scalar) 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?

The tool takes zero parameters, and the description correctly spends no space on input semantics. Baseline for a no-parameter tool is 4, and nothing here suggests otherwise.

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 is explicit about what the tool returns: the workspace, app, signed-in teammate, that teammate's role, read-vs-write capability, and outstanding attention items. That's a concrete enumeration an agent can act on. It doesn't differentiate from nearby siblings like get_setup_status or get_customer_context, 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?

Two explicit triggers are given: 'when a call is refused' and 'before explaining what you can do.' That's clear contextual guidance rather than implied usage. No when-not conditions or named alternatives are provided, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description usefully expands on what is actually returned (handoff state, custom fields), but says nothing about permissions, rate limits, or behavior for a missing/invalid id. Adding field coverage beyond the annotations earns a solid 3.

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

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

Two tight sentences: the first front-loads the core action and returned fields, the second is a single routing pointer. 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?

With no output schema, the field enumeration does real work in telling the agent what comes back, and the pointer to list_messages correctly prevents the agent from expecting message bodies. It could be slightly more complete about absent/invalid id behavior, but for a simple single-id read it is nearly sufficient.

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 a single parameter at 100% schema description coverage, the schema already documents the id and its `cnv_…` format and origin. The description adds no syntax or sourcing detail beyond that, 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 ('Read one conversation') and then enumerates the exact fields returned (subject, status, priority, customer, assignee, team, topics, channel, handoff state, custom fields). This distinguishes it cleanly from find_conversation (search) and list_messages (message retrieval), both of which appear in the sibling list.

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

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

The description routes the agent to list_messages for message content, which is a genuine when-to-use-elsewhere signal, and the schema notes the id comes from find_conversation. It stops short of stating exclusions (e.g., that this does not fetch orders or messages), so it is clear context without full alternative coverage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real behavioral detail beyond them — newest-first ordering, match method and verification status, and the chat-only extras (viewed product/collection, cart). It omits any pagination or result-count limits, 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?

Front-loaded with the core action, then a dense but purposeful enumeration of returned fields, closing with a routing hint. The long field list is informative rather than padding, though it could be trimmed slightly.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: order identity, status, totals, refundable amount, items, fulfillments, tracking, shipping address, plus chat-specific context. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single conversationId parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no format, prefix, or sourcing detail 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 and resource ('Read the store customer matched to a conversation ... and their Shopify orders') and pins the scope to a conversation, which separates it from lookup_orders and list_conversation_order_actions 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 concrete downstream routing ('Use an order's id with refund_order, cancel_order and check_return_eligibility'), which tells the agent what this tool feeds into. It does not state when to prefer it over lookup_orders or get_customer_context, so it stops short of explicit alternatives/exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description goes beyond that by disclosing the empty-result behavior ('Empty when no CRM is connected or nothing matched') and the shape of what is returned (workspace-chosen fields plus match rationale), which are genuinely useful traits not in 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?

Two tight clauses with zero filler; the resource and scope are front-loaded before the empty-state caveat. Every phrase 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?

There is no output schema, yet the description still conveys what comes back (matched CRM records, displayed fields, match reasoning) and the empty case. Nothing essential to calling 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?

With a single parameter at 100% schema coverage, the schema already documents conversationId fully (including its `cnv_…` format and provenance). The description adds no syntax or format detail beyond the schema, 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 ('Read') and a precise resource ('CRM records (Salesforce contacts, accounts or leads) matched to a conversation's customer'). No sibling tool provides CRM context, so an agent can distinguish this immediately from get_conversation or get_conversation_orders.

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

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

The description implies its use case (fetching CRM context for a conversation) but never states when to reach for it versus alternatives or any prerequisites. There is no explicit when/when-not guidance, leaving the trigger to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely useful behavior not in the annotations: the draft is sourced 'with its sources' and the tool returns `data: null` when no draft exists, which tells the agent how to handle the empty case.

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 purpose and followed by the null-return edge case. No filler or restated 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?

For a one-parameter read tool there is no output schema, and the description compensates with the null-result behavior and a hint about included sources. What the draft object looks like is still unspecified, 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?

Schema coverage is 100% for the single conversationId parameter, and the schema even documents the `cnv_…` format and points at find_conversation. The description adds no parameter detail beyond that, 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+resource ('Read Aide's current reply draft') and disambiguates the resource by explaining what a draft is ('the Copilot draft teammates see'), which separates it from list_messages/get_conversation. It stops short of naming a sibling tool to route against, so it is clear but not fully differentiated.

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

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

The description never says when to call this versus get_conversation, list_messages, or reply_to_conversation, nor any prerequisite such as obtaining conversationId first. The only implicit signal is the word 'current', which is not real usage 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful return-content detail (it returns the full body plus title, link, source, collection, status), which matters because there is no output schema to convey that.

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

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

One sentence, front-loaded with the verb and scope, with every listed field earning its place by compensating for the missing output schema. 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 simple one-parameter read tool whose annotations cover the safety profile, the description is nearly sufficient: it tells the agent what it gets back despite there being no output schema. Minor gaps remain around error behavior for an unknown id, but 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?

There is a single required parameter with 100% schema description coverage, so the schema already documents documentId. The description adds nothing about the parameter, which is the expected baseline when the schema does the work.

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 one knowledge document in full'), and by enumerating returned fields (title, link, source, collection, status, body) it makes clear this is full-document retrieval rather than the list/search siblings. It does not name list_knowledge_documents or search_knowledge explicitly, so the differentiation is inferable rather than stated.

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

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

The description contains no when-to-use, when-not-to-use, or alternative-tool guidance. The only routing signal is indirect, via the schema noting the id comes 'from search_knowledge', which is not part of the description text itself.

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, non-destructive and closed-world, so the safety profile is covered. The description adds valuable behavioral context by disclosing the actual return fields and that an error is surfaced when an import failed, which is meaningful for a tool with no 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 tight sentences that front-load the purpose before the usage hint; nothing is wasteful. The first sentence's phrasing ('such as a website add_website started') is slightly awkward but does not harm comprehension.

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

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

With no output schema, the description must convey what comes back, and it does (status, import progress, documentCount, failure error). For a single-param, read-only tool this leaves the agent nothing essential 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 sourceId parameter and its origin (add_website, list_knowledge_sources, get_setup_status) are already fully documented. The description references the source loosely but adds no syntax beyond what the schema provides, 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 singular resource ('Read one knowledge source'), and the enumeration of returned fields (status, import progress, documentCount, error) makes the scope unmistakable. It is clearly distinguishable from the plural sibling list_knowledge_sources and from get_knowledge_document 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 a concrete usage scenario: 'Use it to tell the user when Aide has finished learning a site.' This is clear context for invoking it. It does not name alternatives or exclusions (e.g. list_knowledge_sources for enumeration), so it falls short of the when/when-not standard.

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, non-destructive, closed-world, so the bar is low; the description still adds real value by disclosing the response shape (no output schema exists) and clarifying that `draft` holds not-yet-live edits in the same shape or null. It stops short of stating behavior for a missing/invalid procedureId.

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, front-loaded with the action and colon-introduced field list, followed by one short imperative. The enumeration is long but every item is a distinct returned field, so little could be cut without losing information an agent needs absent an output 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?

For a one-parameter read tool with annotations and no output schema, the description successfully substitutes for a return-value spec by naming the major fields including the conditional `draft`. Minor omissions — error/not-found behavior and the read-before-write rationale — keep it below top marks.

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 a single parameter at 100% schema coverage and a schema description that already tells the agent to source the id from list_procedures, the schema does the work. The description adds no format, validation, or sourcing detail beyond it, 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 and resource ('Read one procedure in full') and then enumerates exactly what is returned — When to use, examples, channels/inboxIds/mediums, steps, finish, subject-change behavior, status, draft. This clearly separates it from list_procedures (plural) and get_draft, though the description never names those siblings directly.

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

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

The closing line 'Read it before changing it' gives a concrete workflow rule that implies when to call it, and 'one procedure' implies list-then-get. There is no explicit when-not guidance or named alternative, so usage is implied rather than 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 declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safeness is covered. The description adds real context the annotations do not: the payload is a 'synced' mirror (implying freshness/consistency caveats versus live Shopify data) and the exact breadth of the returned record. It stops short of noting not-found or stale-sync 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?

One sentence, front-loaded with verb and object, then the enumeration of returned fields. No filler, no repetition of the title, and 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?

With no output schema, the description correctly carries the burden of describing the return payload and does so thoroughly. The only gap is failure modes (unknown/deleted product id) and any pagination of variants, which an agent might want before calling.

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% for the single productId parameter, and the schema itself documents where the id comes from ('from list_products'). The description adds nothing about the parameter, 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 ('Read one') and resource ('synced Shopify product') and immediately enumerates what 'in full' means: description, variants with prices and stock, images, collections, tags, metafields, links. The word 'one' plus the enumeration cleanly distinguishes it from the list_products sibling without needing to name it.

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

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

There is no explicit when-to-use, no when-not-to-use, and no alternative tool named. The scope of the returned payload implies the tool is for detail views rather than browsing, but the agent must infer that list_products is the entry point; the description never says so (only the schema does, via 'from list_products').

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, destructiveHint=false), and the description adds real behavioral context by disclosing the return payload shape and the iterate-and-recheck cadence. It stops short of stating edge cases such as what 'skipped' means operationally or whether nextStep can be null, which keeps it off 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?

Effectively one long sentence, but it is front-loaded with the core purpose and every clause adds non-redundant information (state values, detail semantics, tool vs url, call ordering). Dense rather than wasteful, though it could be broken into two sentences for 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?

With no output schema, the description carries the full burden of describing the result and does so field-by-field, while also covering sequencing and the dashboard alternative. An agent has everything needed to call this first and act on the response.

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 per the rubric the baseline is 4. There is nothing for the description to disambiguate on the input side, and it correctly does not invent parameter guidance.

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 precise verb and resource ('Check how far the workspace is from Aide answering its customers') and enumerates the exact states returned (live, nextStep, per-step status/detail/tool/url). This is unmistakably the onboarding-progress reader and cannot be confused with siblings like get_agent or analytics_summary.

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 call it ('first when the workspace is new or not live'), how to proceed ('do the steps in order, past any that waits on an import or the user'), and to re-call 'after each' step. It also resolves the dashboard-vs-tool choice ('prefer the tool'), giving a real alternative with a selection rule.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, lowering the bar, and the description goes beyond that by disclosing a concrete workflow detail: the forwarding confirmation code exists specifically to be entered into Gmail's settings. What it omits is failure modes (e.g., behavior when forwarding is not yet set up or the mailbox is missing).

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

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

A single front-loaded sentence that opens with the verb+resource and then enumerates outputs. The trailing parenthetical about Gmail's settings is worth its length, though the sentence is dense enough that it borders on overloaded.

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 carries the return-value burden and does enumerate the key fields, including the nested forwarding.confirmationCode. It lacks the mailbox-not-found/failure semantics, but for a single-param read tool it is close to complete.

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

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

With schema description coverage at 100% and only one parameter, the schema already documents mailboxId and even its source (add_support_email or get_setup_status). The description adds no syntax or format detail about the id, 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 and resource ('Read one support mailbox') and enumerates the returned fields (supportAddress, inboundAddress, forwarding status, forwarding.confirmationCode). It does not explicitly contrast itself with the sibling add_support_email or get_setup_status, but the read-one contract is unambiguous.

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

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

Usage is only implied: it is a getter for a single mailbox. The description does not state when to reach for this versus add_support_email (write) or get_setup_status, nor does it name exclusions. Adequate but leaves the routing inference to the agent.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine context beyond them by disclosing what the read returns — rollout (who receives replies), quiet period, and their `sources` — useful because there is no 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?

A single front-loaded sentence with no filler, and the returned concepts are named immediately. Slightly compressed jargon ('rollout', 'sources') is used without explanation, 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?

For a single-parameter read-only getter with no output schema, the description covers the essentials by naming the settings returned. A note on whether an unconfigured mailbox returns defaults or errors would close the 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 coverage is 100% and the mailboxId property already explains where the id comes from (add_support_email or get_setup_status). The description adds no further semantic detail about the parameter, 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-and-resource pair: read the reply configuration ('how Aide answers a support mailbox'), naming rollout and quiet period. It is distinguishable from get_support_email in practice, but the description never explicitly contrasts with that sibling or with update_support_email_settings, so the separation relies partly on the tool name.

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: it is the read counterpart to update_support_email_settings, which the agent must infer from the near-identical name. There is no explicit 'use this before updating' or 'use get_support_email instead for X' 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, non-destructive, closed-world, so the safety profile needs no restating. The description goes beyond them by explaining what each returned flag means operationally ('assigned' = this agent, 'answerable' = Aide can answer, 'replies' = sent vs drafted), which is real behavioral context absent from the annotations. It omits any mention of pagination behavior, though the schema covers that.

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

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

One front-loaded sentence starting with the verb and resource, followed by the result shape, with the follow-up action last. The parenthetical channel enumeration is long but earns its place by defining an ambiguous term; no filler sentences.

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

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

With no output schema, the description usefully enumerates the returned fields, and the readOnly annotations plus fully documented schema cover the rest. An agent has enough to call it and interpret the response; only pagination and ordering/empty-result behavior are 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 coverage is 100% and every parameter (page, agentId, perPage) is documented in the schema, including where agentId comes from. The description adds only that returned ids feed set_inbox_ai, which is workflow rather than parameter semantics. 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 ('List the inboxes an AI agent can answer') and immediately disambiguates what a 'channel' is by enumerating the concrete sources (chat widget, support mailboxes, helpdesk, Gmail inboxes). This distinguishes it from sibling listers like list_agents or list_integrations 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?

The closing line 'Use an id with set_inbox_ai' gives a concrete next-step workflow, signaling this is a discovery step before configuring an inbox. It lacks an explicit when-not or a named alternative among the many list_* siblings, but the context for use 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?

The annotations already declare read-only safety (readOnlyHint=true, destructiveHint=false), and the description adds useful behavioral context: it returns IDs, names, and statuses, and guarantees that every workspace starts with at least one agent. It does not cover pagination or error behavior, but the schema handles page/perPage and the annotations cover the safe-read 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?

Two sentences, front-loaded with the list operation and immediately followed by actionable downstream context. No wasted words, and the key scoping detail ('workspace's AI agents') appears 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 simple read-only list tool with no output schema, the description covers the returned fields and the workspace guarantee, while the schema and annotations handle parameters and safety. Nothing critical 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?

Schema description coverage is 100%, so each parameter (page, status, perPage) is already documented in the input schema. The description only repeats the status enum already present in the schema and adds no further syntax, defaults, or filtering semantics, so the baseline score of 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 description states a clear verb and resource: 'List the workspace's AI agents', specifies the returned fields (ids, names, status) and enumerates the status values. It also distinguishes the returned IDs as inputs for sibling tools get_agent, update_agent, test_agent, and deploy_agent, so an agent can separate this from single-agent retrieval tools.

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

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

It provides clear context by explaining the result's downstream use: 'Use an agent's id with get_agent, update_agent, test_agent and deploy_agent.' This implies listing is the way to discover IDs when you do not already have one, but it does not explicitly state when to prefer this over alternatives like get_agent or list_agent_channels.

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, destructiveHint=false, openWorldHint=false), so the bar is lower. The description does add real value beyond them: result ordering, the fields returned per change, the documented blind spot about which AI app acted, and the pagination mechanism. It stops short of stating default page size or default date window, which matter for a list tool with all-optional parameters.

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 compact sentences, front-loaded with purpose, then a caveat, then the pagination note. No filler or marketing language. The cursor sentence largely duplicates the schema description, which is the one trim available.

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

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

With no output schema, the description correctly compensates by naming the returned fields and the sort order, and it explains how to page. The stated limitation on AI-app attribution preempts a likely agent assumption. Remaining gaps are minor: defaults for `perPage` and the date range, and how to interpret a null cursor at the end of results.

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%, including the enum meanings for `via` and `resourceType`, so the schema already carries the semantics and the baseline of 3 applies. The one parameter the description touches, `cursor`, only restates the schema's own 'metadata.nextCursor of the previous page' wording. Nothing is added for `from`/`to`/`perPage` semantics such as defaults or inclusive/exclusive boundaries.

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 ('list what AI apps changed in the workspace'), plus the ordering ('newest first') and the shape of each returned change. It even discloses a limitation ('does not tell apart which AI app made a change'). It never names the nearest sibling (list_operations), so sibling differentiation is left implicit rather than explicit.

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

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

Usage is implied rather than stated: an agent can infer this is the audit view for AI-app-driven mutations, satisfying the 'when'. There is no explicit 'when not', no mention of how this relates to list_operations or list_messages, and no prerequisites (e.g., whether a date range is required in practice).

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 a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds real context: results are newest first, and `pending_approval` means an admin must act. It also names the returned fields, useful since no output schema exists.

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

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

A single, front-loaded sentence that states the resource, the scope, the ordering, and the returned fields with no filler. Dense but every clause earns its place.

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

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

For a read-only list tool with full schema coverage and no output schema, the description compensates by enumerating the returned fields and ordering, which is what an agent needs to consume results. Only the routing versus the sibling list_order_actions is 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 description coverage is 100%, so the schema already documents all four parameters, including the status enum and pagination bounds. The description only adds meaning to the `pending_approval` status value inline; 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 description gives a specific verb+resource ('List the order actions ... on a conversation's orders') and enumerates the kinds of actions covered (refunds, cancellations, address changes, returns). It scopes the resource to a conversation, but never explicitly distinguishes itself from the similarly named sibling list_order_actions, so sibling differentiation is left to inference.

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

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

Usage is implied by the scope ('a conversation's orders'), which tells the agent this is the per-conversation view, but there is no explicit when-to-use/when-not guidance and no mention of the alternative list_order_actions or get_conversation_orders. The agent must infer the routing from the name alone.

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?

While annotations confirm it is a read-only operation, the description adds behavioral context by listing specific attributes returned (`id`, `name`, `needsReauth`), which helps the agent understand the operational state of the connection 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?

The tool is described in a single, highly efficient sentence. It front-loads the purpose and efficiently lists all necessary details about the returned data.

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

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

Since no output schema exists, the description fulfills the requirement for completeness by explicitly enumerating the key data points the agent can expect to receive upon successful 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?

Given that the input schema is empty, the description is vital. By listing output fields like `id`, `name`, `category`, and `needsReauth`, it provides semantic meaning to the data the agent will receive, making it maximally useful.

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 identifies the resource (workspace connections/integrations) and provides specific examples of the connection types (Shopify, Gmail, Salesforce), distinguishing it from broader list functions.

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

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

It provides a critical usage hint by stating that the returned `id` should be used for subsequent calls to 'other channel tools,' establishing the required operational workflow.

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, destructiveHint=false and openWorldHint=false, so safety needs no restating. The description adds genuinely non-obvious behavior beyond them: default ordering is newest first, and supplying q switches ordering to best match. It does not mention pagination defaults, though the schema's page/perPage docs already cover hasMore.

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

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

Two sentences, zero filler. The primary purpose and returned fields are front-loaded, and the routing guidance follows as a compact contrast between the three knowledge tools.

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 8 optional parameters and no output schema, the description carries the burden of telling the agent what comes back, and it does so by listing the returned fields plus the ordering rule. Combined with the sibling routing hints and fully documented schema, 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 description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: q is not merely a filter, it changes result ordering to relevance, and the parenthetical kind list mirrors the enum for at-a-glance recognition. It stops short of explaining the interaction between q and the kind/status/starred filters.

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 the workspace's knowledge documents), enumerates the document kinds covered, and names the exact fields returned (ids, titles, source ids, kinds, status, excerpts, links). It also distinguishes itself from both get_knowledge_document and search_knowledge by name, so an agent can route 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?

The closing sentence gives explicit alternatives with selecting conditions: read one in full via get_knowledge_document, answer a question via search_knowledge (which ranks passages instead). That leaves no ambiguity about when this enumeration tool is the right choice versus the retrieval 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 already establish that this is a safe read-only operation, and the description adds useful behavior beyond that: gaps are ordered most-conversations-first, each includes rationale, related article, conversation count, and a proposed fix type. It does not describe pagination or the full response metadata, but the schema covers paging parameters.

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 and then adds the ordering, returned fields, and remediation flow. It is dense but mostly earns its space; the fix-type list and field-replacement detail are useful, though the sentence is packed.

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 listing tool with a rich input schema and no output schema, the description is mostly complete: it explains the gaps, ordering, key returned fields, and next actions. The main remaining gap is that the short fix-type list does not cover all `kind` enum values, which could leave some filter semantics 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%, so the baseline is 3. The description adds useful context about what a gap contains and how fixes map to downstream tools, but it does not explain the full 18-value `kind` filter or clarify how its short fix-type list relates to all enum options.

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: list knowledge gaps where Aide drafts fell short of teammate replies. It also distinguishes this tool from sibling knowledge tools by describing what a gap contains and naming the downstream tools used to fix or close one.

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

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

The description gives clear context for when this list is useful and names the resolution path: fix with add_knowledge_article, update_knowledge_article, publish_knowledge_document, or update_agent, then mark_knowledge_gap_done. It does not explicitly compare this listing tool with sibling listing tools or state when not to use it.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds useful payload context (ids, kinds, document counts) but says nothing about ordering, pagination behavior beyond the schema, or result limits, so it adds only modest value on top of 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?

Two short sentences with zero filler; the resource and its returned fields come first, and the follow-up action is the second sentence. Nothing is redundant with the title or annotations.

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

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

With no output schema, the description usefully names the returned fields (ids, kinds, document counts) and pagination is fully covered by the schema. It is nearly complete for a simple read-only list tool, though a note on ordering or an empty-workspace case would close the 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% and both parameters (page, perPage) are documented in the schema including the metadata.hasMore hint. The description adds no parameter-level meaning at all, 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?

Specific verb (List) plus resource (workspace's knowledge sources) with an explicit enumeration of what a source is (help centers, websites, files) and what fields come back (ids, kinds, document counts). It is clearly distinguishable from siblings like list_knowledge_documents and search_knowledge.

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 onward: 'Use the ids to narrow search_knowledge,' which tells the agent this is the discovery step before a filtered search. It does not, however, contrast itself against the closest sibling list_knowledge_documents, so the when-not guidance is incomplete.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by enumerating what comes back (ids, names, emails, roles, teams with team ids, availability), which matters given there is no output schema. It says nothing about pagination defaults or rate 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 load-bearing: the first states the resource and return shape, the second routes the returned ids to their consumers. 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 zero-required-param list tool with read-only annotations, the description is nearly complete: it covers return fields (compensating for no output schema), pagination is handled by the schema, and id semantics are explained. Only minor omissions, such as default page size behavior, remain.

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

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

Schema description coverage is 100% and both parameters (page, perPage) are already fully documented with bounds and the metadata.hasMore follow-up signal. The description adds nothing about parameter behavior, 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?

Specific verb (List) plus resource (workspace's teammates) with the exact fields returned enumerated. An agent can distinguish this from list_macros, list_products, list_topics 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 concrete downstream usage: 'Use a teammate id as update_conversation's assigneeId and a team id as its teamId.' This is a clear cross-tool linkage. It doesn't state when *not* to use this tool or any prerequisites, which is why 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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds behavior beyond that: page ordering (newest page first, oldest-to-newest within a page) and the cursor lifecycle (meta.nextCursor, null on the oldest page), which an agent cannot infer from 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?

Two sentences, no filler. Scope and ordering come first, then the pagination instruction, so the most decision-relevant 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?

There is no output schema, and the description compensates by disclosing the meta.nextCursor envelope and the in-page ordering, which is what an agent needs to page correctly. It does not describe message fields or whether internal notes are permission-gated, but for a straightforward read-list tool this is close to complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds meaning beyond the schema: it explains that `before` is fed from the page's meta.nextCursor and that its null value signals the oldest page, clarifying the cursor's provenance and termination condition. It does not elaborate on `limit` 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 ('List a conversation's messages, replies and internal notes') plus the ordering contract, so it is clearly distinguishable from get_conversation, reply_to_conversation and add_note. It stops short of naming a sibling or scoping itself against one, so it is clear but not fully differentiated.

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

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

The second sentence gives real guidance on when to use the `before` parameter (to page to older messages), which is genuinely useful. However, there is no guidance on when to choose this tool over get_conversation, search or list_* siblings, so usage is only partially addressed.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds meaningful context beyond that: results are filtered to what 'this connection can run' and each entry carries name, title, description, kind, and inputSchema, which tells the agent how to chain into a run_* tool. Return breadth and any truncation behavior remain undocumented, so it adds value but not rich depth.

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 verb and resource, followed immediately by the return shape and the routing to the run_* tools. No filler, no 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?

With no output schema, the description correctly compensates by enumerating the returned fields (name, title, description, kind, inputSchema) and explaining the permission scoping. Combined with a 100%-covered enum schema and full annotations, an agent has what it needs; only chaining specifics, such as passing the returned inputSchema into the matching run_* tool, are 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% and the single enum parameter already spells out all ten areas in detail, so the schema carries the burden. The description only contributes the scoping phrase 'in one area that this connection can run', adding little per-parameter meaning beyond what is already structured.

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 the Aide API operations'), the scope ('in one area that this connection can run'), and the exact shape of each item returned. It is clearly distinguishable from the domain list_* siblings (list_topics, list_procedures) because it enumerates API operations rather than domain objects.

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

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

The second sentence names the alternatives explicitly — run_read_operation, run_create_operation, run_update_operation, run_delete_operation — so an agent knows this tool discovers and those execute. It stops short of an explicit sequencing rule ('call this first, then run_* with the returned inputSchema') or a when-not-to-use statement, which keeps it from 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 (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's added value is the ordering guarantee ('newest first'), the returned field set, and the semantic meaning of the pending_approval status. No permissions or rate-limit caveats, but for a read-only list tool this is solid added context.

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

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

Two tightly packed sentences with zero filler; the identity and scope of the tool come first and the approval-queue hint is placed last where it is most actionable.

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

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

With no output schema, the description usefully enumerates the returned fields (status, amount, order, conversation, reason, result, requester/approver), and the schema handles paging via metadata.hasMore. It is essentially complete for a read-only list tool, though it does not address ordering stability or empty-result behavior.

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 documents page, perPage, and every enum value including pending_approval. The description's remark about the approval queue restates what the status enum description already says, adding little 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 ('List the workspace's order actions'), enumerates what counts as an action (refunds, cancellations, address changes, returns), and scopes it to the workspace, which separates it from the conversation-scoped sibling list_conversation_order_actions.

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

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

The note that '`status: pending_approval` is the approval queue' implies a usage pattern, but the description never explicitly says when to pick this tool over list_conversation_order_actions or when to filter by status versus paging through everything. Usage is inferable but not 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 declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: result ordering (most recently changed first) and the full status vocabulary, including the non-obvious `_with_draft` value meaning edits are staged and not yet live. It does not mention pagination limits, though the schema covers those.

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 action and ending with the sibling routing. The long parenthetical defining a procedure and its status values is dense but each clause carries information an agent needs. Slightly heavy nesting 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?

No output schema exists, so the description compensates by naming the fields returned (ids, names, When to use, status, run frequency) and the sort order. Combined with schema-documented pagination, an agent has everything needed to call this correctly 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 description coverage is 100%: both pagination parameters carry ranges and the schema explains that `metadata.hasMore` signals another page. The description says nothing about paging or page size, so it adds no meaning beyond the schema. 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 and goes further by defining what a procedure is ("what Aide does for one kind of customer message: steps to follow, details to collect, how it finishes"). It also enumerates the returned fields and explicitly distinguishes itself from get_procedure, so an agent can separate the two 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?

The final sentence routes the agent clearly: use this to enumerate, use get_procedure to read one in full. That is an explicit alternative with a stated condition. It stops short of saying when listing is not appropriate (e.g. when the id is already known and a direct get would suffice), so it is strong but not complete.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the useful constraint that results are scoped to the workspace's synced Shopify products, but says nothing about pagination or result ordering beyond what the schema's `page`/`metadata.hasMore` already states.

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

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

One front-loaded sentence carrying scope, search targets and return fields, followed by a one-clause routing pointer. No filler and nothing 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?

With no output schema, enumerating returned fields (id, title, vendor, status, price range, availability, variant count, storefront link) is exactly the right compensation. Pagination mechanics are left entirely to the schema, which handles them, so 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%, so every parameter (q, page, status, perPage, sourceId, integrationId) is already documented in the schema. The description only restates the q match targets, adding no new semantics; baseline 3 applies.

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

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

States a specific verb and resource ('List the workspace's synced Shopify products'), the match fields q searches, and the exact fields returned. It explicitly contrasts with the sibling get_product, so an agent can pick between list and single-read 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?

'Read one in full with get_product' names the alternative and the condition (need full detail) that selects it. No exclusion guidance on the filter parameters (status, sourceId, integrationId), but the list-vs-get branch 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 readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds value the annotations do not: workspace scoping and the shape of the response (ids, names, category, conversation counts), which matters because there is no 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 with no filler; the definition of the resource is parenthetical and the actionable chaining advice comes second. Nothing is wasted and the purpose 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 compensates by naming the returned fields, and pagination semantics live in the parameter descriptions. For a simple read-only list tool, an agent has everything needed to call it and use 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 description coverage is 100%, and the schema documents q, page, and perPage with bounds and the metadata.hasMore hint. The description adds no parameter-level syntax or format detail beyond that, 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 ('List the workspace's topics'), then defines what a topic actually is ('what customers write about; Aide tags each conversation with them') and enumerates the returned fields. It also names the sibling tools that consume the ids, so an agent can place it precisely among find_conversation and the analytics tools.

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

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

Gives a concrete downstream use case: 'Use the ids to filter find_conversation and the analytics tools,' which tells the agent why to call this before those tools. There is no explicit when-not or alternative-listing, but the chaining context is clear enough to route correctly.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely non-structured behavior: results are ordered newest first and each row carries status, totals, items, fulfillments and tracking. No auth or rate-limit context, but the added behavioral detail is real.

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, front-loaded with the verb and resource, with the match semantics and return shape following in priority order. No filler and nothing that fails to earn 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?

With no output schema, the description usefully compensates by enumerating the returned fields, and the annotations carry the safety profile. It stops short of covering no-match behavior or error conditions, but for a read-only lookup it is close to complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by spelling out the conjunction rule ('then an order must match both') and the newest-first ordering with a 20-per-page cap, semantics the schema does not state.

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 specific verb ('Find') and a precisely scoped resource ('the workspace's synced Shopify orders'), and states the three lookup keys (email, order number, or both). This scope distinguishes it from conversation-scoped siblings like get_conversation_orders and list_order_actions without needing to name them.

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

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

It conveys how to query (by email, order number, or both) and the AND semantics when both are supplied, which implies its usage. But it never states when to reach for this tool over siblings such as get_conversation_orders or search, and gives no exclusions or prerequisites.

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 is a non-read-only, non-destructive, closed-world mutation, and the description adds genuinely new facts: it is a state transition only, it does not perform the underlying fix, and it returns the gap. It does not say whether the transition is reversible or whether re-marking an already-done gap errors, which keeps it below 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 short sentences, front-loaded with the action and its precondition; the parenthetical clarification prevents a costly misreading and earns its place. No filler whatsoever.

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 mutation with no output schema, the description covers the precondition, the effect boundary, and the return value ('Returns the gap'). Only idempotency/undo behavior on an already-done gap is left 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?

Single parameter with 100% schema description coverage, including provenance ('from list_knowledge_gaps'), so the schema does the work. The description adds nothing about the gapId beyond what the schema states, which is the expected baseline 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?

States a specific verb and resource ('Mark an open knowledge gap done') and scopes it with the precondition that the fix already exists. It implicitly separates itself from fix-creation tools, but never names sibling alternatives such as dismiss_knowledge_gap or update_knowledge_article.

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?

'once its fix is made' gives a real trigger condition for calling the tool, which is more than most mutation tools offer. However, it gives no guidance on the closely related dismiss_knowledge_gap or on what to do if the gap is already done, leaving the competitive choice to inference.

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

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

Annotations only say this is a non-read-only, non-destructive, closed-world mutation; the description adds real substance on top — configuration is preserved, the change is reversible via deploy_agent, and the returned record carries status `paused`. It stops short of stating permissions or the effect on in-flight conversations.

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 user-visible effect, then the reversal path, then the return shape. Nothing is padded or repeated.

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 purpose, state preservation, reversal, and even the return payload in the absence of an output schema, which is enough for a one-parameter toggle. Only authorization requirements are unaddressed, a minor omission for this 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 description coverage is 100% for the single agentId parameter, which already documents the string and its source (list_agents). The description adds no extra meaning about the parameter, 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 ('Stop a deployed AI agent from answering customers') plus the operative consequence that teammates take over the replies. It also names the inverse operation (deploy_agent), so an agent can distinguish pause from deploy/resume 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?

Clearly explains the situation that calls for this tool (handing customer replies back to teammates) and points to deploy_agent as the way to undo it. There is no explicit 'when not to use' clause, but the use case 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?

Beyond the annotations (readOnly=false, destructive=false), the description discloses two non-obvious consequences: the article appears in Aide Chat's public help section and affects customer answers immediately unless usedByAide is false. It omits error and idempotency behavior, but for a non-destructive toggle the 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?

The action is front-loaded in the first clause and every sentence carries behavioral information. The subclause 'unless it is not used by Aide (`usedByAide` false)' is slightly convoluted and could be stated more directly, keeping it from a top score.

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, non-destructive publish tool with no output schema, this covers the trigger, visibility consequences, type exclusions, and a brief note on the return value ('Returns the document'). Only side-effect nuances such as re-publishing or failure modes are left 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% and the single documentId parameter is fully documented there, including where to obtain it. The description adds only implicit meaning about which document types are valid (drafts, not snippets), which is a small increment over 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?

The description opens with a specific verb+resource, 'Publish a draft article', and clarifies that snippets cannot be published, which implicitly separates this from unpublish_knowledge_document and update_knowledge_article. It stops short of naming any sibling tool explicitly, so an agent must infer the boundaries.

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 (an article a knowledge gap proposes publishing) and a clear exclusion (snippets are internal and can't be published). It does not say what to do instead when the target is a snippet or how to edit before publishing, so routing guidance is imperfect.

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 destructive/openWorld annotations by disclosing the approval-gating flow ('a refund above their limits waits for an admin'), the meaning of the result ('says whether it ran or waits'), and critically the lack of idempotency ('repeated calls are not deduplicated: calling it again refunds again'). That last point is exactly the kind of side-effect disclosure an agent needs before calling a destructive 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?

Four sentences, each carrying distinct load (identity/scope, approval flow, amount default, idempotency). The core purpose is front-loaded and no sentence is filler.

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

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

For a destructive mutation with no output schema, it covers identity, approval, default amount behavior, and repeat-call effects, and hints at the response shape. It does not address failure cases (e.g., non-refundable or already-fully-refunded orders) or any partial-refund edge cases, so it is strong but not exhaustive.

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 all six parameters including amount omission and requestApproval semantics. The description reinforces the amount-omission rule but adds no syntax or format detail beyond what the schema provides, making the baseline 3 correct.

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 ('Refund an order') and adds real scope: the conversation context, the Shopify store, and the acting identity ('as the signed-in teammate'). It is unambiguous what the tool does, though it never explicitly contrasts itself with near-siblings like cancel_order or approve_order_action, so it falls 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 usage context: when to pass an amount vs omit it, when approval rules intervene, and how requestApproval changes behavior. It also warns about re-invocation. It never names an alternative tool or an explicit 'use X instead' exclusion, so it stops 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=false, destructiveHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds genuinely new behavior: the import runs in the background, returns immediately with status 'importing', and must be polled with get_knowledge_source. It does not say what happens to already-imported pages on re-import, which is the main unresolved risk for a re-import operation.

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 action and followed by return/polling behavior; every clause carries information. The nested parentheticals ('the source address when omitted, on the same site; another site is add_website') are dense but compact rather than 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?

With no output schema, the description correctly compensates by naming the return shape ('the source with `status` `importing`') and the tool to confirm completion. For a 3-parameter, open-world mutation it covers the essentials, falling short only on how re-import interacts with existing imported pages and any permission or rate constraints.

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 beyond the schema: imported scope is 'its pages at and under `url`', and `url` is described as a corrected address that defaults to the source address on the same site. maxPages is left entirely to the schema, so this is not a full 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?

The description states a specific verb and resource ('Import a website or help center source again') and scopes the operation to a re-import of an existing source, naming the sibling that handles the nearby case ('another site is add_website'). An agent can distinguish this from add_website and list_knowledge_sources 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 gives the selecting condition explicitly ('such as one whose import failed'), the alternative for a different case (add_website for another site), and the follow-up tool to verify the result (get_knowledge_source). The 'again' framing also implies it is not the tool for creating a new source.

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 real behavioral context: the action 'never runs' after rejection, the actor is the signed-in teammate, and the supplied reason is persisted on the action. It does not address reversibility or what happens if the action is not in pending_approval, keeping it below 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?

A single sentence that front-loads the action, the precondition, the actor, and the effect, with zero filler. Every clause carries information an agent needs.

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 with no output schema, the description covers what happens (action never runs) and what is retained (the reason). It omits edge-case behavior such as errors when the action is not pending_approval or whether the rejection can be undone.

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 actionId and reason are already documented in the schema, including that actionId comes from list_order_actions. The description's 'the reason is kept on the action' adds a small persistence nuance but nothing 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 (reject) and resource (order action) plus the gating precondition (status `pending_approval`), which is exactly what separates it from the sibling approve_order_action. An agent can identify the operation 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 clear trigger condition — the action must be waiting for approval — and implies the alternative (approval) through that same precondition. It stops short of explicitly naming approve_order_action or stating when not to use this tool, so it is clear context without full when/when-not guidance.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds the specific traits that matter: the reply reaches the customer, it cannot be unsent, repeated calls create additional replies, and the optional status moves the conversation afterward (mirroring 'Send and close'). This is exactly the extra context annotations cannot express.

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

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

Three sentences, each load-bearing: purpose and scope first, the internal-note alternative second, the irreversibility and status side effect third. No filler and the critical constraints 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?

For a mutation tool with no output schema, the description covers what the agent needs: who receives the message, that the action is irreversible, retry semantics, and the side effect on conversation status. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description exceeds it by explaining that `status` relocates the conversation after sending and by framing it against the familiar 'Send and close' behavior. It does not add anything for `snoozedUntil` or `conversationId` 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?

The description names a specific verb (send a reply), the resource (a conversation), the acting identity (signed-in teammate), and the delivery channel (email, chat, helpdesk ticket). It also distinguishes itself from the nearest sibling, add_note, so an agent can separate the two 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 alternative with the condition that selects it: 'For something only teammates should see, use add_note.' It also states the consequence of repeat invocation ('calling it again sends another reply'), which tells the agent this is not a safe retry.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered; the description's 'write that adds something' is consistent with that. It adds 'returns its result', but says nothing about failure modes, partial success, permission requirements, or that the return payload varies by operation. Useful but thin 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 front-loaded sentence that defines the action, points at the source of truth, and gives concrete examples of what 'create' covers. The docs link is unobtrusive; 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 generic open-world dispatcher, the description plus a fully documented schema tells an agent where to get both the operation and its arguments. Since there is no output schema, the phrase 'returns its result' is minimal but adequate; only the operation-dependent response shape 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% and the two parameter descriptions already say exactly what the description repeats (operation name from list_operations, arguments per the operation's inputSchema). The description adds no format, constraint, or nesting detail beyond the schema, 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?

The description gives a specific verb ('Runs') and resource ('a `create` operation of the Aide API'), and clarifies semantics with 'a write that adds something, such as a topic, a macro or a routing rule.' The create/read/update/delete split against the run_* siblings is unambiguous from 'create' plus 'adds something', though no sibling is named explicitly.

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

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

It states the prerequisite workflow clearly: the operation name comes from list_operations and the arguments come from that operation's `inputSchema`. That is real routing guidance. It does not state exclusions (e.g., when to prefer a dedicated typed tool like add_note or deploy_agent instead of this generic dispatcher), which keeps it from 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 destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the mutation risk is covered structurally. The description adds genuine value by enumerating the effect surface ('deletes, disconnects, revokes or resends ... such as a topic or an integration') and linking the API docs. It does not state irreversibility or confirmation requirements, which would matter for a destructive 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?

A single dense sentence front-loads the verb and resource, then the provenance and data source. The inline URL and the 'deletes, disconnects, revokes or resends' enumeration make it slightly heavy 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?

For a generic dispatcher-style tool with a nested arguments object and no output schema, the description supplies the data source (list_operations), the docs reference for return shape, and the breadth of effects. It is nearly complete; only irreversibility/confirmation behavior is left unstated.

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

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

Schema coverage is 100% and the schema text itself already says operation comes from list_operations and arguments follow its inputSchema. The description only restates that, adding no new syntax or format detail. A nested 'arguments' object is not further illustrated beyond the pointer.

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 ('Runs a delete operation') plus the resource (Aide API operation, sourced from list_operations) and what it returns. The delete scope implicitly distinguishes it from run_create_operation, run_read_operation and run_update_operation, though it doesn't call those siblings out by name.

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 prerequisite workflow: obtain the operation name from list_operations, and get arguments from that operation's inputSchema. This tells the agent how to call it correctly. It stops short of explicit when-not-to-use guidance (e.g., avoid this for creates/reads).

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 explicitly guarantees that the tool 'Changes nothing,' which reinforces the 'readOnlyHint' annotation by providing a strong behavioral guarantee to the agent. This provides valuable behavioral context beyond the static hint provided in the annotations.

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

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

The description is highly efficient and well-structured. It front-loads the function's purpose (Aide API read operation), provides the mechanism (via `list_operations`), and concludes with the critical safety status in just two concise sentences.

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

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

The tool is reasonably complete for an agent's decision-making. It provides documentation links, defines the scope (read), and defines the constraints (no change). Minor gaps remain regarding expected return structures, but this is often handled by output schemas.

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?

Even with 100% schema coverage, the description adds significant value by explaining that both the operation name and arguments are derived from the `list_operations` API. This tells the agent exactly where to look for valid inputs, providing critical context.

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 that the tool runs read operations from the Aide API. While it specifies 'read' operations, it relies heavily on the sibling tools and their names to distinguish it, rather than listing constraints on the operations it supports.

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

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

It provides clear usage guidance by explicitly stating that the operation 'Changes nothing.' This strongly signals when the tool is appropriate (safe information retrieval) and when it is not (for state 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?

The annotations already declare `destructiveHint: true` and `readOnlyHint: false`, and the description adds useful behavioral detail by explaining that this is a write that overwrites saved settings, with examples such as a topic or the chat widget. It does not add auth, rate-limit, or output-format details, but it meaningfully elaborates on the destructive behavior beyond the annotation.

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

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

The description is a single front-loaded sentence that states what the tool does, where the operation comes from, what it returns, and what kind of write it performs. There is no redundant or filler 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?

For a generic update-operation dispatcher with full schema coverage and annotations covering safety traits, the description provides enough context: it names the source list, explains the return, and warns that it overwrites saved settings. It could be slightly more complete by explicitly stating how it differs from the create/delete/read runner siblings, but the core information is present.

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 both `operation` and `arguments`. The description reinforces that the operation and its arguments come from `list_operations`, but it does not add syntax or detail beyond what the schema already provides, so the baseline of 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 description gives a specific verb and resource: it runs an `update` operation of the Aide API, sourced from `list_operations`, and returns the result. It also characterizes the operation as a write that overwrites saved settings, with examples like a topic or chat widget, which clearly distinguishes it from `run_create_operation`, `run_delete_operation`, and `run_read_operation`.

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 that the operation comes from `list_operations` and that this tool is specifically for update operations. This gives clear context for when to use it, though it does not explicitly state when not to use it or name the sibling alternatives as exclusions.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds meaningful behavior beyond them: the index is limited to *published* knowledge (implying drafts/internal docs are excluded) and results are ranked 'best matching' documents returned as a `results` collection. It does not mention pagination or result caps.

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: purpose and scope first, return shape second, follow-up action last. No filler, no restatement of the title, and it front-loads the most decision-relevant 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?

For a single-parameter read tool with annotations and an output schema, the description covers source scope, result shape, and the natural next step (`fetch`). The one material omission is disambiguation from the near-identically-named sibling `search_knowledge`, which an agent must resolve to pick 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?

Only one parameter at 100% schema coverage, and the schema already documents it well ('A question or keywords, in the customer's words'). The description adds no query syntax, length, or formatting guidance beyond the schema, 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 with scope: search the workspace's *published* knowledge (help center articles, website pages, other sources). It also names the return shape (`results` with `id`, `title`, `url`). However, it does nothing to distinguish itself from the sibling `search_knowledge` (or `list_knowledge_documents`), which is a real ambiguity for a tool generically named `search`.

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

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

Usage is implied by the scope (find published knowledge to cite), and it explicitly chains forward: 'Read a result in full with fetch.' But it never says when to choose this over `search_knowledge`, `list_knowledge_documents`, or `get_knowledge_document`, so the selection condition is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: results are ranked best-first and each match carries the matched passages as excerpts, which tells the agent what to expect from a call. It omits any auth, rate-limit, or freshness/indexing caveats.

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 purpose, followed by the return shape and the handoff to get_knowledge_document. 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?

There is no output schema, so the description correctly carries the return contract (id, sourceId, kind, title, link, excerpt, score) plus ranking order, and it names the follow-up tool for reading a full document. Nothing an agent needs to invoke or interpret results is missing.

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