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

Annotations declare readOnlyHint=true/openWorldHint=false, and the description is consistent while adding substantial context the annotations cannot convey: no side effects ('nothing is stored or sent'), an admin-key requirement with a 403 failure mode for agent keys, and a 404 when the recipient does not exist.

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?

Well front-loaded: the dry-run purpose and the send_event relationship come first, followed by auth behavior and the return shape. The return-field enumeration is dense but earns its place since there is no 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?

With no output schema, the description compensates by naming the returned `rules` fields (rule, matched, status, reason, digest_id) and cross-referencing get_event's `outcome`. Auth, failure modes, and side-effect behavior are all covered.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by clarifying that recipient must be an existing id (unlike send_event, no creation) and that data mirrors send_event input, plus the 404 behavior tied to that 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?

States a precise verb and scope: dry-run an event for a person, showing which rules fire and why others do not. It is immediately distinguishable from send_event (which actually sends) and get_event (which reads a stored event).

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 use it before send_event to verify a rule reaches the person, notes nothing is stored or sent, and gives a hard exclusion: agent keys get 403 and should read get_event instead. Both the when-to-use and the when-not-to-use with an alternative 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 only declare readOnlyHint and openWorldHint; the description adds the required messages:read scope, 404 semantics for missing or cross-agent ids, the expires_at-to-expired behavior, and the polling contract. It also enumerates every returned field in the absence of an 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?

Front-loaded with purpose and polling rule, then auth scope, then return fields. The full field enumeration is long but justified because there is no output schema; only the exhaustive list 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?

With no output schema, the description supplies the return shape, status enumeration, auth requirement, polling behavior, and failure mode. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and the schema already explains approval_id, so the baseline is 3. The description adds value by tying the id to request_approval's return and by documenting the 404 failure mode for nonexistent or foreign-agent ids.

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 (fetch) and resource (approval request by id) and ties it to the sibling that creates it, request_approval. An agent can distinguish it from request_approval, get_message, and the other siblings without opening a schema.

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

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

Explicitly instructs to call it after request_approval, to re-call with a pause while status is pending, and to treat anything but approved as no. That is concrete when-to-use and how-to-poll guidance, not 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 cover the read-only/open-world profile, but the description adds the required `messages:read` scope, the 404 failure conditions (nonexistent id or agent key from another sender), and the pending/processed/failed lifecycle of `status`. That is substantial behavioral context 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?

Front-loaded with purpose and usage before the return-shape detail, and every clause carries information. It is dense and long, but with no output schema the field documentation earns its space, so only minor trimming is possible.

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 fully documents the returned fields and enumerates the matched/reason/status semantics, including suppressed-message cases and the empty-list meaning. Nothing an agent needs to interpret the result 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 description largely restates the schema's own guidance (send_event id or a message's event_id). It adds no format or syntax detail beyond it, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Fetch a reported event by id') plus the exact scope of the response (per-rule fired/outcome detail). This distinguishes it clearly from get_message, send_event, and explain without needing to open the schema.

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

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

Explicitly says 'Use it after send_event to learn what was sent and why or why not', routes delivery questions to get_message, and names explain for dry runs. When-to-use and alternatives are both fully specified.

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 cover the safety profile (readOnlyHint, openWorldHint=false). The description adds substantial behavior: the required auth scope, the 404 failure condition including the cross-sender check for agent keys, and the meaning of status/status_reason values such as `frequency_cap: 3 per 1 day`. This goes well beyond the structured fields.

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

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

Well front-loaded: purpose, then usage/routing, then behavioral details. The return-field enumeration is long, but since no output schema exists it is largely load-bearing rather than 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?

With no output schema and a single trivial parameter, the description compensates fully by enumerating returned fields, status values, status_reason semantics, and failure modes. Nothing needed to call or interpret the tool 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 parameter is already documented as a UUID. The description still adds real value by explaining the three sources of the id (send_message, list_messages, get_event outcome), which is more than the schema alone conveys.

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 ('Fetch one message by id') plus the exact purpose (learning whether/how a person was notified). It is clearly distinguishable from siblings list_messages, get_event, and send_message without opening any schema.

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

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

Explicitly says when to use it ('after send_message, or with a message_id from get_event') and names the alternative for the no-id case ('use list_messages when you have no id'). Prerequisites (the `messages:read` scope) are also 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 only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing the auth scope requirement, a visibility restriction ('agent keys see only their own messages'), pagination behavior via next_cursor, and a concrete failure mode (404 for unknown recipient). These are exactly the behavioral traits 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?

Two short paragraphs, front-loaded with purpose and sibling routing, then return shape and error behavior. Every clause carries information; nothing restates the schema verbatim.

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 carries the return contract itself: it names `items`, says each item matches get_message's fields, and explains `next_cursor` semantics. Combined with the error and permission notes, an agent has everything needed 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining what the status values signify in workflow terms and by documenting the 404 that occurs when `recipient` is not a known external id — semantics the enum list alone does not convey.

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

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

The description opens with a specific verb+resource plus ordering and scope: 'List recent messages, newest first, optionally for one person or status.' It then explicitly distinguishes itself from the sibling get_message ('Use get_message when you have an id'), so an agent can route without opening either schema.

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

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

It names the alternative (get_message) and the condition that selects it (having an id), and explains what the optional status filter is for by mapping statuses to user intent ('what was suppressed', 'what waits for approval'). It also states the required `messages:read` scope, which is a real usage precondition.

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

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

Annotations only declare readOnlyHint and openWorldHint. The description adds real behavioral context beyond them: the admin-key authorization requirement with the concrete 403 failure mode for agent keys, plus the unordered result cap of 200 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?

