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

With no annotations, the description carries the full behavioral burden. It usefully discloses several things the tool does NOT cancel, which is meaningful context, but it does not say whether cancellation is idempotent, what permissions are needed, what happens if the appointment is missing, or what side effects occur.

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 two sentences and front-loads the core action before the exclusions. It is efficient, though the phrase 'your named appointment' is slightly awkward against the tool name's 'wake' terminology.

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

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

An output schema exists, so return values need not be explained. Still, for a mutation tool with no annotations and 0% parameter description coverage, the description leaves important gaps around the required reason field, permissions, and cancellation side effects.

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 explains the optional 'name' parameter and its default, but the required 'reason' parameter is never described at all, leaving a required input undocumented in both schema and description.

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, 'Cancel', applied to 'your named appointment', with a default when the name is omitted. It is distinguishable in practice from the sibling schedule_next_wake, though it never names that sibling and uses 'appointment' instead of the tool name's 'wake'.

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 supplies a when-not list ('does not recall an in-flight or accepted batch, interrupt a turn, or clear an uncertainty hold') and mentions the default name behavior. However, it does not explicitly route the agent to schedule_next_wake, iam_timer_cancel, or another sibling for the excluded cases.

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

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

With no annotations, the description carries the full burden and does the most important thing: it explicitly guarantees no side effects ("No renewal or delivery is triggered"), which is exactly the safety signal an agent needs. It also flags that next_wake is a compatibility alias, a behavioral quirk of the response rather than the call itself.

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 dense sentences with the primary scope front-loaded and the no-side-effect caveat placed at the end where it is most needed. The middle sentence about the next_wake alias is slightly cryptic in isolation but earns its place as a disambiguation note.

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-parameter read tool with a published output schema, the description supplies the two things the schema cannot: what the state comprises and that reading it mutates nothing. The remaining gap is that terms like "global wake eligibility" and "heartbeat-only hold" are not defined for an agent unfamiliar with the heartbeat subsystem.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The one aliasing note about next_wake relates to output shape, which the output schema already covers.

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 ("Inspect") and enumerates the resources it returns: named schedules, global wake eligibility, heartbeat-only hold, delivery receipt. This is clearly distinct from the mutating siblings schedule_next_wake and cancel_next_wake, though the phrase "heartbeat-only hold" is internal jargon an agent may not decode.

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: "Inspect" plus "No renewal or delivery is triggered" tells the agent this is the safe read path, but neither sibling schedule_next_wake nor cancel_next_wake is named, and no condition for choosing this over them is 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?

No annotations are provided, so the description carries the full burden. It does not disclose whether archiving removes the message from the inbox, whether the action is reversible, what permissions are required, or how the mailbox default behaves.

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 wasted words. The core action is stated immediately, though brevity comes at the cost of detail covered under other dimensions.

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 annotations and 0% parameter description coverage, the description is too thin. The output schema covers return values, but the side effects of archiving and the mailbox parameter's meaning are 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 0%, so the description must compensate. 'One ... message' hints that message_id identifies a single message, but the mailbox parameter and its null default are never explained, leaving half the parameters undocumented in both schema and description.

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 ('Archive ... inbox message'), so the agent knows exactly what operation it performs. It does not name or differentiate itself from siblings such as iam_inbox or iam_read, leaving that inference to the 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?

The phrase 'fully handled' implies a precondition for use, but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives (e.g., delete vs. move vs. leave in inbox). Usage is only 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?

With no annotations, the description carries the full burden and does disclose an important side effect: joining another channel deactivates the prior one. It says nothing about permissions, what happens if the channel does not exist, or whether the join persists across sessions, which are meaningful gaps for a state-changing tool.

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

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

Two sentences, no filler, with the single-active-channel constraint front-loaded before the DM caveat. 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?

An output schema exists, so return values need not be described, and the exclusivity behavior is covered. Still, for a four-parameter state-changing tool with zero schema documentation, omitting mailbox semantics and failure behavior leaves the definition only minimally 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?

Schema description coverage is 0%, so the description must explain all four parameters. It partially explains channel_type and with_agent via the DM-creation rule but never defines what other channel_type values are valid, and the required `channel` format and the `mailbox` parameter are entirely 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 description gives a specific verb and resource (join a channel) and immediately scopes it: only one channel is active at a time. It is clearly distinguishable from iam_chat_leave, iam_chat_post, and iam_chat_tail, 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 supplies a conditional rule for the DM case ('use channel_type=private and with_agent only to create a new DM'), which is genuinely useful. But it never says when to join versus checking iam_chat_subscriptions or iam_list_channels first, so the broader selection guidance is only 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?

With no annotations, the description carries the full burden. It discloses the core mutation and one side effect (stopping supervisor notifications), but omits permissions, idempotency, and behavior when no active chat 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?

