BotmailMCP

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and 'Move ... to archive box' is consistent with a non-destructive state change. The description adds the storage-reclamation motive, but says nothing about reversibility, idempotency (despite the operationId requirement), or what happens on repeated calls.

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

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

A single short sentence with the action and its benefit front-loaded; nothing is wasted. It is arguably too terse rather than verbose.

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

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

For a two-parameter write tool with annotations present, this is minimally adequate. Missing is the crucial positioning against delete_message and any note that archiving is recoverable, which is exactly the decision an agent needs to make.

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

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

Schema description coverage is 100%, documenting both messageId and operationId (including the idempotency-key role). The description adds no parameter detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Move a message to the archive box') plus the outcome ('free up active inbox storage'). It doesn't differentiate itself from the closest sibling, delete_message, so an agent must infer the archive-vs-delete distinction.

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 'to free up active inbox storage' hints that this is the non-destructive alternative to deleting, but neither the alternative nor the condition for choosing it is stated explicitly. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only the auth-scoping notion of an 'authorised project'; it says nothing about idempotency via operationId, what an ephemeral inbox with expiresIn does on expiry, or whether creation is reversible.

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

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

A single front-loaded sentence with zero padding, which is structurally sound. However its brevity comes at the cost of the missing detail noted elsewhere rather than through efficient packing.

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 six-parameter mutation with no output schema and low schema description coverage, the description should explain the ephemeral/persistent choice and expiry behaviour. It leaves the agent to guess at the most consequential parameters of a create operation.

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 33%: only projectId and operationId carry inline descriptions. The description mentions no parameters at all, leaving type (persistent vs ephemeral), prefix, expiresIn format and displayName semantics entirely undocumented outside the bare schema constraints.

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

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

States a specific verb and resource ('Create a new inbox') with the scoping qualifier 'inside an authorised project', which is enough to separate it from read-side siblings like list_inboxes. It does not name any sibling explicitly, so it stops short of the top band.

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 guidance on when to use this versus list_inboxes or how it relates to other write tools; the only contextual hint is the implied 'authorised project' scoping. An agent must infer everything about preconditions and alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is largely covered. The description adds useful context with 'Permanently,' clarifying irreversibility beyond the annotation, but it does not describe return behavior, authorization, or other operational details.

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 immediately states the action and the practical reason for using the 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?

For a simple two-parameter delete tool with full schema coverage and descriptive annotations, the description provides enough context to invoke it safely: permanent deletion and quota cleanup. It is not fully complete because it omits any mention of return behavior or recovery implications, though no output schema exists to carry that.

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

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

Schema description coverage is 100%, so messageId and operationId are already documented in the input schema. The description does not add parameter-level meaning beyond what the schema provides, which matches the baseline of 3 when schema coverage is high.

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: 'Permanently delete ... message.' It is clear what the tool does, but it does not explicitly differentiate itself from the sibling archive_message tool.

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

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

The phrase 'to clean up storage and stay within quotas' gives clear context for when to use the tool. It does not explicitly say when not to use it or name archive_message as the non-destructive alternative, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds meaningful context beyond those annotations: routing is workspace-internal, uses the Free Internal Escalation Bus, and incurs zero external credit cost. It does not detail idempotency behavior or side effects, but the schema covers the idempotency key requirement.

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

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

A single sentence, front-loaded with the action and target, with no wasted wording. The trailing cost detail is relevant and earns its place.

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

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

For a write tool with six fully documented parameters, annotations covering safety hints, and no output schema, the description provides sufficient context to call it correctly. It omits success/error behavior and deeper idempotency explanation, but those are largely covered by the schema.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description adds no parameter-level semantics beyond the purpose statement, which is acceptable when the schema fully documents each parameter.

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

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

The description states a specific action (route or escalate an inbound message) with clear scope: internal bus, another @botmail.work inbox in the same workspace, and zero external credit cost. This differentiates it from external-send siblings like send_message without needing to name them.

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

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

The description gives a clear context for use: internal escalation within the workspace with no external credit cost. It does not explicitly name alternatives or when-not-to-use conditions, but the internal-only/cost framing provides strong implied usage guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context that the body is bounded and truncation metadata is returned, but it does not explain truncation limits or edge cases such as missing messages.

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 efficiently conveys the core action and the notable return behavior.

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

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

For a simple one-parameter read tool with annotations covering safety, the description is mostly complete. It notes truncation behavior, though it stops short of explaining how truncation is signaled or what happens when the message does not exist.

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

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

