Approval Link — Quotes and Proofs

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is partly covered. The description adds real value by clarifying that the prior sent version 'stays intact', i.e. this is additive rather than overwriting. It is silent on the notable behavioral risk implied by expectedRowVersion (optimistic concurrency / conflict on stale version) and on what 'unsent' means operationally.

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 filler, and the core outcome (new unsent version) is front-loaded ahead of the side-effect reassurance. Nothing could be cut without losing meaning.

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

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

For a tool with a large nested input schema, 0% parameter coverage, no output schema and a concurrency-token requirement, the description is far too thin. An agent cannot know how to populate content, how to obtain expectedRowVersion, or what happens on a version conflict.

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

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

Schema description coverage is 0% and there are 4 required parameters, including a deeply nested content object, so the description carries the full burden and fails. It explains nothing about expectedRowVersion (concurrency token), deadlineAt (deadline semantics), id, or the structure of content. Only 'version' loosely maps to a parameter.

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?

Clear verb+resource: 'Save a new unsent version' states exactly what is created and its state (unsent). It also distinguishes itself from the send path via 'after a customer requests changes', though it never names a sibling tool explicitly. Adequate for a tool with no direct lookalike among the listed 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?

The phrase 'after a customer requests changes' gives an implied trigger condition, which is more than most tools offer. However there is no explicit when-to-use vs when-not guidance, and no pointer to alternatives such as send_approval_request for actually dispatching the revision.

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 openWorldHint=true, so the external side effect is partly covered. The description adds that a customer email is sent, but omits the stage mutation itself, the optimistic-concurrency requirement (expectedRowVersion/expectedStage must match current state or the call presumably fails), and any irreversibility or failure 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?

A single short sentence with no filler, front-loaded. It is efficient, though efficiency here reflects under-specification rather than disciplined brevity.

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, open-world, five-required-parameter mutation with no output schema and no parameter documentation, the description omits the state transition, the concurrency guard semantics, and the email's relationship to the mutation. An agent has almost nothing beyond raw enums to call this 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?

Five required parameters with 0% schema description coverage, and the description mentions none of them. It gives no meaning for stage vs. expectedStage, no explanation of the row-version guard, and no note on the 6000-character note field.

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

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

The name and schema say this tool transitions a record's stage (IN_PROGRESS/READY → READY/COMPLETED), but the description only mentions emailing the customer a progress update. It describes an apparent side effect rather than the core mutation, so an agent cannot reliably infer what the tool actually does from the text.

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?

"after approval" is a weak timing hint, but it does not say which approval artifact is needed (get_approval? wait_for_decision?) nor distinguish this from siblings like send_approval_request or create_approval_request, which also involve customer email. No when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the agent knows this is an irreversible external write. The description usefully adds that the mechanism is an emailed link whose response is later recorded, but it omits that the response arrives asynchronously (requiring get_decision/wait_for_decision) and says nothing about expiry or idempotency behavior.

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

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

Two tight sentences with the core action front-loaded and the person/personId constraint appended. Nothing is padded, though the brevity is part of why the definition under-specifies.

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 8-parameter, nested-object, asynchronous external-side-effect tool with no output schema, the description is far too thin. It gives no account of the request lifecycle, the conditional choices field, or how the recorded response is retrieved.

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

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

Schema description coverage is 0% across 8 parameters, so the description carries the full burden and fails to. Only person/personId are mentioned, and the description never explains kind vs choices coupling, the purpose of expiresAt, or the idempotencyKey, leaving five required parameters undocumented in prose.

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

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

States a specific verb and resource: emails a person a decision link and records the response. That is distinguishable in substance from siblings like send_approval_request or create_approval_request, but the description never names those siblings or explains the boundary, so the agent must infer which tool routes to a person versus an approval flow.

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?

'Provide one person or personId' is a parameter constraint, not usage guidance. There is no statement of when to use this versus send_approval_request, create_approval_request, or wait_for_decision, and no prerequisites or exclusions are given.

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 write/destructive nature is covered. The description adds that a cancellation reason is persisted as part of the operation, which is genuinely new context, but it omits key behavioral facts such as whether already-decided approvals can be cancelled and whether cancellation is reversible.

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 tight sentence with no filler and the action front-loaded. It is efficient, though the brevity comes at the cost of missing detail rather than trimming redundancy.

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

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

For a destructive mutation with no output schema, no schema descriptions, and three required parameters including an unexplained optimistic-concurrency token, the description leaves substantial gaps. It should at minimum explain the state precondition and the meaning of expectedRowVersion.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it only vaguely gestures at 'why' (reason). It says nothing about the required id or the expectedRowVersion concurrency token, whose purpose an agent cannot infer from the schema alone.

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

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

Names a specific verb and resource (cancel an approval request) and adds the side effect of recording a reason. The qualifier 'direct' is unexplained and there is no explicit differentiation from siblings like get_approval or list_approvals, but the action itself 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?

No statement of when this tool should be used, what state the approval must be in (pending vs already decided), or which sibling to reach for instead. The agent must infer everything about applicability 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?