It is a single front-loaded sentence with no redundant or filler content. Every phrase contributes scope or effect.

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 mutation with an output schema, the core action and side effect are stated. However, the missing parameter semantics and operational conditions leave it only minimally 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 0% and the sole parameter 'mailbox' is undocumented. The description says 'this mailbox's' but does not explain the optional null default or how to specify a mailbox.

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: leaving a live chat channel, scoped to this mailbox, plus stopping supervisor notifications. This clearly distinguishes it from the opposite sibling iam_chat_join and other chat 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 implies usage by saying 'Leave this mailbox's active live chat channel,' but gives no explicit when-to-use conditions, prerequisites, or alternatives such as iam_chat_join or iam_chat_subscriptions.

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?

No annotations are provided, so the description carries the full behavioral burden. It mentions the active-channel prerequisite but omits side effects, permissions, error behavior when no channel is active, and message visibility.

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

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

The definition is two sentences, front-loaded with the core action, and contains no filler. The prerequisite and channel constraint are placed 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 mutation tool with no annotations and 0% schema descriptions, this is too thin. The output schema handles return values, but the description still leaves key parameter meanings and mutation behavior unexplained.

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 explain the three parameters. It gives some context for the mailbox concept and implies message content via 'Post', but never explains the date parameter and does not clarify mailbox semantics.

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, 'Post', and a specific resource, 'this mailbox's active chat channel'. It does not name a sibling tool, but the active-channel constraint makes it distinguishable from join/tail 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 gives a clear prerequisite, 'Join a channel first', and clarifies that a channel cannot be supplied here. However, it does not explicitly name iam_chat_join as the alternative or explain when to use this versus other chat 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?

No annotations are supplied, so the description carries the full burden for a mutation-style operation. It does not say whether marking as seen affects other participants' view, whether it is idempotent, whether it advances a persistent cursor, or what it returns; only the bare action is given.

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; it is efficient, though brevity here comes at the cost of the missing detail noted elsewhere rather than through disciplined editing.

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

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

For a four-parameter mutation with no annotations and zero schema coverage, the description does not provide enough to call it correctly. An output schema exists so return values need not be explained, but channel/mailbox/date/lines semantics and the side effects of marking as seen remain 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% across four parameters, and the description only vaguely implies a recency window ('recent'). It never mentions channel, mailbox, date, or lines, so the agent gets essentially no guidance on scoping the mark-as-seen range from the description.

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 ... as seen') plus the scope ('this project'), which is more than a restatement of the name. However, 'recent' is undefined, and nothing distinguishes it from siblings like iam_chat_tail or iam_chat_subscriptions, which also deal with recent chat content.

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 statement of when to call this, when not to, or which sibling to use instead. An agent must infer that this is the read-receipt counterpart to iam_chat_tail and cannot tell whether calling iam_chat_tail already does this.

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

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

With no annotations provided, the description carries the full behavioral burden. 'Return' and 'active ... if any' imply a read-only lookup and possible absence of a subscription, but it does not explicitly state side-effect behavior, authorization needs, or how the mailbox default is resolved; the output schema covers return 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?

The description is a single front-loaded sentence with no wasted wording. It communicates the core operation 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 simple one-parameter getter with an output schema, the purpose and conditional result are present. However, the optional mailbox default/null semantics and some behavioral context are missing, leaving clear gaps 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 0%, so the description should compensate for the single optional 'mailbox' parameter. It only says 'this mailbox's,' which hints at the parameter but does not explain accepted identifier format or what a null/default value means.

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 uses a specific verb and resource: 'Return this mailbox's active live chat subscription.' It is reasonably distinguishable from chat join/leave/post siblings, but it does not explicitly contrast itself with related chat tools or name an 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?

It states what the tool returns but gives no when-to-use or when-not-to-use guidance, and it does not reference alternatives such as iam_chat_join, iam_chat_leave, or iam_list_channels. The use case is implied rather than guided.

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

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

With no annotations, the description carries the full behavioral burden. It discloses one important trait—private-channel membership enforcement—but omits access failure behavior, ordering, pagination, and other read semantics.

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 is structurally efficient, though its brevity contributes to gaps covered by other dimensions.

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

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

An output schema exists, so return values need not be described. However, for a four-parameter tool with no annotations and no schema descriptions, the definition is incomplete: it lacks parameter guidance, usage routing, and detailed private-channel access 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?

The schema has four parameters with 0% description coverage, and the description explains none of them. It does not clarify what 'date', 'lines', 'channel', or 'mailbox' mean or how they interact.

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: read recent chat messages. It is clearly a chat-history retrieval tool, though it does not explicitly contrast itself with siblings such as iam_chat_seen or iam_chat_subscriptions.

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 'Read recent chat messages' implies the basic use case, but there is no explicit guidance on when to choose this over sibling chat tools. No exclusions or alternatives are mentioned.

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

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