Schema description coverage is 100% for the single messageId parameter, so the schema already documents its meaning. The description does not add syntax, format, or constraints beyond what the schema provides, which is the expected baseline for high schema coverage.

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 ('Get a single message') and contrasts with list/search siblings by emphasizing single-message retrieval. It also mentions bounded body and truncation metadata, giving a concrete sense of the result.

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

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

Usage is implied by the need to fetch one message, presumably by ID, but the description does not explicitly state when to use this tool versus list_messages or search_messages. No exclusions or alternative routing guidance are provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that this surfaces quota ceilings and pairs that with a remediation hint, which is modestly useful context beyond the annotations. It does not say whether the values are per-workspace vs. per-user, whether limits are rolling or calendar-day, or how limits are enforced on send—real behavioral gaps that remain after annotations.

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

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

Two short sentences, zero waste, with the substantive content ('what you get') front-loaded before the advisory note. Every clause carries information an agent can act on.

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

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

With no output schema, the description carries the whole burden of explaining the return value. It enumerates three categories but gives no sense of shape—whether each limit is reported as used/remaining pairs, percentages, or reset timestamps—which is exactly what an agent needs to parse the response. Adequate to select the tool, thin for interpreting its result.

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

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

The tool takes zero parameters, so there is no parameter semantics to convey and the baseline of 4 applies. The description correctly implies no arguments are needed by describing only the resource being queried.

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

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

Names the specific resource (workspace usage and quota) and enumerates the returned data categories: inbox storage, archive storage, and daily send/receive limits. An agent can immediately tell this is a read of quota state, not a message operation like its siblings. It stops short of a full verb+object statement and never explicitly differentiates itself from the message-management siblings, but the subject matter 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?

There is no explicit 'call this when...' guidance, though the enumerated fields imply the use case (checking remaining quota, diagnosing send failures). The second sentence gestures at follow-up behavior (archive or delete unneeded emails) but frames it as general hygiene advice rather than a trigger condition for invoking this tool. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The only behavioral contribution is the word 'authorised', implying results are permission-scoped, with no mention of ordering, pagination, or what an inbox object contains (and there is no output schema to fill that gap).

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

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

Three words, no filler, purpose front-loaded. Brevity is a virtue here, though it borders on under-specification rather than tight 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 simple two-parameter read tool with full schema coverage and annotations, this is minimally adequate. However, with no output schema, the description could have said what an inbox entry includes or how results are ordered, which would let an agent chain into list_messages confidently.

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 fully documents both parameters (limit with default/max, projectId as an optional filter) at 100% coverage, so the baseline is 3. The description adds no extra meaning about pagination behavior or what 'authorised' scoping means relative to projectId.

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 (List) plus resource (inboxes) with a scope qualifier ('authorised') that separates it from list_messages and list_projects by resource. It does not explicitly name a sibling or contrast with one, 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?

There is no guidance on when to call this versus list_messages, list_projects, or get_usage; nothing says it is the discovery step before list_messages. The agent must infer the workflow entirely from the resource 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?

The annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false. The description adds that results are summaries and scoped to an inbox, but it does not explain pagination, limits, cursor behavior, or what happens with large result sets.

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 short sentence with the key scope and resource front-loaded. It is efficient, though very terse for a tool with several 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?

There is no output schema, and the description does not cover pagination, result limits, or direction filtering. For a list tool with four parameters and limited schema descriptions, the definition is incomplete enough that an agent may not know how to page or filter 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 only 25%, and only inboxId has a schema description, which is essentially just "Inbox ID." The description adds no meaning for limit, cursor, or direction, leaving three parameters undocumented by 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 states a specific verb and resource: "List summaries of messages" scoped to "an inbox." It distinguishes the tool from get_message by saying summaries rather than full messages, but it does not explicitly differentiate from search_messages.

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

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

Usage is only implied by "for an inbox," which signals the required inbox scope. It does not state when to use this tool instead of search_messages or get_message, nor does it mention pagination or filtering context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact — results are filtered to projects the caller is authorised to see — but says nothing about ordering, pagination, or what happens when more projects exist than the limit allows.

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 eight-word sentence with zero filler, and the scope constraint is front-loaded. It is arguably too terse rather than too long, which costs it a point on completeness rather than on structure.

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

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