Annotations already declare a non-destructive write in a closed world (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds the key side-effect fact that no email is dispatched, which annotations do not convey. It omits permissions, idempotency behavior of creationKey, and what expiryPolicy does.

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

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

Two tight sentences with zero filler, and the primary action is front-loaded ahead of the side-effect caveat. 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 an 8-parameter tool with 6 required fields, nested objects, two enums, and no output schema, the description is far too thin. It should at minimum explain the idempotency role of creationKey and the meaning of expiryPolicy, which no other structured field documents.

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

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

Schema description coverage is 0% across 8 parameters, so the description must carry the load, but it barely does. 'Quote or proof' loosely maps to the type enum, yet creationKey (idempotency), deadlineAt, expiryPolicy, recipient, message, and the nested content structure are entirely unexplained.

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 ('Save a customer quote or proof as a draft'), and 'does not send an email' implicitly distinguishes it from the sibling send_approval_request. It stops short of naming that sibling, but the core action 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?

'This does not send an email' implies the tool is for drafting rather than dispatching, which gestures at when to use it versus send_approval_request. However, it never explicitly states the alternative or the follow-up step, leaving the agent to infer the 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 declare readOnlyHint=false, yet the description frames the operation as pure retrieval ('Return the PDF record'), which would lead an agent to treat it as a safe read with no side effects. This is the same class of mismatch as a write tool advertised as read-only, so it is flagged as an annotation contradiction; the description also says nothing about permissions, rate limits, or whether an export artifact is created or logged.

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 — the verb, resource, scope and output format all arrive immediately. Its brevity is legitimate rather than padding, though the same compression is what leaves the parameters and usage conditions unexplained.

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 tool with zero schema description coverage, no output schema, and a misleading read-only framing, the description covers only the return medium ('embedded document') and leaves the identifier semantics, preconditions, and side-effect profile 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 0% for two parameters, and the description does not identify either one: it never says what 'id' refers to, that 'decisionId' exists or is optional, or which identifier to supply for a given approval. It gestures at identifying an approval but provides no compensating semantics for the undocumented inputs.

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 (Return/Export), a specific resource (the PDF record) and its scope (a completed customer approval), plus the delivery format (embedded document). An agent can tell it apart from plain data getters like get_approval or get_decision, though it never explicitly contrasts itself with those 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?

The phrase 'a completed customer approval' implicitly restricts this to finished approvals and hints at a precondition, but there is no explicit when-to-use guidance, no statement of when to prefer it over get_approval/get_decision, and no note about whether incomplete or pending approvals are accepted.

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

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

Annotations already establish read-only, non-destructive, closed-world behavior. The description adds useful context about response content—current version, decisions, and delivery states—but does not cover error behavior, authorization needs, or missing-id handling.

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 tight sentence with no wasted words, and the core action is front-loaded. It is appropriately sized for a simple by-id read tool.

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 simple, and annotations cover its safety profile, but with no output schema the description should more fully explain return values or not-found behavior. It lists returned content at a high level but remains thin on parameter semantics and error conditions.

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

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

There is only one parameter, id, with 0% schema description coverage. The description does not mention the id parameter at all, so it fails to compensate for the missing schema description, even though the schema provides UUID type and pattern constraints.

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 approval request,' and enumerates what is returned (current version, decisions, delivery states). It clearly implies retrieval of a single approval by id, distinguishing it from list tools, though it does not explicitly name a sibling alternative.

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 'Read one approval request,' suggesting this tool is for fetching a single approval by id. However, it gives no explicit when-to-use guidance, prerequisites, or comparison to alternatives such as get_decision or list_approvals.

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 useful context by indicating the returned content ('latest answer or deadline status'), which matters since no output schema exists, but it says nothing about auth, error cases, or what 'latest' means operationally.

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 short sentence with no filler, front-loading the operation and its scope. Every word 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 one-parameter read tool with annotations already carrying safety semantics, the description covers the essentials and gestures at the return payload without an output schema. It falls short only on identifying what the 'id' refers to and what happens when no decision is found.

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

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

Schema description coverage is 0% for the single required 'id' parameter, so the description must compensate. It partially does so by implying the id identifies an internal decision, but it never states the expected identifier form or whether it is a decision id, request id, or approval id.

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

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

States a specific verb ('Read') and resource ('one internal decision') with a scoped return ('latest answer or deadline status'). It is distinguishable from list_internal_decisions and wait_for_decision, though it never names those siblings explicitly.

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

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

Usage is only implied: the singular 'one internal decision' signals a single-record lookup rather than a listing or a blocking wait. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative sibling.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that it pages through results and returns recorded statuses, which is useful, but does not detail pagination mechanics or return format.

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 zero waste; it states the action and scope immediately.

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 list tool with four parameters and no output schema, the description is too sparse: it omits how to paginate (beforeAt/beforeId), the limit, and the full set of status filters, leaving the agent to infer from 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 0%, so the description must compensate. It only alludes to the status filter ('recorded statuses') and vaguely to pagination ('Page through'), leaving limit, beforeAt, and beforeId completely unexplained.

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 ('Page through') and resource ('approval requests and their recorded statuses'), clearly indicating a list operation. It does not explicitly differentiate from sibling list tools like list_internal_decisions, so not 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?

Implies usage for browsing approvals with statuses, but gives no explicit when-to-use versus get_approval or other list tools, nor any 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 readOnly, non-destructive, and closed-world, so the safety profile is covered. The description adds real context beyond that: pagination is cursor-based ('page through') and the status field reflects the answer state rather than the notification state. It omits ordering, defaults, and result shape.

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 the scope front-loaded and no filler; the second sentence efficiently packs the filtering behavior plus a semantic caveat. The caveat clause is slightly cryptic in isolation but earns its place by preventing a status/notification mix-up.

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 4-parameter, no-required-arg, no-output-schema listing tool, the description covers scope, filtering, and pagination at a high level but leaves cursor semantics, default limit, and sort order unstated. Adequate to invoke, not enough to invoke confidently without inspecting 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 0%, so the description must carry the load. 'Page through' communicates that beforeAt/beforeId are pagination cursors and 'filter by current status' disambiguates the status enum (answer state, not notification state), but the limit parameter and default/ordering behavior remain unexplained.

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: paging through this workspace's internal ask_person decisions. Naming ask_person anchors the domain, so an agent can separate it from single-item tools like get_decision or unrelated list_approvals. It stops short of explicitly naming which sibling to use for a different result shape.

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?

'Filter by current status' implies the intended usage, and the note that notification state is separate from the answer pre-empts a likely confusion about the status filter. However, it never states when to pick this over list_approvals or get_decision, and gives no prerequisites or 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 this is a safe read operation (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds useful domain context by scoping results to people who can answer a decision in the workspace, but it does not disclose pagination behavior, ordering, or response shape. With annotations carrying the safety profile, this is adequate but not rich.

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 with no wasted words. It states the tool's purpose efficiently.

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 paginated list tool with three undocumented parameters and no output schema, the description is too thin. It does not explain how to use limit/afterId/afterName or what the result contains, so an agent cannot call it correctly without guessing.

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

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

The schema has 0% description coverage for all three parameters (limit, afterId, afterName), and the description does not mention any parameter or explain pagination. It fails to compensate for the schema gap, leaving the agent with no semantic guidance for cursor-based listing.

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 people') and adds a meaningful scope qualifier ('who can answer a decision in this workspace'). It doesn't explicitly name a sibling alternative, but the qualifier helps distinguish it from a generic people directory.

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

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

The description implies the tool is used when looking for people who can answer a decision, but it gives no explicit when-to-use guidance, no prerequisites, and no alternatives such as ask_person. The agent is left to infer the context.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the external-send and irreversibility profile is partly covered. The description adds genuinely useful context: the draft must be in a confirmed state and recipient/version must be revalidated, implying staleness failure modes. It stops short of saying what happens on a version mismatch or that the send cannot be undone.

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

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

Two short sentences, zero filler, with the action front-loaded and the precondition following. 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 destructive, open-world send with three required params and no output schema, the description covers the precondition but omits the consequence of a stale version, whether retries are safe, and what a successful send returns. Annotations carry the safety profile, so this is adequate but thin.

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

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

Schema description coverage is 0%, so the description carries the burden. It gives meaning to recipientEmail (must be the current recipient) and expectedRowVersion (must be rechecked), and implies id via "confirmed draft," but supplies no format or constraint detail beyond the schema's own validation patterns.

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 target: "Email a confirmed draft to its customer," which clearly separates it from create_approval_request (creating) and cancel_approval (cancelling). It never names a sibling, so differentiation is implied from the verb rather than made 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?

"Recheck the current recipient and version before sending" is a concrete precondition (implying an optimistic-concurrency flow), but the description gives no when-to-use versus alternatives guidance and no when-not-to-use case among the many sibling approval 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 declare readOnlyHint=true and non-destructive, so safety is covered. The description nonetheless adds valuable behavior the annotations cannot express: it blocks for up to 20 seconds and, critically, that a timeout means 'pending', not approval. It omits what happens to the caller after a timeout or whether the wait is cancellable.

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

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

Two short sentences with no filler; the blocking duration is front-loaded and the timeout caveat is a compact, high-value second sentence.

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

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

With no output schema and no parameter descriptions, the description should carry more of the return semantics. 'A pending timeout is not approval' is a useful start, but it does not say what a successful wait yields, nor what an agent should do when the wait expires — leaving a real gap for a blocking, state-dependent tool.

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

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

Schema description coverage is 0% for two parameters, so the description must compensate. It only indirectly implies the 20-second ceiling that constrains waitMs (schema default 15000, max 20000) and says nothing at all about what the required 'id' identifies, leaving the key parameter undocumented.

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

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

The verb 'wait' plus the resource ('internal answer or customer approval response') is specific and says what the tool returns control over. It implicitly distinguishes itself from the sibling get_decision by being a blocking wait rather than a one-shot read, though it never names that alternative.

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 hints at the context (waiting for a decision to arrive) but gives no explicit when-to-use rule and no comparison against get_decision, get_approval, or the list_* polling siblings. An agent has to infer whether to block here or poll elsewhere.

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