With no annotations, the description carries the full burden and excels: it discloses rate limits (20/hour), character limit (4000), deduplication via notice_id, file size/format constraints, privacy warnings, and clarifying that it grants no authority and does not wake agents. This is comprehensive behavioral context beyond the schema.

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

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

The description is dense but well-structured, front-loading the purpose and then systematically covering constraints and cautions. Every sentence adds value, with no wasted words.

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

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

Given the complexity of file attachments and rate limits, the description provides most critical context. An output schema exists, so return values needn't be explained. However, the unexplained mailbox parameter and slight ambiguity around 'body' leave minor gaps.

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 0%, so the description must explain all parameters. It covers notice_id (deduplication), image_paths and file_paths (formats, size limits), but the 'body' and 'mailbox' parameters are not explicitly described—'Include a caption' is ambiguous and could refer to body, while mailbox is entirely unexplained. Partial compensation for the coverage gap.

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 uses a specific verb ('send') and resource ('Messenger message') with clear scope ('unsolicited', 'from YOUR mailbox', 'No prior request needed'). This distinguishes it from sibling tools like iam_desktop_reply, which implies a response to a prior 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?

The description clarifies that no prior request is needed, indicating this is for proactive outreach. However, it does not explicitly name alternatives or state when to use this tool versus iam_desktop_reply or other notification methods, leaving some 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?

With no annotations, the description carries the burden well: it discloses that avatar_path intentionally publishes a local file with a 1 MB cap and accepted formats, that empty values clear fields, and that all content is publicly visible. It does not state whether partial updates are merged vs. replaced or whether write permission/ownership is required.

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

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

Dense and front-loaded: the action and field inventory come first, constraints follow. The long parenthetical field lists make it slightly hard to scan, but no sentence is redundant.

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

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