Three short sentences, each load-bearing: purpose+consumer, the alternative tool, the auth constraint, and the result shape. Purpose is front-loaded and nothing is redundant with the schema.

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

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

With no input parameters and no output schema, the description carries the burden and does so: it documents the authorization requirement and the returned fields (key, description, locales) and the cap of 200, which is exactly what an agent needs.

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; baseline for a no-param tool is 4. It still usefully notes that the call needs an admin key rather than 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?

States a specific verb and resource (list the templates) and ties it to the consumer (send_message) so the agent knows these keys feed message sending. It is clearly distinguishable from sibling preview_template, which is called out separately.

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 why to call it (to find a template key), names the alternative for viewing content (preview_template), and states a hard prerequisite (admin key; agent keys get 403). When-to-use and when-not are both covered.

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

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

Beyond the readOnlyHint annotation, it discloses the key behavioral traits: no message is sent, an admin key is required, and it fails with 404 for unknown templates and 422 when rendering fails. This is exactly the out-of-band context annotations cannot carry.

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

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

Front-loaded with the core action, then routing guidance, then return and error behavior. Three sentences, each carrying distinct, non-redundant 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 usefully documents the return shape (locale and variants with title/body/url per channel) as well as error codes and auth requirements, leaving nothing important for correct invocation 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 parameters are already documented; however the description adds meaning about `data` (sample variables whose needed keys come from list_templates) and `locale` fallback behavior, going slightly beyond the schema text.

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

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

States a precise verb+resource (render a template with sample data) and clarifies the non-sending nature that separates it from send_message. It also names list_templates as the source of keys, so an agent can place it among siblings without reading schemas.

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

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

Explicitly says to use it to check which `data` a template needs before send_message, naming the alternative and the ordering condition. It also states the auth consequence (admin key required, agent keys get 403), which is decisive for tool selection.

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 are minimal (write, open-world, non-destructive), and the description carries the real burden: messages:write scope, a cue.approval_requested event per reviewer, a one-time review link, humans-only decision, 403 for unconfigured reviewers, and a 429 limit of ~10 open requests. This is exactly the behavioral context annotations cannot convey.

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

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

Purpose and the sibling exclusion are front-loaded, and the dense paragraph is largely information-bearing rather than filler. It is longer than strictly necessary (the full field enumeration of the return could be trimmed), so it falls just short of ideal.

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 spelling out the returned fields (id, status, title, body, reviewers, importance, metadata, expires_at, created_at) and the required poll step. Auth scope, error codes, and limits are all covered, so nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: agent keys may name only their configured reviewers (403 otherwise) and the reviewer pool is 1-10 external ids with first-decision-wins. Those constraints meaningfully sharpen how reviewers should be supplied.

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 (ask to approve/reject) and resource (an action about to be taken outside Cue), with concrete examples (deleting data, spending money, contacting many people). It also explicitly distinguishes itself from the informing siblings by naming send_event and send_message.

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

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

Gives an explicit exclusion ('Not for informing anyone: use send_event or send_message') plus the follow-up workflow ('poll get_approval with the id and act only on approved'). When-to-use, when-not-to-use, and the alternative tools are all 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 only declare the coarse profile (not read-only, open-world, non-destructive); the description goes far beyond with asynchronous processing, the receipt-only result shape (`status: pending`, `duplicate`), idempotency semantics, the suppressed/no_reachable_channel edge case, per-person budget and importance-ceiling limits, approval waits, and explicit 403/422 failure modes.

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 purpose and the send_message routing rule before behavior, and every sentence carries real information. It is dense and slightly long, but the density is justified by the async/idempotency/error complexity rather than padding.

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

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

For a fire-and-forget event tool with no output schema, the description supplies exactly what is missing: the return fields, why they are only a receipt, how to inspect per-rule outcomes via get_event, and the failure codes. Nothing an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters (event name grammar, recipient id semantics, data size limit, idempotency key derivation). The description reinforces the recipient/idempotency behavior but adds no syntax beyond what the schema provides; 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 ('Report that something happened to a person') plus a concrete example event name, and explicitly positions it against the sibling send_message. An agent can distinguish it from send_message and get_event without opening any schema.

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

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

Gives an explicit routing rule: 'Prefer it to send_message whenever a rule can cover the case', and names the scope required (`events:write`). It also tells the agent how to follow up (call get_event with the returned id), which is the correct next step versus alternatives.

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 cover safety flags. The description adds all the behavior an agent needs: policy still applies (preferences, caps, quiet hours, unsubscribes), agent budget/importance ceiling/approval, return shape with the same fields as get_message, the three status values with guidance to read status_reason and not resend pending_approval, idempotency behavior, and specific failure codes (404/403/422).

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 dense, front-loaded paragraphs: purpose/alternative routing first, then behavior, then return values and errors. Every sentence earns its place, though a touch long.

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 usage, policy interactions, return status semantics, idempotency, and error codes. An agent has everything needed to call it 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 coverage is 100%, so the baseline is 3, but the description reinforces key semantics: channels are in fallback order, idempotency_key returns the original message on repeat. It stops short of adding syntax not already in the schema, so it lands one above baseline.

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

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

States a specific verb and resource ('Send one template directly to one person'), defines scope ('without rules'), and explicitly names the sibling it is not (send_event). An agent can distinguish this from send_event 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?

Explicit when-to-use ('an explicit one-off message... when you know the template key') and names the alternative plus the condition that selects it ('otherwise prefer send_event'). Nothing is left to inference.

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