mosADD — the comms layer for AI agents

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

Annotations cover safety (idempotent, non-destructive, not read-only), and the description adds real context beyond them: 10-minute command expiry, the fact that clear/new_session do not touch the tunnel's MOM memory, vault, or mail, and the constraint to act only in the agent's own conversation. That clarifies the contradiction risk between 'clear' and destructiveHint=false. It does not discuss failure modes or rate limits, so 4 rather than 5.

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

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

The core action is front-loaded and no sentence is filler — expiry, scope, and caller restriction each earn their place. The second sentence is dense and parenthetical, slightly hampering readability, which keeps it below a 5.

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

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

For a two-optional-parameter mutation tool with full schema coverage and annotations, this is nearly complete: it explains the input round-trip ('they come back in commands') and the answer cycle despite no output schema. Only the concrete response payload shape is left implicit.

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

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

Schema coverage is 100% and both parameter descriptions are detailed, so the baseline is 3. The prose adds meaning beyond the schema by explaining the owner-visibility consequence of declaring verbs and the intended workflow of receiving commands then answering them. It stops short of documenting response shape (e.g., what 'commands' looks like), hence 4.

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 concrete verbs and resources: start a new session, compact conversation, clear it, plus retrieve and answer pending commands. It is distinguishable from every sibling in the list, which are messaging/vault/storage tools. The 'cable'/'tunnel' terminology is slightly opaque, but the operation itself is unambiguous.

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

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

It gives a clear cadence: 'Call it whenever you check in,' and a caller constraint: 'Only a cable key of the tunnel uses it.' It also scopes the action to 'your own conversation only.' No explicit alternative tool is named, but none of the siblings overlap, so the missing comparison is low-cost.

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 the tool is not read-only, is idempotent, and is non-destructive. The description adds valuable domain behavior beyond those annotations: exhausted accounts cause cables to go dark on all lines, and 429 is a temporary jam rather than exhaustion.

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 compact sentences, front-loaded with the reporting action and followed by the critical exhaustion rule. The phrase 'with source and hour' is slightly ambiguous because the schema uses a window enum rather than an hour parameter.

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

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

Covers the important operational semantics for an agent: how to interpret 402, 429, monthly_cap, and used_pct 100. With no output schema, it could say more about what the tool returns or how reset_at and exhausted interact, but the core behavior is adequately conveyed.

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

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

Schema coverage is 100%, so the schema already documents all six parameters, including the error_code enum and used_pct semantics. The description reinforces the high-stakes exhaustion logic but largely repeats what the schema already states.

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

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

States a specific verb and resource: reporting a limit reading for the model account of a cable from the owner's machine. The examples (get_usage, Codex rate limits, provider 402/429) make the domain concrete and clearly distinguish this from sibling messaging/line 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?

Explains the meaning of 402/monthly_cap versus 429, which helps an agent interpret a reading. However, it does not explicitly state when to call this tool versus alternatives, nor what prerequisites must be true before reporting.

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?

Adds substantial context beyond readOnlyHint=false: the consent gate, the calling-user ownership model, sandbox-only execution boundaries, default/capped TTL, and the explicit security caveat that file_request payloads are not yet end-to-end encrypted. This is exactly the kind of limitation an agent needs before calling a mutation tool.

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

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

Front-loaded with the core action and return shape, then capabilities, then honest limits — a sensible ordering. It is dense but nearly every clause earns its place; the action_type enumeration slightly duplicates the schema enum.

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 12-parameter, no-output-schema tool, the description supplies the return shape ({action_id, token, link, expires_at}) and delivery mechanics, which is a real gap-filler. The one incompleteness is the missing screen_share action type in prose, which an agent would only discover from the schema enum or the comms_action_frame_get sibling.

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

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

Schema coverage is 100%, so the schema already documents every parameter including defaults and per-action_type prefixes; the description mostly restates that (TTL default 24h/cap 7d, action_type meanings). It adds little semantic detail the schema lacks, and notably omits screen_share semantics that only appear in the schema.

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

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

States a specific verb and resource ('Mint a single-use, expiring action link') plus the URL shape and enumerates the action types, so an agent knows exactly what this produces and how it differs from send/message siblings. The only blemish is that the prose lists four action_types while the schema enum has five (screen_share is missing from the description).

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

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

Provides clear operational context: the returned link must be delivered via mDM/mIRC/mp0st, the recipient consents in-browser, and each action_type has an inline condition that selects it. It does not contrast against nearby siblings such as comms_embed_create or line_send, so it stops short of explicit 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 only declare readOnlyHint=true; the description goes far beyond by spelling out 'VIEW ONLY — you cannot click or control their screen', noting the return is an image plus its age, and describing polling and no-frame behavior. That is exactly the behavioral context an agent needs for a live-view tool.

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

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

Front-loads the purpose and return type, then adds prerequisites, polling cadence, and limits in short declarative sentences. Every sentence carries distinct, actionable information with no filler.

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

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

There is no output schema, so the description carries the return-value burden and does so: an image, its age, and a 'no frame yet' note. Combined with the prerequisite state and polling guidance, nothing an agent needs to call this correctly is missing.

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

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

The single action_id parameter is fully documented in the schema at 100% coverage, including that it comes from comms_action_create for a 'screen_share' action. The description's mention of the same provenance adds no new syntax or format detail, so it sits at the baseline for high-coverage schemas.

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 ('See the LATEST screen frame from a screen_share action') and explicitly ties it to the sibling that produces the required id (comms_action_create). An agent can immediately distinguish this retrieval tool from the creation 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?

Gives the precondition (recipient must have opened the link and clicked 'share screen'), the operating pattern ('poll this every few seconds to watch live'), and the expected empty-state ('no frame yet' until they start sharing). It also carves out what the tool cannot do, which prevents misuse.

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, so the safety profile is clear. The description adds useful behavioral context beyond annotations: it is a one-time discovery call for carrier-aware hosts and returns a manifest grouped by transport. It does not detail manifest fields or response structure, keeping it short of a 5.

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

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

The description is three tight sentences: purpose first, caller/usage second, return shape third. Every sentence adds value and there is no repetition or filler.

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

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

For a zero-parameter, read-only discovery tool with no output schema, the description covers the essential purpose, caller context, and high-level return shape. It stops short of describing manifest fields or exact grouping structure, which would help an agent parse the result without the output schema.

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

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

The tool has zero parameters, so there is nothing for the description to clarify about parameter meaning. The baseline for a no-parameter tool is 4, and the description appropriately avoids inventing parameter guidance.

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

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

The description names a specific action (discover which mosadd tools are available), a specific resource (tool capabilities), and the key data returned (transport requirements: any | radio | network). It clearly distinguishes this meta-discovery tool from the dozens of sibling action-oriented comms 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 explicitly states the intended caller and condition: 'Carrier-aware hosts (e.g. off-grid radio devices) call this once to gate the tool list to what the current carrier supports.' This gives strong when-to-use guidance, though it does not state when not to call it or name 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?

Goes well beyond the single readOnlyHint:false annotation by disclosing the security model (publishable key is browser-safe, mints only channel-scoped JWTs, hub key never leaves the server) and the consequence of a misconfigured origin (key only works on declared domains). It also states the return shape, which the absent output schema would otherwise leave blank.

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

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

Front-loaded with the action and outcome, then the hard requirement, then the security note and return shape. It is dense and parenthetical-heavy, but nearly every clause carries information an agent needs; only the framework name-drops are mildly expendable.

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 output schema, the description covers the required inputs, the origin-scoping constraint, the dev-vs-prod mode, the security posture, and the exact return keys. An agent has everything needed to invoke it correctly without opening the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema can't: it ties allowed_origins to the runtime constraint and pairs mode:'test' with localhost-style origins. That linkage is genuinely useful beyond the per-field descriptions.

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 ('Embed a LIVE mosadd chat channel into an app/site') and the concrete artifact produced (embed key + ready-to-paste HTML snippet). Clearly distinct from sibling mIRC_* channel-management tools and mIRC_mint_channel_token.

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

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

Gives explicit context (builder-agents on Lovable/Bolt/Cursor/v0) and the required precondition that allowed_origins must be the app's serving domains, plus guidance on mode:'test' for local/dev origins. It does not explicitly name which sibling tool to use instead if you only need a raw channel token, so it stops just 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?

Adds substantial context beyond the annotations: the hold renews automatically, lapses if the session dies, suppresses the cloud stand-in, and ownership of as_agent is verified server-side with strangers refused. The lifecycle semantics are exactly what an agent needs and are not in the structured fields.

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

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

The core action and timing are front-loaded and each sentence carries real information, but the prose is dense and the as_agent clause is embedded mid-paragraph rather than separated, making it slower to scan than it needs to be.

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

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