For a read-only, closed-world list tool with one fully documented optional parameter, no output schema, and annotations covering safety, the description is nearly sufficient. The only real omission is what result ordering and pagination look like, which an agent may need to page correctly past the limit.

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

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

Schema description coverage is 100%: the single 'limit' parameter is documented with default (20) and maximum (50) directly in the schema. The description adds no meaning beyond that, so the baseline of 3 applies.

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

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

'List authorised projects' pairs a specific verb with a specific resource, and the phrase 'in the workspace' plus 'authorised' adds scope that the name alone doesn't convey. It doesn't name or distinguish itself from any sibling, but the sibling set is entirely message/inbox oriented, so there is little realistic confusion.

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 alternatives, no prerequisites, and no exclusions — calling it, versus reading projects from another tool, is left entirely to inference. Only the implicit 'list' semantics signal usage.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful operational fact — the recipient is resolved server-side, so no recipient parameter is needed — but says nothing about idempotency behavior, retry semantics, failure modes, or what the reply returns.

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

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

A single sentence with zero waste and the key constraint (recipient resolution) placed immediately after the action. It is efficiently front-loaded, though it is arguably too terse to carry the necessary behavioral weight.

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-parameter mutation tool with no output schema, the description covers the core action and recipient handling but leaves the caller guessing on idempotency semantics, error cases, and return value. Adequate, but with clear gaps that annotations do not fill.

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 67%: messageId and operationId are documented in-schema, and bodyText is self-evident from its name and length bounds. The description's 'recipient resolved server-side' clarifies an absent parameter but adds no detail on body content constraints or how messageId is obtained.

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 ('Reply') and resource ('an inbound message'), which is meaningfully distinct from the sibling send_message. It stops short of explicitly naming that sibling or stating the boundary condition, but the 'inbound' qualifier does most of the differentiation work.

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 'inbound message' phrasing implies when this applies versus send_message, but there is no explicit when-to-use/when-not guidance, no mention of what happens if the message is outbound or already replied to, and no pointer to the alternative tool.

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

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

Annotations already declare readOnly/non-destructive/closed-world, so the safety profile is covered. The description adds real value by disclosing the searched fields (subject and headers only, not body) and the permission scoping, but omits case sensitivity, result ordering, default limit, and what a match returns.

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 searched fields and scope both appear before any caveats. 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?

With no output schema, the description should say what a result looks like (full messages vs. snippets) and how limit defaults. It covers search scope and permissions but leaves return shape and empty-result behavior unstated for a 3-parameter tool.

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

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

Schema coverage is 67%: query and inboxId are documented in-schema, but limit has no description and no stated default despite a 1-50 range. The description adds nothing about parameters, so it functions at the baseline rather than compensating for the 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 ("literal substring search over subject and headers") plus the scope constraint ("granted inboxes"). An agent can see this is a search tool distinct from a plain list, but no sibling tool (list_messages, get_message) is named to sharpen the distinction.

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 prefer this over list_messages or get_message, and no mention of what to do when the substring doesn't hit the body. The only implicit cue is the "granted inboxes" scope in the schema's inboxId default.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the write/external-facing profile is covered. The description adds genuinely new context: sending requires an 'authorised inbox' and internal recipients are free, which hints at a credit-based quota. It says nothing about what happens on failure, whether credits are debited on failure, or rate limits.

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 tight sentence with the core action front-loaded and the cost caveat in parentheses. Slightly cluttered by the vendor-ish 'Free Internal Escalation Bus' name, but no filler.

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

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

This is a five-required-parameter mutation with open-world effects, no output schema, and no indication of what is returned (message id?) or whether the charge is refunded on failure. The description covers the action and one pricing rule but leaves the agent without enough to invoke it confidently in a credit-metered environment.

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 60%, with only type/format constraints documented for subject and bodyText; the description adds no field-level meaning at all. It repeats the internal-recipient credit rule already present in the `to` parameter description, so it contributes nothing beyond the schema for any of the five required parameters.

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

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

States a specific verb and resource ('Send an outbound message from an authorised inbox') and adds a pricing note. It does not distinguish itself from the closely related siblings reply_to_message and escalate_message, and the phrase 'Free Internal Escalation Bus' arguably blurs the line with escalate_message further.

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 guidance on when to use this rather than reply_to_message (replying in-thread) or escalate_message, which is the most likely point of confusion given the 'Escalation Bus' wording. The only conditional statement is about pricing, not tool selection.

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