An output schema exists, so return values need no explanation, and the behavioral/field coverage is strong. The gap is the parameter layer: 0% schema description coverage plus an entirely unexplained `mailbox` argument and unstated nesting under `updates` leaves an agent without enough to construct a correct call from the description alone.

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 0%, so the description must compensate, and it does richly for the profile fields (presence enum values, 2000-char limit, #RRGGBB format, clearing semantics, avatar size/type limits). However, it never mentions the `mailbox` parameter nor explains that these field names are keys nested inside the `updates` object, which is a real risk of malformed calls.

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

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

The description states a specific verb pair (inspect/update) applied to a specific resource (buddy profile) and enumerates every writable field, so the scope is unmistakable. It stops short of naming a sibling (e.g., iam_whoami for read-only identity, iam_friend for relationships), so an agent must infer the boundary rather than being told.

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?

"Only intentionally public profile content belongs here" and "Presence and away messages are chosen expression, not runtime availability, wake blocking, or authority" are explicit scope exclusions that prevent real misuse (e.g., using presence to signal wake availability). No positive routing to alternatives is given, so it sits just below 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?

With no annotations present, the description carries the full burden and delivers: immutability ('One immutable reply per request'), idempotency ('identical retries are safe'), and attachment semantics ('copied, not live path links', per-file and per-category size caps, UTF-8 requirement). These are exactly the behavioral facts an agent needs before invoking a mutation.

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

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

The purpose and the ONLY constraint are front-loaded, and each subsequent sentence adds a distinct constraint (attachment limits, copy semantics, safety exclusions, idempotency). It is dense but no sentence is filler; a light break into separate clauses would aid scanning.

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

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

An output schema exists, so return values need not be described, and the mutation's safety profile is well covered despite missing annotations. The only material gap is the role/format of request_id and the optional mailbox, which an agent must infer.

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, and it does for the non-obvious parameters: image_paths and file_paths get formats, counts, and size limits, and body is tied to 'Include a caption' / UTF-8 text. request_id and mailbox receive no explanation, leaving a partial gap.

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: 'Publish an intentional reply ... to a human IAM Desktop request addressed to your mailbox.' This cleanly separates it from the email siblings (iam_reply, iam_send) and from notify-style tools by naming the request/reply model.

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 'ONLY to a human IAM Desktop request' constraint and the 'Never forward unrelated mail, private notes, reasoning, secrets or tool output' exclusion give clear when/when-not guidance. It stops short of naming the alternative sibling (e.g. iam_reply) for non-desktop cases, so it is strong but not fully routing.

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

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

With no annotations, the description carries the full burden and does disclose non-obvious behavior: owner enrollment is required, registration does not confer sending permission, old addresses persist as aliases, and no outbound mail is emitted. These are exactly the facts an agent could not infer. It still omits idempotency (what happens on re-register) and 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-loaded with the three operations before the caveats, and the telegraphic sentence fragments are dense rather than padded. Every clause carries information; the clipped style is slightly at the cost of readability 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, so return values need not be described. But for a three-action, three-parameter tool with zero schema documentation, the missing action-to-parameter mapping leaves a real hole in an otherwise thoughtfully annotated definition.

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, and it largely does not. It names the action values but never explains the 'local' or 'mailbox' parameters, nor which parameters each action consumes — an agent cannot tell whether 'register' takes local, mailbox, or both.

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 three concrete operations (check availability, register address, inspect status) on a specific resource (iam_email), and the stated action values available/register/status let an agent separate this from siblings like iam_send or iam_reply. It stops short of a single crisp one-line purpose statement, but the function 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?

The action list (available/register/status) gives implied routing, and 'Owner enrollment required' is a genuine prerequisite. However, there is no explicit guidance on when to choose this over iam_list_mailboxes or iam_whoami, and no indication of what to do if enrollment is missing.

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

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

With no annotations provided, the description carries the full behavioral burden and does so richly: consent and gate requirements, public visibility of explanations and sent content, untrusted received content, safe read-only inspection after uncertain outcomes, and strict resend semantics. These are exactly the behavioral traits an agent needs beyond the schema.

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

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

The description is long and dense, but it is front-loaded with purpose and every clause appears to carry operational meaning. It could be easier to scan with bullets or line breaks, but there is little obvious fluff for such a complex multi-operation 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 complex, has a generic schema with no parameter descriptions, and lacks annotations. The description compensates by covering operations, required formats, prerequisites, safety constraints, side effects, and resend behavior. Since an output schema exists, it need not explain return values.

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 the schema itself is a generic operation/value pair. The description compensates by enumerating operation-specific fields, accepted value forms (e.g. code OR target, id/ids), attachment upload formats, chunk sizes, and file payload shapes. It adds substantial meaning beyond the bare schema.

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

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

The description opens with a specific verb and resource: 'Intentional external friendship operations for your bound mailbox.' It then enumerates concrete operations, making the tool's scope unmistakable and separating it from siblings by explicitly excluding owner control, wake, steering, and arbitrary RPC.

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 prerequisites such as owner risk consent and active feature gates, lists operational subcommands, and gives exclusions ('No owner control...'). It also tells the agent what to do after uncertain outcomes and how to resend safely. It does not explicitly name iam_friend_policy as an alternative, but the operational boundaries are 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?

With no annotations, the description carries the burden and does substantial work: it warns the tool cannot enable owner permission or accept a friendship, notes external messages are non-owner content, flags that owner risk review is Desktop-only, and states stale choices are invalidated by policy changes. These are meaningful behavioral constraints, though some phrasing is terse.

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

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

Purpose is front-loaded and the constraints follow in order. It is dense but each sentence carries a distinct rule; the ALL-CAPS clauses are slightly noisy but not wasteful.

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

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

For a 3-param, no-annotation tool with an output schema, the description covers safety constraints, write preconditions, and revision semantics well. The main gap is the undocumented mailbox parameter, which keeps it short of 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 0%, so the description must compensate. It meaningfully explains opted_in (only when owner allows) and revision (use the returned revision), but says nothing about the mailbox parameter, leaving one of three params 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 and resource: 'Inspect your external-contact permission.' A reader understands it reads (and optionally sets) the friend/external-contact policy. It doesn't explicitly differentiate from the sibling iam_friend, so it stops short of a 5.

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

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

Gives a clear conditional for the write path: 'Choose opted_in only when your owner has explicitly allowed agent choice, using the returned revision.' This tells the agent when to set versus just inspect. It does not name sibling alternatives like iam_friend, which keeps it below 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?

No annotations exist, so the description carries the full burden. It does disclose the key side-effect fact (messages are not marked read, i.e. non-mutating), but says nothing about permissions, ordering guarantees, pagination, or default behavior — the burden is only partly met.

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 resource, and every clause earns its place — the non-mutating qualifier is the highest-value information and appears 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?

An output schema exists, so return values need not be explained, and the read semantics are covered. However, the three undocumented parameters (limit default 100, optional mailbox, unread_only toggling the core filter) leave genuine gaps an agent must guess at.

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?

Three parameters (limit, mailbox, unread_only) with 0% schema description coverage, so the description must compensate and does not. Only 'newest' loosely hints at ordering relative to limit; mailbox and unread_only are entirely unexplained anywhere.

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 (inbox messages), scoped to 'this project', and it adds a distinguishing trait ('without marking them read') that separates it from iam_read. It does not explicitly name a sibling, so it stops short of 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?

The phrase 'without marking them read' implicitly signals when to prefer this over iam_read, but there is no explicit when-to-use/when-not-to-use statement or named alternative. Usage must be inferred from a single clause.

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?

No annotations are supplied, so the description carries the full behavioral burden. It implies a read but never states that it is non-mutating, whether it requires permissions, whether it returns all public channels plus private ones the caller belongs to, or whether results are paginated/truncated.

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. It is efficient, though its brevity borders on under-specification rather than tightness.

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

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

An output schema exists so return values need not be explained, but with no annotations, an undocumented optional parameter, and no usage routing, the definition leaves the agent guessing about scoping and channel visibility.

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 the sole parameter 'mailbox' is entirely unexplained in both schema and description. The description does not say what mailbox scoping means here (filter channels by owning mailbox? which mailbox is defaulted?) — a real gap the text should have closed.

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 ("List ... chat channel names") and narrows scope to IAM public and private channels. It does not, however, distinguish itself from close siblings such as iam_chat_subscriptions or iam_chat_tail, so an agent must infer the difference.

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 statement of when to call this versus iam_chat_subscriptions (which presumably shows joined channels) or iam_chat_join/iam_chat_leave. The agent gets a one-line purpose and no routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Known' hints at a directory scope, but there is no disclosure of permissions, whether mailboxes can be filtered, pagination, or how the list is ordered. The output schema covers return values, but the operational behavior remains thin.

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 wasted words. It is appropriately terse, though the terseness contributes to the documentation gaps elsewhere.

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 list operation with an output schema, explaining return values is unnecessary, so the omission is acceptable. However, the unexplained optional parameter and lack of any behavioral or usage context leave the definition just barely adequate for reliable 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 0%, and the optional 'mailbox' parameter is completely undocumented in both the schema and the description. It is unclear whether passing 'mailbox' narrows the list to one entry, changes the output shape, or is ignored. The description must compensate for the schema gap and does not.

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 (List) and resource (known IAM mailbox addresses and display names), which is clear enough to distinguish it from message-oriented siblings like iam_inbox or iam_read. It does not explicitly name a sibling or clarify how it differs from iam_whoami, so it stops short of a 5.

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

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

The description gives no when-to-use or when-not-to-use guidance and does not mention any alternative tool. An agent must infer from the name alone that this enumerates mailboxes rather than reading messages or retrieving the current identity.

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?

No annotations are provided, so the description carries the full disclosure burden, and it undersells the tool: it reads as a passive lookup while the hidden mark_read parameter defaults to true, meaning the call mutates message state. Side effects, permission requirements, and error behavior for ambiguous prefixes are all undisclosed.

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 short, front-loaded sentence with no wasted words. It is terse rather than bloated, though the terseness is part of why other dimensions are under-covered.

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

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

An output schema exists, so return values need not be described, but with three parameters at 0% schema coverage and no annotations, the description leaves the agent without the mailbox scoping or the mark_read side-effect. For a tool that silently mutates state by default, this is inadequate.

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 and only partly does: it clarifies that message_id accepts a full id or a unique prefix, which is genuinely useful. The other two parameters, mailbox and mark_read (with its default of true), get no explanation at all.

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 specific verb ('Read') plus resource ('one inbox message') and scope ('one'), so the agent knows it's a single-message fetch rather than a list. It does not explicitly distinguish itself from the sibling list tool iam_inbox, leaving the agent to infer the contrast from '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?

No statement of when to use this instead of iam_inbox (listing) or iam_chat_tail, and no guidance on when the prefix form is appropriate versus a full id. Usage is only implied by the verb.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses only that originator and routing are preserved; it does not state that it sends externally, what permissions are required, whether subject is auto-generated, or how attachments and cc affect delivery.

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 redundant text. It could be more informative, but that is a completeness issue rather than a conciseness problem.

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 9-parameter mutation tool with no annotations and 0% schema description coverage, the definition is far too sparse. Output schema exists, so return values need not be explained, but input semantics and behavioral constraints are 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 0% for 9 parameters and the description mentions no parameter semantics. 'Existing thread' weakly hints at message_id and 'reply' hints at body, but to/cc, mailbox, subject, priority, references, and attachments are entirely 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?

States a specific verb and resource/context ('Send ... reply in an existing thread') plus the routing effect. It does not distinguish this from sibling tools like iam_desktop_reply or iam_send, so it is clear but lacks sibling differentiation.

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 'in an existing thread' implies the use case, but there is no explicit when-to-use, when-not, or comparison to iam_desktop_reply/iam_send. The agent must infer that this is intended for substantive threaded replies rather than other message-sending 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that urgent priority may steer an active Codex turn, which is non-obvious, but it does not explain send side effects, reversibility, recipient behavior, or mailbox semantics.

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 two short sentences with no wasted words, and the core purpose is front-loaded. The second sentence adds non-obvious behavioral information rather than restating the name.

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?

Although an output schema exists, the tool has 8 parameters, 0% schema description coverage, no annotations, and mutation semantics. The description is far too sparse to fully prepare an agent for correct invocation, especially regarding recipients, mailbox, attachments, and threading fields.

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 compensate. It only clarifies the priority field as normal or urgent and says nothing about to, cc, subject, body, mailbox, references, or attachments.

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: "Send a new message." However, it does not distinguish this tool from siblings such as iam_email, iam_reply, or iam_chat_post, leaving the message type ambiguous despite the likely email-like parameters.

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 no guidance on when to use iam_send versus iam_reply, iam_email, or iam_chat_post, and no prerequisites or exclusions are stated. The only usage-related detail is the priority option, which does not help select the 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?

With no annotations, the description carries the full burden and does disclose the required permission grant, which is valuable. However, it says nothing about behavior on missing permission, duplicate membership, idempotency, or partial failure—significant gaps for a mutation tool with zero annotation coverage.

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 action precedes the permission caveat. Appropriately sized for the tool, though the phrasing introduces mild ambiguity rather than resolving it.

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 explained, but with 0% parameter coverage, no annotations, and a mutation action, the description should clarify member vs mailbox and failure/idempotency behavior. As written, an agent has too little 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 0%, so the description must compensate, but it only mentions 'team' and 'mailbox' loosely. It leaves the required 'member' parameter unexplained and creates ambiguity by calling the object a 'mailbox' while 'mailbox' is an optional default-null param and 'member' is required.

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

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

States a specific verb and resource (add a mailbox to a leader's team), and the 'one mailbox' phrasing scopes the operation, implicitly contrasting with the sibling iam_team_remove_member. It's clear enough to pick from siblings, though the object being added ('mailbox' vs the required 'member' param) is slightly muddled.

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

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

Explicitly names the precondition for use ('when team.manage_members was explicitly granted'), which is exactly the gating condition an agent needs. It does not name an explicit alternative or any when-not-to-use case, keeping it 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?

No annotations are provided, so the description carries the full disclosure burden. It usefully surfaces the required permission scope and the non-leader restriction, but says nothing about failure behavior for leader mailboxes, reversibility, or what "this leader" refers to (presumably the caller, but unstated).

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 that front-loads the action and the resource, with zero filler. Nothing could be removed without losing 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?

An output schema exists, so return values need not be described, but for a mutation tool with no annotations and 0% schema coverage the description is too thin. It leaves the identity semantics of `member` vs `mailbox` and the treatment of leader mailboxes unexplained.

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 three parameters, so the description must compensate and largely does not. It hints that one argument is the team ("this leader's team") and another a mailbox, but never distinguishes the `member` parameter from the optional `mailbox` parameter or explains why `mailbox` defaults to null.

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 ("Remove a ... mailbox from this leader's team") and scopes it with "non-leader", which makes it clearly distinct from the inverse sibling iam_team_add_member. It stops short of naming the sibling explicitly, but the operation 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?

The trailing clause "when team.manage_members was granted" gives a permission prerequisite, and "non-leader" implies a when-not condition (leaders cannot be removed this way). However, no alternative tool or fallback is named, and the preconditions are 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?

No annotations are supplied, so the description carries the full burden of behavioral disclosure. It identifies the operation as a cancellation but says nothing about whether it is idempotent, what happens when the timer_id is unknown or already fired, required permissions, or whether the mailbox argument defaults to the caller's own mailbox — significant gaps for a mutation tool with zero annotation coverage.

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 well-formed sentence with the action front-loaded and no filler. It is efficient, though the brevity comes at the cost of the missing context noted elsewhere rather than through deliberate compression.

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

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

An output schema exists, so return-value shape is covered, but for a mutation tool with no annotations and 0% parameter coverage the description leaves too much implicit: failure behavior, idempotency, and the meaning of both parameters are 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%, so neither timer_id nor mailbox is documented anywhere in structured form. The description never mentions parameters explicitly, only hinting via 'this mailbox' that a mailbox scope exists; timer_id — the sole required parameter — is 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?

States a specific verb (Cancel) and resource (timer) plus the scoping condition 'created by or targeted to this mailbox,' which an agent can act on. It does not, however, distinguish this from the very similar sibling iam_timer_clear (or iam_timer_snooze), so a reader must infer the boundary between overlapping timer operations.

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 guidance on when to use this versus iam_timer_clear, iam_timer_list, iam_timer_snooze, or cancel_next_wake, all of which sound adjacent. The description offers no preconditions, no exclusions, and no routing to 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?

With no annotations, the description carries the full burden and does disclose the two things that matter most for a destructive call: it is permanent and cleared timers are not archived, i.e. unrecoverable. It omits permission requirements and error behavior for non-handled timers.

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 destructive nature front-loaded ahead of the archive note. Nothing could be removed without losing 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?

An output schema exists, so return values need not be explained, and irreversibility is covered. But for a destructive two-parameter tool with no annotations and 0% schema coverage, the missing parameter meaning and missing outcome for unhandled timers leave real gaps.

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 the description mentions neither parameter. It does not explain what timer_id refers to or what the optional `mailbox` parameter means (default mailbox vs. multi-mailbox targeting), leaving both undocumented in schema and 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 ("Clear a handled timer") and adds the scoping qualifier "handled," which distinguishes it from a generic cancel. It never names the sibling it competes with (iam_timer_cancel / iam_timer_snooze), so the differentiation is implied 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?

"Handled timer" implicitly encodes the precondition for use, and "permanently" implies this is the terminal action rather than a cancel or snooze. However there is no explicit statement of when to choose this over iam_timer_cancel or what happens if the timer is not yet handled.

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

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

With no annotations provided, the description carries the full burden. 'List' implies a safe read operation and 'outstanding' implies a filter, but it does not clarify whether overdue or snoozed reminders are included, nor does it mention pagination or ordering. The presence of an output schema reduces the need to describe return values.

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

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

It is a single front-loaded sentence with no filler. It is appropriately brief, though it is arguably too terse for the two undocumented parameters.

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 has two optional parameters, zero annotation coverage, and no schema parameter descriptions. The description does not explain due_only or the mailbox default, so an agent lacks enough context to use the filtering options 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 0%, so both parameters depend on the description for meaning. The description implies the mailbox scope, but it does not explain that mailbox is optional or what due_only controls, leaving a key filter 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 description uses a specific verb, 'List', and a specific resource, 'outstanding temporary reminders', scoped to 'this mailbox'. It is clear enough to distinguish this from timer-setting or cancellation siblings, though it does not explicitly name an 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?

It implies a read/list use case but gives no explicit guidance on when to use this tool versus siblings like iam_timer_set, iam_timer_cancel, or iam_timer_snooze. There are no exclusions, prerequisites, or contextual cues for choosing 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?

No annotations are supplied, so the description carries the full burden. It does disclose two useful traits: the reminder fires once ('one-shot') and the time must be an ISO-8601 timezone-aware value. It says nothing about permissions, whether the timer can be replaced or cancelled, or what happens with a past timestamp, which for a mutation-style tool leaves gaps.

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 scope constraint ('this mailbox') and format constraint ('ISO-8601 timezone-aware') are both placed where an agent will read them first. It is efficient, though the terseness is more a symptom of what is omitted than of disciplined editing.

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 zero annotations, 0% parameter description coverage, and a write-oriented action, the description should carry far more than one sentence. An output schema exists so return values need not be explained, but the tool's interaction with the other timer siblings (replacement, cancellation via iam_timer_cancel, mailbox targeting) is entirely 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%, so the description must compensate for three undocumented parameters. It usefully pins down 'due_at' as an ISO-8601 timezone-aware time and implies 'note' is the reminder text, but 'mailbox' is only gestured at by 'this mailbox' – it never says whether that is an address, a handle, or that null means the default.

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 ('Set') and resource ('a one-shot reminder') scoped to 'this mailbox', which is enough to distinguish it from the team variant and the 'set_for' sibling by implication. It stops short of naming a sibling, so the differentiation must be inferred from 'this mailbox'.

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 guidance and no alternative is named, even though the sibling list contains iam_timer_set_for, iam_timer_set_team, schedule_next_wake and iam_timer_snooze, all plausibly competing choices. The only hint is 'one-shot', which weakly implies non-recurring vs. the 'for'/'team' variants.

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

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

With no annotations, the description carries the full burden; it does useful work by disclosing the required timer.schedule permission. It does not say what happens if a target already has a timer (overwrite vs error), what happens on failure, or how the target is resolved.

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 the action first and the permission constraint second, and no wasted words.

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

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

For a four-parameter mutation tool with no annotations and 0% schema description coverage, one sentence is too thin — an agent cannot reliably format `due_at` or resolve `target`/`mailbox` from this. The existing output schema covers returns, but the input side is under-specified.

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 0% and the description explains none of the four parameters. Only "teammate" weakly hints at what `target` should be; `note`, `due_at` (format/timezone?), and optional `mailbox` are entirely undefined.

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 ("Schedule a timer") and scopes it to "one authorized teammate," which implicitly separates it from the team-wide and personal timer siblings. It stops short of naming iam_timer_set or iam_timer_set_team, so the agent must infer the boundary.

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 "for one authorized teammate" implies when this tool applies versus the team variant, and the permission prerequisite is stated. However, there is no explicit when-not guidance or routing instruction to the sibling timer 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?

With no annotations, the description carries the full behavioral burden, and it only discloses the authorization requirement. It says nothing about side effects, whether an existing team timer is replaced, how it interacts with iam_timer_cancel/iam_timer_clear, or whether the grant is checked at call time.

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 purpose front-loaded and no filler. The brevity is a strength structurally, though it exposes the under-specification penalized in other dimensions.

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

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

An output schema exists, so return values need not be described, but for a 4-parameter mutation with 0% schema documentation the description is too thin: no parameter meaning, no due_at format, no clarification of "independent timers" versus the sibling timer tools.

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

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

Schema description coverage is 0% across 4 parameters, so the description must compensate and does not: team, note, due_at and mailbox are never mentioned, and even the due_at format/expected timezone is left entirely 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?

States a specific verb and resource ("Schedule independent timers ... for a team"), which lets an agent distinguish this from the personal iam_timer_set / iam_timer_set_for siblings. The qualifier "independent" is unexplained, but the team-scoped scheduling purpose is clear.

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

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

The sentence "Only an explicitly granted active leader may use this" gives a real precondition, implying when-not-to-use. However, it never names the alternative sibling (iam_timer_set_for for individuals, iam_timer_set for self) or states what an agent should do if the caller isn't a leader.

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?

No annotations are provided, so the description carries the full burden. It does disclose two non-obvious behavioral facts — the timer must be 'outstanding' and the new time must be ISO-8601 timezone-aware — but says nothing about failure behavior for missing/cancelled timers, whether the original schedule is replaced, or whether it is idempotent.

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 the action front-loaded and zero redundant wording. Nothing to trim 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?

An output schema exists so return values need no explanation, and two of three parameters are covered. The undefined 'mailbox' parameter and the absence of any sibling routing (vs iam_timer_set_for, iam_timer_cancel) keep it short of complete for a mutation tool with no annotations.

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 partially does: 'one outstanding timer' maps to timer_id and 'ISO-8601 timezone-aware due time' gives a concrete format for due_at. The optional 'mailbox' parameter is entirely unexplained in both schema and description, leaving a real gap.

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 ('Move one outstanding timer to a new ... due time'), so the agent knows it reschedules an existing timer rather than creating one. It implicitly separates itself from iam_timer_set/iam_timer_set_for (create) and iam_timer_cancel/iam_timer_clear (delete), but 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?

The word 'outstanding' hints that the timer must already exist and be pending, which is useful pre-call context. However there is no explicit when-to-use statement, no exclusion of alternatives like iam_timer_set_for, and no guidance on what to do if the timer is already fired or cancelled.

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 word 'Return' implies a read-only, side-effect-free lookup, which is the key behavioral fact for an unannotated tool. However, it says nothing about permissions, whether the response can fail for an unbound mailbox, or how the mailbox param affects resolution.

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 with no filler. Every word carries meaning and there is nothing to trim.

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?

Because an output schema exists, return values need not be described, which keeps this from being worse. Still, an optional parameter is left unexplained and no context on failure or auth is given for a tool whose whole job is identity resolution.

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 0% and the single optional 'mailbox' parameter is never mentioned in the description. It is unclear whether supplying it overrides the bound identity, filters, or is ignored, so the description fails to compensate for the schema gap.

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 returns the mailbox identity bound to the server. That is enough to distinguish it from mutation siblings like iam_send or iam_email, though it doesn't explicitly contrast with the nearby iam_list_mailboxes.

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 guidance on when to call this versus iam_list_mailboxes, and no mention of prerequisites or what the optional mailbox argument changes. The agent must infer usage entirely from the name.

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

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

With no annotations, the description carries the full burden and does disclose non-obvious behavior: one-shot semantics, that only the matching name is replaced, that omission falls back to 'default', that owner pause suspends delivery but not the schedule itself, and that global wake spacing is 15 minutes. Missing are permission/auth requirements and failure behavior, but the mutation and lifecycle traits are unusually well surfaced.

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

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

Five tight sentences, front-loaded with the core constraint and no filler. The final clause ('Reasons are continuity, not authority') is terse to the point of being cryptic, which costs a little clarity.

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

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

An output schema exists so return values need not be explained, and the description covers timing and replacement semantics. But for a 3-parameter tool with zero schema descriptions, the absence of timestamp format guidance and any failure/edge-case behavior leaves the definition only adequate.

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 adds the meaningful 15-minute minimum for timestamp, the name-replacement/default behavior, and a hint that reason is continuity-oriented, but it never states the timestamp format or what a valid reason looks like, leaving required-parameter syntax 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 description conveys a one-shot, time-based appointment keyed by name, and the '15 minutes ahead' constraint narrows intent. However, the verb 'Choose' does not clearly signal scheduling/wake-setting, and it never contrasts with timer siblings like iam_timer_set or with cancel_next_wake. An agent must infer from the tool name that this creates a wake schedule.

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?

'At least 15 minutes ahead' and 'Replaces only that name' imply the conditions for use, and the pause note hints at interaction with owner state. But there is no explicit when-to-use vs. when-not, and no guidance on choosing this over the many timer siblings (iam_timer_set, iam_timer_set_team).

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