Covers lifecycle, scoping ('owner-scoped'), and the as_agent mechanism thoroughly for a 3-param optional-args tool with no output schema. The only omission is what a successful claim returns (holder identity, expiry), which is minor given no output schema exists.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining the downstream effect of as_agent (gateway auto-signs channel posts, that agent's stand-in defers) and the immediate-vs-expiry distinction for release. Slight redundancy with the schema's own parameter descriptions keeps it off a 5.

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

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

States a specific verb and resource — 'claim a mosADD reply lane for the CURRENT agent session' — and immediately contrasts the behavior with the alternative ('the 24/7 cloud stand-in stops answering in its place'), which cleanly separates it from siblings like line_attach or mAYL_agentbox_provision.

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

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

Gives explicit timing ('call it once at the start of a session'), an explicit termination call ('Pass release:true when finishing'), and a conditional branch with a concrete example for the as_agent case. When-to-use and when-not are both covered.

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

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

Beyond the annotations, the description discloses the lease model in detail: epoch increment on free/expired lines, renewal on reattach, owner-only switching of another cable's live lease, and renewal via writing. These are important side effects and conditions for a mutating, non-read-only tool, and they align with the annotation hints.

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

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

The description is front-loaded with the core action and the returned identity package, then adds lease rules. It is dense and jargon-heavy, but for a tool with nontrivial lease semantics, most sentences carry useful information.

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

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

Given the absence of an output schema, the description compensates by enumerating the identity package returned. It also covers lease acquisition, renewal, ownership switching, and epoch behavior, which are the key contextual details needed to invoke the tool 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?

The schema has 100% description coverage for both parameters, so the baseline is 3. The description adds the useful conceptual mapping 'cable = a model' but does not add further semantics for model or runs_on beyond what the schema already provides.

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 and resource: plug a session into its line and obtain the identity package including line, lease, epoch, persona, wiring, memory brief, and cursors. It is clear what the tool does, though it does not explicitly name sibling alternatives such as line_release or line_handover to sharpen selection.

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 clear context for when to attach: to take a free/expired line lease or to renew an existing attachment with the same cable. It also states the owner-only rule for switching live leases and notes that writing renews the lease, but it does not explicitly compare against sibling tools or list when not to use this tool.

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

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

Annotations already declare idempotent=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context the annotations don't carry: the lease-ownership authorization requirement and the fact that no new message is dispatched. It omits platform-level caveats (e.g. Telegram edit windows or re-edit semantics), keeping it just short of a 5.

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

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

Three short sentences with zero filler: action, provenance of the ID, explicit non-effect, and the authorization constraint. The most decision-relevant facts are front-loaded.

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

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

With annotations covering safety and idempotency, a complete schema, and no output schema requiring explanation, the description supplies what's missing: the lease requirement and the no-new-send guarantee. What remains unexplained — failure modes or whether prior text is recoverable — is minor for a non-destructive, idempotent edit.

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

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

Schema description coverage is 100%, so all three parameters (text, message_id, parse_mode) are already documented, and parse_mode has an enum. The description adds only the provenance hint for message_id ('from line_send or line_inbox'), which is useful but marginal against a fully documented schema — baseline 3 applies.

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

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

Names a specific verb (edit) and resource (text of a message this line previously sent), plus the scope qualifier 'this line sent earlier' and the platform (Telegram). It also pre-empts confusion with the larger send family by stating 'Nothing new is sent,' so an agent can distinguish it from line_send without opening a schema.

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

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

Explicitly routes the agent to line_send or line_inbox as the source of message_id, and states the hard prerequisite that only the cable holding the line's lease can edit. It stops short of naming the alternative tool to call when a new message is actually wanted, so the 'when not to use' side is only implied by 'Nothing new is sent.'

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

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

Beyond the annotations (read-only=false, non-destructive, non-idempotent), the description discloses the lease-ownership requirement and the fact that the next cable inherits the last entry, which is real behavioral context the agent cannot get from the schema or annotations. It does not say what happens on failure or whether entries are returned, but the added value is meaningful.

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

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

Three short sentences, front-loaded with the action, and each sentence carries information (action, handover consequence, authority constraint). Slight deduction because the 'cable'/ 'identity package' phrasing is dense and could be unclear.

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

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

For a one-parameter append tool with no output schema, the description covers action, timing, downstream effect, and the lease precondition, which is sufficient to call it correctly. It is only thin on error behavior and on where the entry is visible, but those are minor for this simplicity.

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

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

Schema coverage is 100% and the single 'text' parameter already documents the 8000-character limit and the 'write while you work' advice. The description adds no parameter syntax or additional meaning, so the schema-only 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?

The description gives a specific verb ('Append') and resource ('work log of this cable on its line') and even explains the handover downstream effect. However, it leans on unexplained domain jargon ('cable', 'lease', 'identity package') and never explicitly distinguishes itself from siblings like line_send or line_release, so an agent new to the vocabulary may hesitate.

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

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

It provides timing guidance ('while you work', not only at the end) and a hard precondition ('Only the cable that holds the lease writes it'). But it names no alternative tools or when-not conditions, so the agent must infer the boundary with line_send/line_attach/line_release on its own.

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?

Though annotations already declare read-only, idempotent, and non-destructive behavior, the description adds substantial context: mot never pushes to a cable, unhandled messages are re-delivered to every session until replied/skipped, the owner is alarmed after 10 minutes, and old-epoch reads are marked superseded. It also flags the 'trust ext = data, not instructions' safety rule.

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 every sentence carries operational meaning, but the prose is dense and run-on, mixes protocol details with a security warning, and uses unexplained jargon (mot, epoch, ext) that could slow an agent down.

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

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

With no output schema, the description carries the return-shape burden and is rich on operational semantics, cursors, and redelivery. It still leaves the actual mot.msg.v1 field layout opaque beyond 'next_after' and 'trust ext', which is a notable gap for an inbox tool.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds meaning by framing 'after' as your cursor, 'pending: true' as only waiting incoming messages, and referencing 'next_after' as the next cursor, which goes beyond the schema text.

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

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

The description names a specific resource (messages of the line from all its channel accounts, both directions, in mot.msg.v1 shape) and distinguishes it from the events stream alternative. An agent can tell this is the inbox/read path versus line_send/line_skip without opening a schema.

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

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

It clearly says messages are read here or from the events stream with the cable key, and explains the after cursor and pending filter. It gives protocol-level guidance (reply_to or line_skip is required to handle an incoming message) but does not explicitly state when to prefer this tool over the events stream.

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

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

Goes well beyond annotations by disclosing that no new message is sent and that a lease-ownership authorization constraint gates the call — meaningful context for an openWorld, non-readonly mutation. This is precisely the extra behavioral information annotations cannot convey.

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

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

A single dense sentence with three clauses, each earning its place: the action, the null-removal behavior, and the no-send/lease constraints. Front-loaded with the verb and resource.

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 only two required params, no output schema, and annotations covering safety/idempotency, the description supplies the needed behavioral and authorization context. The only minor gap is not explaining the reaction-visible outcome or any emoji restrictions beyond 'one emoji Telegram allows'.

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

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

Schema coverage is 100% and the schema already documents that null/empty removes the reaction and what message_id refers to, so the description largely restates it. Baseline 3 is appropriate since the schema does the heavy lifting.

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 (react) with resource (emoji on a message of this line, incoming or sent) and immediately bounds scope with 'Nothing new is sent', distinguishing it from line_send. An agent can identify the operation without opening the schema.

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

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

Explains the null-emoji case (removes the reaction) and the precondition that only the lease-holding cable may react, which effectively tells the agent when it can and cannot use the tool. It does not name sibling alternatives explicitly, keeping it 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?

Annotations already flag non-readonly, non-idempotent, closed-world, so the bar is lower; the description still adds real value by disclosing the precondition (must hold the lease) and the side effect (a handover is deposited for the next cable in its identity package). It stops short of saying what happens on an unauthorized release attempt.

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

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

Two sentences, front-loaded with the action and followed by the precondition. The parenthetical '(it comes in its identity package)' is terse domain jargon that costs a little clarity but occupies minimal space.

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 one optional, fully-described parameter, no output schema, and annotations covering the safety profile, the description supplies the remaining essentials: the lease-holder precondition and the handover side effect. Error behavior on a failed release is the only notable omission.

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

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

Schema coverage is 100% and the single optional parameter is fully documented in-schema, so the baseline applies. The description restates the handover's purpose and audience ('for the next cable') but adds no format or length guidance beyond what the schema supplies.

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 — releasing the line's lease — and adds the scope of what the operation leaves behind (a handover). It implicitly contrasts with line_attach (acquiring) but never names a sibling outright, so differentiation relies on the reader's inference.

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

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

"Only the cable that holds the lease can release it" gives a real precondition for use, but there is no explicit when-not guidance and no pointer to line_handover for the case where the agent only wants to update the handover without dropping the lease.

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, idempotent, non-destructive, closed-world, so safety is covered. The description adds real context beyond that: results are ordered heaviest-first, and the payload includes a rule-kind catalog and weekly stopped-result counts. It stops short of explaining what 'MASTER stopped' means or the response 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?

A single dense sentence with the primary payload front-loaded and the optional flag last. It earns its length, though the compressed jargon ('heaviest first', 'MASTER stopped') slightly undercuts readability.

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

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

With no output schema, the description must convey the return structure; it sketches three parts (ordered live rules, rule-kind catalog, weekly stop counts) but leaves the meaning of key terms and the shape of each part ambiguous. Adequate but not sufficient for confident invocation.

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

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

Schema coverage is 100% and the schema already explains history as 'last 50 retired rules (superseded decisions included)'. The description's 'history: true adds the last 50 retired rules' largely restates it, adding only marginal framing – baseline 3 applies.

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

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

The description names the resource ('this line's rider') and what is returned (live rules, catalog of rule kinds, weekly stop counts), so the basic read operation comes across. However, 'rider' and 'MASTER' are undefined domain jargon, and nothing distinguishes it from siblings like line_rider_put, line_rider_retire, or line_wiring_list.

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

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

There is no statement of when to call this versus line_rider_put/line_rider_retire or other line_* tools. The only conditional mentioned (history:true) is a parameter option, not 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?

Goes beyond the annotations meaningfully: it discloses that SHELL replays riders on every start ordered heaviest-first, and that a newer decision on the same scope retires the older one — a real side effect not covered by destructiveHint=false. The 'never put secrets in a rule' caution is also useful operational guidance. It does not say what the response looks like or how duplicates behave, which is why it is not a 5.

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

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

Dense but front-loaded: purpose first, then behavior, then per-kind requirements, then a safety caveat. A few domain terms ('SHELL', 'mot catalog') assume context, but nearly every sentence carries distinct information.

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

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

For a non-idempotent write with no output schema, the description covers side effects (retirement of older decisions), ordering behavior, and a security caveat. Remaining gaps — return value and duplicate handling — are minor given the annotations already declare it is non-destructive and non-idempotent.

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

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

Schema coverage is 100%, so the schema already documents all six parameters including kinds, weight range, and decision-only fields. The description reinforces the decision triple (scope, said_at, quote) and the scope-collision rule, adding a little meaning beyond the schema, but nothing about value formats that the schema does not already carry.

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 rule ... for this line') and enumerates the rule kinds it accepts, so an agent knows exactly what is being created. It does not explicitly contrast with line_rider_list or line_rider_retire, so sibling differentiation is only implicit through the verb and kind list.

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

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

The description implies when to use it (when the owner has a brand/naming/tone/forbidden/language/decision/proof rule to persist) and gives conditional requirements for decisions. It never states when not to use it, nor points at line_rider_retire for removal or line_rider_list for inspection, leaving the alternative routing to the agent.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so 'retiring a retired rule changes nothing' largely restates the annotation rather than adding new information. What the description does add is that the rule is archived to history rather than deleted, which supports the non-destructive hint, but it omits what permissions are needed and whether retirement can be undone.

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

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

Two short sentences, the core action front-loaded, and the edge case (already retired) stated immediately after. Nothing redundant or padded.

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

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

For a two-parameter mutation with full schema coverage and annotations covering safety and idempotency, this is nearly complete. Minor gaps: no mention of behavior when rule_id is unknown, and no note that reason is optional.

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

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

Schema coverage is 100% and both parameters are documented in the schema itself ('rule_id from line_rider_list', 'Why the rule leaves the rider'). The description's phrase 'with a reason' adds tone but no syntax or constraint detail beyond what the schema already gives, so baseline 3 applies — and it slightly overstates by implying reason is required when only rule_id is.

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 — moving a rider rule to history — which is clearly distinct from line_rider_put (modify) and line_rider_list (read). It never names those siblings explicitly, so the differentiation is inferable rather than stated.

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

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

The purpose implies the when (a rule should be removed from active use), and the second sentence warns about a no-op case. But there is no explicit guidance on when to retire versus using line_rider_put to alter a rule, nor any stated prerequisites.

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

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

Annotations already declare non-read-only, open-world, non-idempotent, non-destructive, so the safety profile is covered. The description adds real context beyond them: sending is gated by lease ownership ('Only the cable that holds the lease sends'), the message is stamped with cable and epoch, and the send is recorded to the line's memory — all behavioral facts the annotations do not carry.

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

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

Front-loaded with the core action and compressed into a single dense sentence with no filler. The domain vocabulary ('cable', 'epoch', 'the memory of the line') makes it harder to parse on first read than a plainer phrasing would, costing it the top mark.

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 13-parameter, all-optional tool with no output schema, the description covers the essential question — how the destination account is chosen — and the privilege model for sending. Remaining gaps are the relationship to the overlapping siblings (line_edit, line_react) and which parameter combinations are valid, which are only implicit in 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 a baseline of 3 would be defensible. The description goes further by articulating the precedence chain among the mutually optional addressing parameters (reply_to > account > kind defaults), which the per-parameter schema text does not state as a combined rule for a tool with zero 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 a message as the line') plus the scope of channels it can route through (Telegram bot, Gmail, wired accounts). However, it never distinguishes itself from the sibling tools line_edit, line_react, and line_inbox, which overlap with the 'edit', 'react_to', and 'reply_to' parameters documented in this schema — an agent has no signal about which entry point to prefer.

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 resolution order for the addressing parameters: 'reply_to answers through the same account and thread, account picks an account, kind uses the default outgoing account of that kind.' That is genuine when-to-use-which guidance. It stops short of exclusions, e.g. it does not tell the agent when to call line_edit or line_react instead of using the built-in edit/react_to parameters.

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

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

The description adds substantial behavioral detail beyond annotations: it leaves line_inbox pending, stops the no-reply alarm, requires the lease-holding cable, stamps the skip with cable and epoch, and preserves prior replies. These are meaningful side effects and constraints for a mutation tool whose annotations already indicate it is non-readonly, idempotent, and non-destructive.

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

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

The description is front-loaded with the core action and then layers behavioral details in a logical order. Every sentence contributes distinct, useful information without repetition, and the overall length is appropriate for a two-parameter mutation 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?

Given that annotations cover safety traits and the input schema is fully documented, the description completes the picture by explaining side effects, lease requirements, and interaction with existing replies. With no output schema, no return-value explanation is needed, and the behavioral scope is sufficiently comprehensive.

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

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

Schema coverage is 100%, so both message_id and reason are fully described in the input schema. The description does not add meaning beyond the schema for these parameters, making the baseline score of 3 appropriate when the schema carries the parameter 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 and resource: 'Mark an incoming message of the line as handled without a reply'. It clearly distinguishes this from replying tools by emphasizing 'without a reply' and mentions the line_inbox state, making it identifiable among siblings like line_send and line_inbox.

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

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

It provides clear when-to-use context with examples such as spam, duplicate, or answered elsewhere, and explains that already-answered messages remain answered. However, it does not explicitly name alternatives like line_send or line_inbox for different scenarios, 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds a useful disclosure about return content — that secrets are never exposed — which is genuine value beyond the annotations.

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

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

Two sentences, front-loaded with the resource and its fields, then a security note. 'Secrets never leave mot' is slightly cryptic because 'mot' is undefined, but overall it is tight.

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 parameters, no output schema and rich annotations, the description supplies the missing piece — the shape of the returned data (direction, memory policy, default outgoing flag, health) and the secret-handling guarantee. Adequate for an agent to call it correctly.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the schema needs explanation, and the description does not clutter with nonexistent inputs.

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

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

The description names a specific resource (channel accounts wired to a line) and enumerates the fields returned, so an agent can distinguish it from mutation siblings like line_attach. The phrase 'of this key' is a bit opaque given there are no parameters, but the intent is still 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?

There is no statement of when to call this versus alternatives, nor any precondition (e.g., that a line must already be attached). 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?

Annotations only say this is non-read-only and non-destructive; the description adds far more: the return shape (ok plus naruszenia with fragment, rule, hint), the explicit non-behavior ('does not rewrite your text'), and the side effect that explains readOnlyHint=false (two failures in a row go to the LEDGER). That is exactly the context annotations cannot convey.

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

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

Four compact sentences, front-loaded with the action and the trigger, then the checks, then the return shape, then the retry rule and the ledger consequence. Nothing is redundant and no sentence could be dropped 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?

There is no output schema, and the description compensates by naming the returned fields and their contents. Combined with the retry instruction and the ledger side effect, an agent has everything needed to call it and act on the result.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents 'text' including its 20000-character bound. The description reinforces intent ('exactly as you would send it') but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Run your result through MASTER') and enumerates exactly what is checked: forbidden words, names outside the rider, foreign language, placeholders, foreign brand, unnumbered promises. No sibling tool does anything comparable, so an agent can select it unambiguously.

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?

Timing is explicit ('before it goes to the owner') and the failure loop is prescribed ('fix it yourself and check again'). It also warns that two consecutive failures are recorded in the LEDGER. What is missing is any statement of when not to use it, but with no competing sibling the guidance is effectively complete.

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

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

Annotations only declare readOnlyHint=false, so the description carries most of the burden and does it well: TTL is measured from NOW rather than added to the existing expiry, the 24 h ceiling is stated twice (description and param), and owner scoping is disclosed. It stops short of saying what happens to an already-expired box or what the call 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?

Two dense sentences, operation and scope front-loaded with the TTL caveat in a parenthetical. No filler; only the parenthetical nesting slightly hurts scanability.

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

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

For a two-parameter mutation with no output schema, this covers the critical facts: eligibility (ephemeral only), TTL semantics (from now, max 24 h), and ownership. Missing only return/error behaviour (expired or unknown id) which an agent would otherwise have to discover empirically.

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

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

Schema coverage is 100%, so both id (UUID sourced from provision/list) and ttl_seconds (default 600, max 86400, exclusive minimum) are already fully documented. The description's 'counted from NOW' echo adds a little semantic nuance about non-additive behaviour but is largely redundant with the schema text.

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

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

States a specific verb and resource: extend the lifetime of an EPHEMERAL agent inbox, by id. The qualifier that persistent boxes never expire and cannot be extended distinguishes it cleanly from the provisioning, listing and release siblings 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?

Gives a clear when-not: persistent boxes cannot be extended, so the agent knows only ephemeral boxes qualify. It also flags owner scoping as a precondition, but does not explicitly route to a sibling (e.g. provision) when the box is persistent or already expired.

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, so the safety profile is covered. The description adds real value beyond that: sort order ('newest first'), scope ('Owner-scoped'), and the exact result fields (address, display_name, kind, agent_id, expires_at) that stand in for the missing output schema. It stops short of any volume, pagination, or expiry-filtering behavior.

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

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

Two short sentences with zero filler, front-loaded with the action and object. The field list is parenthetical and the scope constraint is a terse trailing fragment, so every clause carries information.

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

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

With no parameters and no output schema, the description compensates by enumerating the returned fields and their ordering, which is the main thing an agent needs. It leaves open whether results are bounded or paginated and whether 'active' excludes anything, which are the only remaining 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline applies. The description correctly omits any param discussion and instead spends its words on scope and return shape.

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 a specific resource ('your active agent inboxes') and the exact fields returned. An agent can distinguish it from mAYL_agentbox_provision/extend/release by the 'list' verb, but the description never names those siblings or the related mAYL_list tool, so differentiation is inferred rather than stated.

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

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

Usage is only implied: 'your active agent inboxes' and 'Owner-scoped' suggest the call is for inspecting your own inboxes before acting on them. There is no explicit when-to-use, when-not-to-use, or routing statement pointing at a sibling such as mAYL_agentbox_extend or mAYL_agentbox_release.

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

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

Annotations only give readOnlyHint=false, so the description carries the burden and does so well: it discloses the default 10-minute TTL, auto-expiry/reaping, persistent alternative, the 86400s cap, owner scoping, and the 25-box quota. These are non-obvious operational constraints an agent could not infer elsewhere.

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 primary action and address format come first, followed by TTL options and the read workflow. It is information-rich rather than padded, though the accumulated detail makes it heavier than a strictly minimal definition.

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

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

No output schema exists, yet the description supplies the return shape {id, address, expires_at}. Combined with the TTL, quota, and downstream read path, an agent has everything needed to provision and then use the box correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter thoroughly. The description reinforces the defaults (ephemeral, 10-minute TTL, persistent alternative) but adds no syntax or nuance beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb ('Mint') and resource (a real disposable inbox at agent-<hex>@mosadd.com) with the send/receive capability spelled out. This is distinguishable from siblings like mAYL_agentbox_extend or mAYL_agentbox_list, which operate on existing boxes.

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 frames the workflow: mint the box, then use mAYL_list (filtered by address) plus mAYL_view to read arrivals. It doesn't mention the sibling lifecycle tools extend/release, so it stops short of a fully exhaustive when-to-use map, but the primary usage path is clear.

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

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

Annotations declare destructiveHint=true, and the description adds real context beyond that: deletion is immediate, the address stops receiving right away, and the operation is owner-scoped. It stops short of stating irreversibility or the error behavior for an unknown or already-released id.

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 destructive action, the resource, the immediate consequence and the ownership scope — no filler.

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

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

For a one-parameter destructive tool with annotations covering the safety profile and no output schema, the definition is nearly sufficient. The only missing piece is what happens when the id is invalid or already released.

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

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

Single parameter with 100% schema description coverage; the schema already explains the UUID and where to obtain it. The description only echoes 'by id', adding no format or constraint detail beyond the schema.

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

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

States a specific verb ('release/delete'), the resource ('agent inbox'), the selector ('by id') and the scope ('owner-scoped'). An agent can distinguish it from mAYL_agentbox_provision/list, though no sibling is named explicitly in the text.

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

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

'Frees the address immediately so it stops receiving' implies the intent (decommissioning an inbox), but there is no explicit when-to-use vs. alternatives guidance — e.g. it does not contrast itself with mAYL_agentbox_extend for keeping the address.

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

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

Goes well beyond the readOnlyHint annotation: it discloses the HMAC-SHA256 signature over canonical JSON, the exact contents of the payload (event trail plus totals), the owner-scoping authorization constraint, and candidly bounds what the proof means (observed vs. a qualified ERDS receipt). That is exactly the kind of trust-relevant context an agent cannot infer from schema or annotations.

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

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

Front-loaded with the action and artifact, then the mechanism, then the caveat — a sensible order. Slightly dense with jargon ("RMail-style", "mosadd") that costs a little readability, but no sentence is filler.

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

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

There is no output schema, and the description compensates by describing what the report contains (event trail, print/copy/forward signals, totals, signature). Scope, authorization and limitations are all covered, so an agent has everything needed to call it and interpret the result.

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

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

The single message_id parameter is fully documented in the schema (100% coverage), including that it comes from mAYL_send or inbox. The description adds only the implicit constraint that the message must be a sent email; with one well-documented param, baseline 3 is appropriate.

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

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

States a specific verb (Export) and a precisely scoped resource (a tamper-evident engagement audit report for one sent email), plus the contents of that report. It is clearly distinguishable from siblings like mAYL_events, mAYL_metrics and mAYL_stats which read raw engagement data rather than a signed export.

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?

"For legal/compliance use" plus the HONEST LIMIT note gives clear conditions for reaching for this tool rather than raw event/stats endpoints. It stops short of naming an explicit alternative or stating when-not to use it (e.g. for bulk export or non-compliance inspection).

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

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

Annotations only declare readOnlyHint=false, so the description carries most of the load, and it does add real behavior: opt-outs originate from the footer link, mAYL_send then suppresses pixel and link-wrapping automatically, and scope is owner-limited. It omits what happens when 'check'/'optin' targets an unknown or non-owned recipient, and whether 'optin' 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?

Front-loaded with the purpose, then the action semantics, then the downstream effect on mAYL_send — the ordering matches how an agent reads. Slight redundancy with the schema's own enum descriptions keeps it from a 5.

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

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

For a 2-parameter tool with full schema coverage and no output schema, the description supplies the missing behavioral context (opt-out origin, send-time effect, ownership scoping). It could still say what 'list' returns and whether 'optin' confirms or errors, but nothing essential to calling it correctly is absent.

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

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

Schema description coverage is 100%, so both 'action' and 'recipient' are already documented, including the enum meanings and the 'required for check/optin' rule. The description restates those semantics rather than adding format or edge-case detail, which is the baseline 3 case.

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

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

Names a specific verb and resource ('Manage recipient tracking opt-outs') and enumerates the three discrete actions with what each does. It also distinguishes the tool from the send path by explaining that mAYL_send consumes this state, so an agent can place it relative to siblings without opening a schema.

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

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

Each action value is paired with the situation that selects it ('list' for the whole opt-out set, 'check' for one recipient, 'optin' to re-enable), which effectively tells the agent when to use which mode. It stops short of explicit exclusions or prerequisites (e.g. permission level needed to run 'optin' for another owner's recipient).

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

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

Annotations only give destructiveHint=true; the description adds the material behavioral facts beyond that: the delete is a soft-delete, its observable effect is removal from mAYL_list, and it is owner-scoped to the caller's own mail. It does not state whether the message can be restored or how long it persists, which is the main remaining gap for a mutation 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?

Three short clauses, front-loaded with verb and resource, then the soft-delete consequence, then the ownership constraint. Nothing 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?

For a single-parameter mutation with an annotation covering destructiveness and no output schema, this covers what the agent needs to call it correctly. The only missing piece is post-delete recoverability/return behavior, which matters because the operation is destructive.

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

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

Schema coverage is 100% and the schema already defines message_id as a UUID, so the burden is low. The description still adds value by tying the id to mAYL_list, giving the agent an acquisition path that the schema's 'from mAYL_send or inbox' phrasing doesn't frame as a lookup step.

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 ('Delete'), resource ('the user's emails'), and the keying parameter, which separates it cleanly from mDM_delete, mIRC_delete, and mRAG_delete in the sibling list. It also names the companion tool that produces the id, so the agent knows exactly which resource family this operates on.

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 says to source message_id from mAYL_list, which effectively tells the agent to enumerate before deleting rather than guess an id. There is no explicit statement of when-not to use it (e.g., bulk cleanup vs a dedicated purge tool), so it stops short of full 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds the access constraint 'Owner-scoped' and pre-declares the returned fields (timestamp, device type, link URL), which is real context beyond the annotations. It does not say whether the event list is paginated or time-ordered, which is relevant for a timeline 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?

Three short sentences, front-loaded with what is returned, then the routing rule, then the access scope. Every clause carries information; no filler.

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

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

For a single-parameter read-only tool with full schema coverage and no output schema, the description supplies the return payload shape in prose and the access scope. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents message_id as a UUID sourced from mAYL_send or inbox. The description only restates that the id scopes to a single email, adding marginal meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource: 'Raw engagement timeline for one email (by message_id)' and enumerates the event types returned. It explicitly names the sibling it is not ('Use mAYL_stats for the rollup'), so an agent can distinguish it from mAYL_stats without inspecting either schema.

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

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

Gives an explicit when-to-use rule paired with the alternative: mAYL_stats for rollups, this tool for per-event detail. No inference required to pick the correct sibling.

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

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

readOnlyHint=true already declares the safety profile, and the description adds behavior beyond that: results are ordered newest-first, snippets are short previews rather than bodies, and pagination flows forward through a cursor. It does not state any auth/permission prerequisites, but for a read-only listing the disclosure is solid.

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 tight sentences, front-loaded with what is returned, then filtering, then paging, then the escalation path to mAYL_view. No filler and no sentence that could be dropped without losing an instruction.

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

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

With no output schema, the description compensates by enumerating the returned fields and explaining the cursor round-trip. For a three-parameter, read-only list tool this covers everything an agent needs to call it correctly and to know when to escalate to mAYL_view.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the enum meaning of inbound/outbound and the next_cursor-to-before handoff. The description largely restates those semantics rather than adding new ones; the baseline 3 applies when the schema carries the load.

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

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

States a specific verb and resource ('List the user's mailbox'), defines the scope ('their <userId>@mosadd.com inbox/outbox', newest-first), and enumerates what comes back (sender, subject, status, snippet). It also explicitly distinguishes itself from mAYL_view, which reads a full body, so an agent can pick between the two without opening a schema.

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

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

Gives concrete context: use the direction filter for received vs sent, omit it for both, and page older mail by passing next_cursor into `before`. It names the alternative for reading a full message (mAYL_view), but says nothing about other mail-adjacent siblings such as mAYL_agentbox_list or mAYL_events, nor when not to use 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?

With readOnlyHint already declared, the description adds useful scope information ('mailbox-wide', 'across the user's sent mail', 'Owner-scoped') and enumerates the aggregate fields returned, which is valuable since there is no output schema. It stops short of describing aggregation window (all-time vs. recent) or how owner scoping is determined.

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 resource and metric list front-loaded and the scoping note appended. The metric enumeration is long but each field earns its place because no output schema exists.

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?

It discloses the returned metric names, which compensates for the missing output schema, and states the ownership scope. However, with a near-identical sibling (mAYL_stats) available, the description leaves the key selection question — which stats tool to call — unresolved.

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; there is nothing for the description to disambiguate. The description correctly implies no filtering arguments are accepted.

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 resource and scope: a mailbox-wide engagement aggregate over the user's sent mail, with the exact metric names enumerated. It does not distinguish itself from the sibling mAYL_stats, which likely overlaps, so it falls short of a 5.

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

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

No indication of when to use this versus the sibling mAYL_stats or any other mAYL tool, and no exclusions or prerequisites. The agent must infer selection from the name alone.

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

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

Annotations already declare readOnlyHint, so the safe-read profile is covered; the description adds real value beyond that with ordering (newest first), scope (owner-scoped, all sent mail), the exact event types surfaced, and cursor-based pagination behavior. It does not mention volume/rate considerations that matter for a polling tool, but the essential traits are disclosed.

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, front-loaded with what the feed is before the polling instruction; every clause carries information. The parenthetical list of event types is slightly cluttered but earns its place by defining the feed's contents.

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 does the necessary work by naming the payload fields (subject, recipient, cursor) and the ordering. Enough to call the tool correctly; only minor gaps remain around error handling and event-shape details.

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

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

Schema coverage is 100% and both parameters are documented there, including the cursor-as-`since` polling trick. The description restates the same cursor convention without adding syntax, defaults, or edge-case behavior (e.g. what happens with an invalid or future timestamp), so it matches the baseline rather than exceeding it.

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: a recent engagement feed of opens, clicks, forwards and print/copy signals across ALL sent mail, newest first, with subject and recipient per event. An agent can immediately tell this is the notification/engagement stream rather than aggregate reporting (mAYL_stats/metrics) or raw audit events.

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

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

Gives explicit polling instructions — pass the returned `cursor` back as `since` to get only new activity — which is the primary usage pattern, and notes the owner scope. It never names a sibling tool or states when another tool would be the better choice.

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

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

Goes well beyond the destructiveHint annotation by stating the recall is immediate, what access is disabled, that restore:true reverses it, and an honest limitation: it cannot un-send or claw back already-read/copied/screenshotted content. This is exactly the behavioral context an agent needs for a destructive operation.

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

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

The effect and key limitation are front-loaded, the restore behavior is stated concisely, and the 'HONEST LIMIT' sentence earns its place by preventing overclaiming. No wasteful repetition.

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 destructive tool with no output schema, the description supplies the missing behavioral context: immediate effect, reversibility, owner scoping, and the critical limitation about prior access. An agent can invoke it correctly and set expectations.

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

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

Schema coverage is 100%, so both parameters are already well documented. The description reinforces that restore:true re-enables access, but adds no syntax or format detail beyond the schema's own descriptions.

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: revoke/recall secure-reader access for a sent email by message_id. It precisely describes the effect (recipient can no longer open via the reader link) and distinguishes the operation from deletion or un-send, making sibling selection 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?

Clearly explains the primary use case and the restore:true inverse operation, plus the owner-scoped prerequisite. It does not explicitly name alternatives such as mAYL_delete for permanent removal, so the guidance is strong but not fully comparative.

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

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

Annotations only declare readOnlyHint=false, so the description carries the burden and does it well: it discloses that tracking is ON by default, that force_reader replaces the body with a stub and routes the recipient through mosadd's secure reader, that auto_destruct expires the reader link, and that watermark surfaces in screenshots/prints. These are non-obvious side effects an agent must know before calling.

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

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

Front-loaded with purpose and sending identity, then grouped into recipients, body, and monitoring/legal options. The telegraphic parenthetical style is efficient, though the semicolon-chained clause on tracking is dense enough to risk misreading on a fast scan.

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 12-parameter mutation tool with no output schema, it covers the fields that have surprising behavior and leaves plain fields to the schema. It omits failure modes and any note on sender provisioning, which would be useful but are secondary.

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 already 83%, and the description still adds genuine meaning: it explains the runtime consequence of force_reader (stub + secure reader + print/copy/time-on-read observability), the true/string polymorphism of watermark, and the legal rationale for disclose_tracking. It leaves the delivery limits on to/cc/bcc to the schema, so 4 rather than 5.

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

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

States a specific verb and resource ('Send an email') and pins the sending identity to the user's own mosadd address, which implicitly separates it from mAYL_send_as_agent and from mDM_send/sms_send channels. It does not explicitly name the alternatives it is not, 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 real usage guidance for the body fields ('Pass body_text or body_html (or both)') and for the compliance options ('default on; set false for no tracking', 'recommended for GDPR/ePrivacy compliance'), but says nothing about when to choose this tool over sms_send, mDM_send, or mAYL_send_as_agent. Tool-selection guidance is left to inference.

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

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

Goes well beyond the readOnlyHint=false annotation: it discloses the provenance fields written (sent_by, agent_id, task_id) onto the record and audit trail, the auth mechanism (hub-claim JWT requiring MOSADD_API_KEY, verified with HUB_JWT_SECRET), and that body trust is never granted for provenance. The implementation-facing jargon is noise but the behavioral disclosure is unusually rich for a mutation tool.

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

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

Front-loaded with the core distinction and the provenance effect, then auth. Mostly earning its place, though the naming of the internal 'mp0st-send EF' and env-var secrets is implementation detail that costs a sentence without helping tool selection.

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 10-parameter mutation with no output schema and minimal annotations, the description covers identity/provenance and auth well but omits delivery behavior, return shape, failure modes, and most parameter meanings. An agent knows why to call it, but not fully what to expect back.

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 20% (10 params, only task_id and agent_id documented), so the description must compensate. It does clarify what agent_id and task_id become on the record (sent_by_agent_id, sent_by_task_id), but says nothing about tracking, reply_to, or the body_html vs body_text choice, leaving most parameters 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?

Specific verb + resource ('Send an email') with a precise qualifier: the send is attributed to the agent and provenance-stamped. It explicitly contrasts with the sibling mAYL_send ('sends as the user'), so an agent can distinguish the two without opening either schema.

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

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

The contrast with mAYL_send establishes the selection condition: use this when the mail must be visibly agent-originated for recipients/compliance. It does not spell out a 'do not use when' case or mention rate limits, but the routing signal to the alternative tool is clear.

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

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

Beyond the readOnlyHint annotation, the description discloses meaningful behavioral traits: opens/clicks are real (pixel + link-wrap) while forward detection is best-effort via IP-subnet diversity, and results are owner-scoped. This is exactly the kind of reliability caveat an agent needs before trusting the data.

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

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

A single dense sentence that front-loads the resource and then lists return fields with no filler. It is long but every clause (fields, reliability caveats, scoping) carries information.

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

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

With no output schema, the description compensates by enumerating the return fields and flagging which are reliable. Combined with the readOnlyHint annotation, an agent has enough to call it correctly; only explicit sibling routing is missing.

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

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

Schema coverage is 100% and the schema already explains message_id is a UUID from mAYL_send or inbox, so the description adds nothing new about the parameter. Baseline 3 applies when the schema does the work.

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

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

States a specific verb+resource: engagement summary for one sent email identified by message_id, then enumerates the exact fields returned. The 'one sent email (by message_id)' scoping implicitly separates it from aggregate siblings like mAYL_metrics and mAYL_list, 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?

The required message_id and the note that it comes 'from mAYL_send or inbox' implies the usage context. 'Owner-scoped' signals an access prerequisite, but there is no explicit when-to-use / when-not-to-use guidance or named alternative (e.g. vs mAYL_metrics for aggregates).

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

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

Annotations already declare readOnlyHint=true and the description's 'Read' is consistent with that. It adds that both body and metadata are returned, but says nothing about permissions, message-size limits, or what happens with an invalid/expired id — modest added value against an already-covered safety profile.

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

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

One front-loaded sentence that states verb, resource, return content, and lookup key with zero filler. Nothing could be cut 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?

For a one-parameter read tool with annotations covering safety and no output schema, the description covers what is returned (body + metadata) and how to address the message. Missing only edge-case behavior for invalid ids or large messages.

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

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

Schema coverage is 100% and the single parameter is documented with its origin ('UUID from mAYL_send or inbox'). The description repeats the name but adds no format or error semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('full body and metadata of an email') plus the lookup key ('by message_id'). This clearly distinguishes it from mAYL_list, though the description never names that sibling explicitly.

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

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

Usage is only implied: the emphasis on 'full body' suggests it is for retrieving content after a listing call, and the schema note says the id comes 'from mAYL_send or inbox'. There is no explicit when-to-use versus mAYL_list/mAYL_events guidance or stated preconditions.

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 only readOnlyHint=false available, the description usefully discloses that the call mutates state (answering) and returns join credentials with both a token and a media url, which is valuable since there is no output schema. It omits failure behavior (expired invite, already-answered call) and any permission requirements for issuing credentials.

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 compact sentences with no filler: the action and its input come first, the return value second. Every clause carries information the agent needs.

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

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

For a one-parameter tool with no output schema, the description covers the action, the id source, and the response shape, which is close to sufficient. What remains missing is edge-case behavior — what happens if the invite is stale or the call was already answered — which matters for a state-changing call tool.

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

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

Schema coverage is 100% for the single room_id, so the schema already carries the semantics; the description adds only the origin hint ('from the call_invite'). That hint also mildly conflicts with the schema, which attributes the invite to mDM_call_start rather than mDM_list, leaving the agent with two provenance stories.

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 ('Answer an incoming 1:1 call by its room_id') and names the return ('join credentials (token + media url) for the same room'). An agent can distinguish this from mDM_call_start and mDM_call_end without opening a schema.

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

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

The phrase 'incoming 1:1 call' establishes the triggering context, and pointing to the call_invite as the id source tells the agent where to obtain the input. It does not explicitly name mDM_call_start/mDM_call_end as alternatives or state what to do when no invite is pending, so it stops short of full 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?

Beyond the readOnlyHint=false annotation, the description adds meaningful behavior: the audio leg ends when clients disconnect, and passing `to` drops a `call_end` control message in the DM thread. It does not cover permissions or error conditions, but it provides useful operational context.

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

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

Two tight sentences, front-loaded with purpose and followed by the key behavioral nuance. No wasted wording.

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 three-parameter mutation tool with no output schema, the description covers the core action and optional message behavior adequately. The missing explanation of `thread_label` is a minor gap.

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

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

Schema coverage is 67%, with `room_id` and `to` already described in the schema. The description reinforces the `to` parameter but adds little beyond the schema and leaves `thread_label` undocumented, so baseline 3 is appropriate.

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

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

States a specific verb and resource: "End a 1:1 call," with the title clarifying it is a voice call. This clearly distinguishes it from sibling tools like mDM_call_start and mDM_call_answer.

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 makes the use case clear: end an existing 1:1 call. It also explains the optional `to` behavior, though it does not explicitly name alternatives or state when not to use 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?

Goes well beyond readOnlyHint=false by disclosing the side effects that matter: a room is created, join credentials (token + media url) come back, and a call_invite control message is injected into the DM thread — an externally visible effect on the recipient. That is exactly the context an agent needs before triggering a mutating, other-party-visible action.

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

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

Front-loaded with the core action and disambiguation first, then side effects, then the optional flag. No filler sentences; every clause carries either identity, exclusion, or outcome information.

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

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

Covers initiation, side effects, and the return payload (token + media url) despite there being no output schema, which is the bulk of what an agent needs. Minor gaps remain around failure modes, invite expiry, and whether a call can be upgraded to video after start.

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

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

Schema coverage is 100%, so 'to', 'video', and 'thread_label' are already documented with patterns and defaults. The description's 'Set video:true for video' merely restates the schema's boolean, adding no new semantics such as whether video can be upgraded mid-call.

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 ('Start a 1:1 real-time voice (or video) call with a contact') and immediately disambiguates it from the two lookalike transports, mTALK and mCALL. An agent can distinguish it from mDM_call_answer/mDM_call_end or mTALK_open without opening any schema.

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

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

Explicit exclusions ('NOT walkie-talkie mTALK, NOT PSTN mCALL') give a clear when-not, and the mention that the contact 'can answer' implies mDM_call_answer is the counterpart. It stops short of naming mDM_call_answer/mDM_call_end as the lifecycle siblings, so the routing is inferred 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 declare destructiveHint=true, which would otherwise suggest permanent removal; the description usefully corrects that by disclosing it is a server-side soft-delete and describing the observable effect (disappears from mDM_list for both parties). It omits reversibility/restore path, permission requirements, and error behavior when the message isn't yours.

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

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

A single tight sentence with no filler; the action and its constraint are front-loaded, and the soft-delete consequence follows as supporting detail.

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

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

For a one-parameter delete with no output schema and annotations covering the safety profile, this covers what the agent needs: which id, whose message, and what deletion actually means. Remaining gaps are minor (undo capability, failure modes).

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

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

Schema coverage is 100% and the single parameter is already documented as coming from mDM_list, so the description's '(from mDM_list)' adds provenance but no new syntax or format detail. Baseline 3 applies since the schema does the heavy lifting.

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 (delete), resource (direct message), and a scope constraint (one you sent) identified by message_id. An agent can immediately distinguish this from mDM_edit (modify) and mDM_list (read) without opening any schema.

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

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

Points to mDM_list as the source of valid message_ids, which is the key prerequisite for calling it. It also implicitly excludes deleting others' messages via 'you sent', but never names an alternative for editing or handling received messages, so it stops short of explicit 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?

With only destructiveHint=true in annotations, the description supplies the key non-obvious behavior: E2EE messages are refused because the ratchet is forward-only, and the correct fallback is delete-plus-send. It also implies only messages the agent sent are editable.

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 compact and front-loaded with the operation and ID mechanism. The E2EE NOTE is long but earns its place because it prevents a predictable failed edit and gives the correct alternative.

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?

It covers purpose, key constraints, and the E2EE workaround well enough for correct invocation. Because no output schema exists, it could say more about the return value or confirmation behavior, but the critical selection and invocation details are present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the roles of `to` and `message_id`, but adds no meaningful detail beyond the schema for `new_text` or the optional `thread_label`.

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: edit a direct message you sent, replacing its body by message_id. It also distinguishes this from mDM_delete and mDM_send by explicitly limiting editing to legacy non-E2EE 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?

It gives clear when-to-use guidance and an explicit exclusion: E2EE messages cannot be edited, and the agent should use mDM_delete plus mDM_send instead. The prerequisite that only legacy non-E2EE messages are editable is stated directly.

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?

Adds substantial behavior beyond the annotations: automatic E2E decryption, legacy plaintext passthrough, and the side effect that decoded incoming text is marked read while failed decryption never advances the read pointer. This also explains why readOnlyHint=false despite the tool being a read/list operation, resolving what would otherwise be a confusing annotation.

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

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

Four dense sentences, front-loaded with purpose then prerequisites then decryption/read-marking semantics. Nothing is redundant and every sentence carries distinct information.

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

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

With no output schema, it still covers the non-obvious parts: decryption, read-pointer advancement, and thread scoping. It does not describe pagination behavior (cursor/limit interplay) or roughly what a returned message looks like, which leaves a small gap for a 4-parameter list 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 75% and already documents contact_id, cursor, and thread_label. The description still adds value by identifying contact_id's provenance (identity_id from mDM_list_contacts) and clarifying thread_label as a filter over the conversation; only `limit` is left undocumented in both places, which is minor given its 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 and resource ('List recent direct messages with a specific contact') and implicitly distinguishes itself from mDM_list_contacts, which it names as the source of contact_id. An agent can tell immediately that this reads a conversation rather than enumerating contacts.

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 routes the agent to the prerequisite tool ('Pass contact_id as the identity_id from mDM_list_contacts') and states the optional narrowing by thread_label. It gives no explicit when-not-to-use guidance or alternatives for other message-listing paths, but for a read tool in this family the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds genuine value by disclosing the returned fields and the contact states (pending, accepted, blocked), but says nothing about pagination behavior despite a limit capped at 500.

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

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

Two tight sentences, front-loaded with the purpose and followed by return values. Nothing is wasted, though the second sentence could have been spent on the undocumented limit parameter instead.

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, describing the return fields and contact states is exactly the right use of space, so the response shape is covered. However, the single input parameter and the truncation/pagination behavior remain unexplained, leaving an agent unable to reason about partial results.

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

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

There is one parameter (limit) with 0% schema description coverage, so the description carries the full burden of explaining it — yet the description never mentions the limit, its default of 100, or what happens when more contacts exist. The gap is unmitigated.

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

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

States a specific verb and resource (list the user's mosadd contacts) and enumerates the returned fields, so an agent knows exactly what it gets back. It also names the downstream tools that consume identity_id, which helps separate it from mDM_list, though it doesn't clarify what mDM_list itself returns.

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: the description signals this is the way to obtain identity_id for mDM_send / mDM_list, but never says when to call this versus mDM_list_my_agents or other listing tools. No exclusions or prerequisites 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=true, so the description is not needed to establish safety; instead it adds real substance by disclosing result scope ("every live agent owned by the account behind this key") and the exact fields returned (identity id, mosADD address, display name). It omits pagination or empty-result behavior, so it is strong rather than exhaustive.

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

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

Two sentences, both front-loaded with the highest-value information: what the list contains, then when to call it. No restatement of the tool name, no filler, and the sibling reference is packed into the first clause rather than a separate sentence.

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

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

With no parameters, no output schema and only a readOnlyHint annotation, the description carries everything an agent needs: ownership scope, liveness, the three returned fields, and the follow-up call it enables. Nothing required to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. The mention of identity id and mosADD address is useful context for the *output*, but it does not pretend to describe inputs.

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

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

States a specific verb and resource ("List the agents you are allowed to speak as") and immediately ties the resource to the sibling it feeds, mDM_send_as_agent. An agent can distinguish this from mDM_list, mDM_list_contacts and mAYL_list without opening any schema, because the description scopes it to agents owned by the key's account.

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

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

Gives an explicit triggering condition: "Call this first when you are unsure which agent identity you hold," which is actionable ordering guidance relative to mDM_send_as_agent. It stops short of naming when *not* to call it (e.g. if the identity id is already known or comes from config), so it is clear context rather than full when/when-not coverage.

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

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

Annotations only supply readOnlyHint=false, so the description carries most of the burden and delivers: it's a publish/mutation with a social side effect (others become able to initiate conversations), it is meant to be run once rather than repeatedly, and it shares the message transport including off-grid radio. It doesn't state permissions, failure modes, or whether re-running is idempotent or revokes prior bundles.

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

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

Three short sentences, front-loaded with the action and effect, then the when-to-run guidance, then the transport caveat. Every sentence adds distinct information with no restatement of the title or 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?

With no parameters, no output schema, and minimal annotations, the description covers the essentials: what it publishes, why, how often, and that it works off-grid. The remaining gap is operational detail — what happens on failure, whether an existing bundle is replaced, and any auth prerequisite beyond sign-in.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly implies no arguments are required, matching the empty schema.

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

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

States a specific verb and resource ('Publish your mDM prekey bundle') and the user-visible outcome ('so other people can start an end-to-end-encrypted conversation with you'). No sibling tool in the visible list performs this function, and the description makes that unique role 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?

Gives an explicit trigger and cadence: 'Run this once after sign-in (and to replenish one-time prekeys).' That is concrete when-to-run guidance rather than vague context. It doesn't enumerate exclusions or point at alternatives, but no sibling is a plausible substitute here.

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 readOnlyHint=false annotation already signals mutation, and the description adds the request/whitelist context. However, it does not describe consequences of accept versus reject, whether acceptance adds the contact to the whitelist, or whether the request is consumed.

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 purpose and scoping condition are immediately visible.

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

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

For a two-parameter mutation tool with no output schema, the description covers purpose and context but omits behavioral outcomes and parameter usage details. It is minimally adequate but leaves meaningful 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%, so the description must compensate. It conveys the accept/reject action and the concept of an incoming request, which partially maps to both parameters, but it does not explain request_id sourcing, format, or requiredness.

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 pair (accept/reject) and resource (incoming DM request) with a clear scoping condition (contact not yet whitelisted). An agent can distinguish it from send-oriented mDM_* siblings, though it does not explicitly name an alternative 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?

Gives clear context for when to use it: an incoming DM request from a non-whitelisted contact. It does not state when not to use it or name alternatives such as mIRC_approve_request/reject_request for IRC contexts.

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

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

Annotations only supply readOnlyHint=false; the description carries the real behavioral burden, disclosing that fleet-line/self conversations degrade to plaintext with a concrete result shape (`encrypted: false, reason: "fleet_plaintext"`) and that true E2E requires published recipient keys. That is exactly the non-obvious side effect an agent needs before sending.

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

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

Front-loads the action and the encryption rule, then the addressing rule, then the thread feature — a sensible ordering. Some clauses ('exactly like the mosadd app', 'unlike WhatsApp/Telegram') are comparative color rather than operative instruction, plus heavy capitalization, which trims it below full marks.

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

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

With no output schema, the description usefully sketches the result field for the plaintext case and covers the encryption precondition, so an agent can call it correctly. It omits delivery/failure behavior (rate limits, what happens if keys are missing) and anything about attachments, 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 100%, so baseline is 3; the description goes beyond it by explaining what thread_label actually does (named thread per contact, multiple threads allowed, default when omitted) and by reinforcing that `to` is an identity_id requiring lookup. The reply_to_id parameter is left entirely to the schema.

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

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

States a specific verb and resource ('Send a direct message via mosadd mDM') and immediately clarifies the encryption scope that distinguishes this from mDM_send_unencrypted and mDM_send_as_agent. It never names those siblings explicitly, so the differentiation is inferential 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?

Gives clear pre-call guidance: resolve the recipient via mDM_list_contacts and ensure the recipient has published keys before expecting encryption. It does not state when to prefer mDM_send_as_agent, mDM_send_unencrypted, or mDM_send_file instead, which are the closest alternatives in the sibling list.

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

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

Annotations only declare readOnlyHint=false, so the description carries the behavioral burden and does so well: server-side ownership verification, refusal conditions, the person-only recipient constraint, and the default recipient (key's owner). This is exactly the auth-and-limits context annotations don't provide.

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

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

Content is front-loaded with the key distinction and the when-to-use clause comes second; every sentence carries information. It is on the longer side for a 4-parameter tool, but no sentence is padding.

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

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

With no output schema, the description could say what a successful send returns (message id, thread reference), but the ownership checks, defaults, and constraints an agent needs to call it correctly are all present. Minor gap only.

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

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

Schema coverage is 100%, so parameters are already documented; the description reinforces the `to` default ('the common case is an agent reporting to its owner') and clarifies that `agent` accepts mosADD address, identity id, or display name. Mostly redundant with the schema, so not a 5.

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

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

States a specific verb+resource (send a DM as one of your own agents) and immediately contrasts with the default behavior of mDM_send, where messages appear to come from the owner. An agent can distinguish this from mDM_send and mAYL_send_as_agent without opening any schema.

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

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

Explicitly names the situation that selects this tool ('when you are an agent runtime connected with your owner's key') and the consequence of not using it. It also lists exclusions: speaking as someone else's agent, as another person, or agent-to-agent DMs are refused.

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

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

Goes beyond readOnlyHint=false by disclosing the processing pipeline (bytes staged in Storage before send) and honestly flagging that the E2EE seal is not yet implemented — a material caveat for a messaging tool. It stops short of stating what the send returns or any per-call limits 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?

Three short sentences, front-loaded with the action, then the pipeline, then the caveat. No filler; each 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?

No output schema exists, so the description should indicate what a successful send returns (message id, storage ref) or failure modes, and it doesn't. The SCAFFOLD/E2EE caveat and the schema's 86% coverage cover most call mechanics, leaving the return contract as the main gap.

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

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

Schema description coverage is 86%, so the schema already documents recipient lookup, MIME examples, base64/data-URL handling, and the ~15 MB decoded cap. The description adds only the conceptual 'base64 bytes → Storage' flow and no new parameter meaning, 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 concrete verb and resource — 'Send a FILE to a contact as a first-class mDM `file` message' — plus the delivery path (base64 → Storage → attachment). It implicitly separates this from mDM_send (text) and mDM_send_voice, 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 phrase 'as a first-class mDM `file` message' hints at when to pick this over mDM_send or mDM_send_unencrypted, but there is no explicit when-to-use/when-not-to-use statement or named alternative. Prerequisite (finding the recipient via mDM_list_contacts) is only stated in the schema, not the description.

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

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

Annotations only declare readOnlyHint=false, so the description carries most of the burden and does so: the message is never encrypted, this path is mandatory for fleet/King traffic, and the choice is permanent. It does not describe what is returned or whether delivery can be revoked or fails, which keeps it from a 5.

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

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

The mandatory-routing rule is front-loaded and the alternative tool is mentioned last, which is the right ordering. It repeats the unencrypted idea twice ('plain text, never encrypted' then 'in the clear'), a minor redundancy in an otherwise dense passage.

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

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

For a 4-parameter mutation with no output schema, the description covers routing policy, recipient id sourcing, permanence, and thread behavior. The main gap is that it never says what a successful send returns (e.g., a message id) or how failures surface.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates that `to` is a mosadd identity_id found via mDM_list_contacts and that thread_label creates a named thread, which is essentially the same information the schema already provides, adding little beyond it.

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 a direct message) plus the defining constraint: plain text, never encrypted. It explicitly separates itself from the sibling mDM_send by naming the condition under which mDM_send would take the same path, so an agent can distinguish the two without opening either schema.

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

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

Gives concrete routing rules: every agent line writing to the King, to another line, or to itself must use this tool, and the choice is permanent. It also names mDM_list_contacts as the prerequisite for obtaining `to`. It stops short of an explicit 'use mDM_send instead when no fleet line is a party', leaving that inference to the reader.

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

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

Annotations only declare readOnlyHint=false, so the description carries the disclosure burden and does it well — it states the bytes are uploaded to Storage unsealed until the seal step ships, which is critical safety context. It does not cover permissions, size-limit failure behavior, or what the response returns, but the encryption caveat is genuinely valuable.

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 tight sentences, front-loaded with the core action and scope, then mechanism, then the caveat. The 'TODO Lane A' internal scaffolding reference is noise for an agent but small.

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

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

For a mutation tool with no output schema, the description covers purpose, mechanism, and the unsealed-upload risk. It omits return/idempotency information and any sibling disambiguation, which keeps it short of 5.

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 86%, so the schema already documents every parameter (~15 MB decoded max, mime examples, thread_label semantics). The description only echoes 'pass audio bytes as base64', adding nothing beyond the schema — baseline 3 is correct.

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

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

States a specific verb+resource ('Send a VOICE note ... as a first-class mDM `voice` message, not a URL stub') and clarifies the mechanism (base64 upload to Storage, posted via message-send). It never distinguishes itself from the ambiguous sibling `mDM_voice_note`, so an agent cannot fully route between them from this text alone.

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 when-to-use / when-not guidance and no alternatives are named, despite the existence of `mDM_voice_note`, `mDM_send_file`, and `mDM_send_unencrypted` as obviously relevant siblings. The SCAFFOLD note is a caveat, not 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 only declare readOnlyHint=false; the description adds the important behavioral facts that this is asynchronous, that it is not a live call, and that the audio must already be uploaded (no upload step, no recording). It does not say whether deletion/edit of the note is possible afterwards or whether encryption applies (note the sibling mDM_send_unencrypted), which would be useful for 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?

Two sentences, both front-loaded with the action and the mechanism; no filler and the usage cue comes after the definition in the right order.

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

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

No output schema and only 5 params, so the description covers the important ground: async nature, message type, pre-uploaded asset. Missing is any indication of failure behavior or what `thread_label` does, which is the one parameter unexplained anywhere.

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 80%, so baseline is 3. The description reinforces the audio_url prerequisite ('already-uploaded audio clip'), which is already in the schema, and adds nothing about `to`, `mime`, `duration_ms`, or the otherwise-undocumented `thread_label`.

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

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

States a specific verb+resource ('Send an asynchronous voice note to a contact') and pins down the mechanism: posts a `voice_note` message in the DM thread from a pre-uploaded clip. It does not, however, differentiate itself from the near-identical sibling mDM_send_voice, leaving the agent to guess which of the two to use.

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?

'Use for fire-and-forget voice instead of a live call' gives a clear when-to-use and implicitly names the alternative (mDM_call_start). The closest alternative, mDM_send_voice, is never mentioned, so the routing guidance is incomplete at the most ambiguous decision point.

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 only readOnlyHint=false provided, the description carries most of the burden and does so well: it discloses the privilege requirement, the state mutation's effect, and the exact failure mode ("wrapped_group_key required") the backend raises. It stops short of covering idempotency, what happens to the requester on success, 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?

Three sentences, front-loaded with the action and state transition, then permissions, then the non-obvious parameter constraint. Nothing is padding and the ordering matches how an agent needs the information.

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

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

For a mutating tool with no output schema and minimal annotations, the description covers authority, state effect, mandatory inputs, and failure mode. It omits what a successful call returns and whether re-approving an already-active member errors or is a no-op, which an agent would want before retrying.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real interpretive value by asserting that wrapped_group_key — which is not in the required array — is effectively always required, resolving the ambiguity between the schema's optional marking and actual backend behavior. It also clarifies the key is wrapped to the approved member's identity key.

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

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

States a specific verb (approve) plus resource (pending access request) and pins the exact state transition (state=requested → active). An agent can immediately distinguish this from mIRC_reject_request or mIRC_join without opening a schema.

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

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

"Admins / moderators / owner only" gives an explicit eligibility gate, and the sentence explaining that access requests only exist on non-open channels tells the agent the condition under which wrapped_group_key is mandatory. It never names mIRC_reject_request as the counter-action, so the exclusion path is left implicit.

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

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

Annotations only flag destructiveHint=true; the description adds two pieces of real behavioral context the agent cannot get elsewhere – that the effect persists until mIRC_unban and that admin+ privileges are required. It still omits whether the banned member is removed from the channel or can rejoin, and whether ban state is visible to others.

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

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

Three short sentences, zero filler, with the action front-loaded and the permanence/reversal constraint plus permission gate following in priority order.

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

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

For a two-parameter mutation with no output schema, the description covers action, durability, reversal path, and authorization. Slightly incomplete on post-ban member state and error behavior, but nothing critical to invoking it is missing.

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

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

Schema description coverage is 100% and both parameters document their source (mIRC_list/mIRC_create, mDM_list_contacts/radar logs). The description adds only the implication that identity_id identifies the 'member'; no additional format or selection guidance. 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 ('Ban a member from the channel') and names the sibling that reverses it, which separates it from mIRC_kick and mIRC_unban. It stops short of stating what banning actually does to the member (removal, message visibility), so it is clear but not maximally precise.

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 'permanent until you call mIRC_unban' clause implies this is the durable-moderation choice, but the description never contrasts it with mIRC_kick or mIRC_set_role, so the agent must infer which moderation tool fits. The admin+ prerequisite is a useful gate but not 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?

The description discloses substantial behavior beyond the readOnlyHint=false annotation: voice/PTT/live are server-relayed rather than E2EE, password/private channels require wrapped_group_key, open channels ignore it, and non-open requests fail without it. It also explains invite fan-out behavior, auto-join for own agents, per-agent failure reporting, and the 20/min invite rate limit.

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

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

The description is front-loaded with the core action and remains dense with operationally relevant caveats. It is long but mostly justified by the tool's complexity, though several clauses restate access_mode, discoverable, and capabilities already documented in the schema.

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

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

For a complex eight-parameter creation tool with no output schema, the description covers access modes, encryption expectations, required group-key handling, discoverability, invite behavior, and rate limits. An agent has enough context to invoke it correctly even without additional return-shape documentation.

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?

Although schema coverage is 100%, the description adds cross-parameter meaning: password/private channels need wrapped_group_key while open channels ignore it, discoverable is honored only for open channels, and invite_agents requires identity ids from mDM_list_my_agents. It also explains that invite_agents fan-out cannot carry per-agent wrapped_group_key on password/private channels.

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 first sentence states a specific verb and resource: create a new persistent channel, with a Discord/Slack analogy. It also names related tools such as mIRC_invite, mIRC_discover, mIRC_post_message, and mDM_list_my_agents, making its role distinguishable from sibling 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?

The description gives clear context for choosing access modes, enabling capabilities, and when discoverable applies. It also says to pass invite_agents now or call mIRC_invite afterwards, which provides an explicit alternative path, though it does not state when not to use this tool versus mIRC_join or other siblings.

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 supply destructiveHint=true, and the description adds real value beyond that: the cascade removal of members and an owner-only authorization requirement. It stops short of warning about irreversibility or what happens to message history, leaving some behavioral 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?

Two short sentences front-loaded with the action and its blast radius, then the permission gate. Every clause carries information.

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

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

For a one-parameter destructive tool with no output schema, the description covers the action, side effects, and authorization. Missing only secondary consequences such as what happens to channel history or whether deletion is recoverable.

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

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

There is a single parameter with 100% schema description coverage, including a pointer to mIRC_list for discovery. The description adds no semantics about channel_id beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Delete a channel') and adds the important scope detail that members are cascade-removed. It does not explicitly contrast with siblings like mIRC_leave or mIRC_kick, so the distinction from those tools is left implicit.

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?

'Owner only' states a permission prerequisite, which is genuinely useful context for selecting the tool. However, there is no guidance on when to delete versus leaving (mIRC_leave) or kicking members (mIRC_kick), so 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?

Annotations only declare readOnlyHint=true; the description adds real behavioral context on top: the discoverable=true opt-in gate, the hard exclusion of private/password/partner channels, the exact response shape, and that results are paginated. This is well beyond what the structured fields convey.

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

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

Two tight sentences, front-loaded with the scope that most affects selection (PUBLIC / opted-in), then eligibility exclusions and the join hand-off. Zero filler despite packing in return fields and pagination.

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

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

With no output schema, the description supplies the return field list itself, and with only a readOnlyHint annotation it supplies the exclusion rules and pagination behavior. An agent has everything needed to call this and interpret the result.

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

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

Schema coverage is only 33% – only q carries a schema description, while limit and offset are undocumented beyond name/min/max. The description partially compensates by saying 'Filter by name with q; paginated', but leaves limit/offset semantics and defaults to inference from the schema.

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

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

States a specific verb and resource ('Browse the PUBLIC channel DIRECTORY') plus the eligibility rule (owners opted in, discoverable=true) and enumerates the returned fields. It also sharply distinguishes itself from the private-channel tools by declaring that private/password/partner channels never appear, so an agent can tell exactly what this returns.

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 next-step route: 'Join a result with mIRC_join (open = one-click)', which tells the agent what this tool feeds into. It doesn't explicitly contrast against the sibling mIRC_list or state when not to use it, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true and supply a title, so the safety profile is covered and the bar is lower. The description adds nothing beyond that — it doesn't say what fields "full details" includes or what happens when the id is unknown — but it also contradicts nothing.

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 resource scope front-loaded and zero filler. Nothing is wasted or 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?

The schema and annotations make the call mechanics unambiguous, but with no output schema the description's phrase "full details" is the only clue to the return payload and it stays vague. Adequate for invocation, thin for interpreting the result.

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

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

Schema coverage is 100% and the single channel_id parameter is fully documented in the schema, including its UUID format and the pointer to mIRC_list. The description only reinforces "by id", so baseline 3 is appropriate.

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

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

States a specific verb and resource ("Get full details of a single channel") and scopes it to one item by id, which implicitly separates it from the sibling list tool mIRC_list. It doesn't explicitly name which sibling to prefer, but the singular/plural scope distinction is clear enough to select correctly.

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

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

The description contains no when-to-use or when-not-to-use guidance and never mentions mIRC_list, mIRC_discover, or mIRC_list_messages as alternatives. The only routing hint ("Use mIRC_list to discover available channels") lives in the schema's channel_id description, not in the tool description itself.

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