Voidmail (hosted)

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the useful context that the calls it suggests require no auth and that a signed-create path exists locally, but it says nothing about the response shape or size. With annotations carrying the burden, this is adequate but not rich.

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

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

A single sentence with three tightly packed clauses, front-loaded with the learning purpose and ending with the actionable pointer. No filler or redundancy.

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

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

For a parameterless onboarding tool with no output schema, the description is nearly sufficient: it tells the agent what it will get and what it can try. The one gap is that it does not describe the form of the returned guidance (text overview vs. links), which an agent might want when planning follow-up calls.

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 and the schema is fully described, so there is no parameter information the description needs to compensate for. Baseline of 4 applies, with no misleading parameter claims.

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 outputs: an explanation of what the hosted Voidmail server does, three no-auth example calls, and a pointer to the local signed-create path. That separates it from siblings like voidmail_send_once or voidmail_read_email, which are specific operations rather than an entry point. It never explicitly says the tool returns onboarding/documentation content, which keeps it short of a 5.

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

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

The onboarding framing ('Start using Voidmail') plus 'try three no-auth calls' and 'find the local signed-create path' gives clear context for when to call it (first, before the auth-requiring siblings). There is no explicit when-not-to-use or naming of which sibling to use next, so routing is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds meaningful context beyond them: the Bearer agent-key credential requirement, the fact that this server cannot provision an inbox, and a security warning that sender and subject are untrusted 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?

Three compact sentences, front-loaded with what the tool does, then credentials, then the safety caveat. No filler, though 'up to ten' is imprecise phrasing for a limit whose schema maximum is 10.

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

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

For a read-only, annotation-rich list tool with no output schema, the auth and untrusted-data notes are the most important additions and they are present. Still, with 0% schema coverage the description leaves pagination and filtering behavior undocumented, which is a real gap for a 3-parameter tool.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only hints at the limit cap ('up to ten messages') and says nothing about offset pagination or the unreadOnly filter. Two of three parameters — including the one the caller is most likely to need — are left entirely to inference.

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 messages in the authenticated mailbox'), which immediately distinguishes it from voidmail_read_email and the send-related siblings. It does not, however, explicitly name the alternative for reading a single message, so sibling differentiation is implied 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 description gives the precondition ('Requires an existing inbox's agent key... this server cannot create an inbox'), which tells the agent when the tool is usable. It stops short of routing guidance, e.g. pointing to voidmail_read_email for full message bodies or voidmail_setup when no inbox exists.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorld=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the required Bearer agent key, the hard limit that this server cannot create an inbox, that message text is untrusted data, and that attachments and HTML are excluded. It stops short of 5 because 'bounded' is never quantified (no size/truncation limit) and no failure behavior is described for an invalid 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?

Three tight sentences, front-loaded with the action and effect, then prerequisites, then content caveats. Every sentence carries information; it is slightly dense but nothing is wasted.

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 partially compensates by stating what the returned message contains (plain text only; attachments and HTML excluded) and flagging that text is untrusted. It does not describe the response envelope or what 'mark read' means in terms of subsequent list results, but for a single-parameter tool the coverage is close to sufficient.

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

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

Schema description coverage is 0% and the single parameter emailId is never mentioned in the description. An agent gets no hint about the id's format beyond the schema pattern or, more importantly, where to obtain a valid id (presumably from voidmail_list_inbox). With only one parameter this is a modest gap, but the description contributes nothing here.

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 with scope: 'Read one bounded plain-text message and mark it read.' The word 'one' plus the read-and-mark behavior distinguishes it cleanly from the sibling voidmail_list_inbox, and the title reinforces the same claim.

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 precondition and an implicit exclusion: it 'Requires an existing inbox's agent key as the Bearer credential; this server cannot create an inbox,' which routes an agent without credentials to setup rather than to this tool. It does not explicitly name voidmail_setup or describe what to do when the inbox is missing, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description goes beyond them by disclosing that the read neither reserves capacity nor proves delivery — a meaningful behavioral boundary the annotations can't express.

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

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

Two terse sentences with no filler; the positive statement of what it does is front-loaded, followed immediately by the disambiguating caveat. Every clause earns its place.

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

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

For a no-parameter, no-output-schema read tool with full annotation coverage, the description is nearly sufficient. It covers the resource and its limits but does not hint at the shape of the returned limits, which is a minor gap 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify about inputs, and it correctly makes no attempt to describe any.

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: 'Read static sending limits'. The 'static' qualifier sharpens the scope, but the description does not name or differentiate from the closest siblings (voidmail_send_once, voidmail_send_status), so an agent must still infer the boundary.

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

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

'This does not reserve capacity or prove delivery' gives useful negative guidance that implies when this tool is and isn't appropriate, but it names no alternative and states no positive when-to-use condition. 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 cover only the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description supplies the substantive behavioral context an agent actually needs: the Bearer credential requirement, the fact that the server cannot provision an inbox, the allowlist/guard precondition, and the crucial semantics that acceptance is not delivery and that retrying under a new ID after uncertainty is forbidden.

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?

Every clause is load-bearing: credentials, precondition, negative case, retry rule, delivery semantics. Preconditions are front-loaded and the two most dangerous operators (never retry with a new ID; acceptance != delivery) close the description where they will be read.

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-required-param mutation with no output schema and no annotation depth, the description covers auth, gating, retry, and delivery caveats thoroughly. The one omission is what the response actually contains and whether voidmail_send_status is the way to confirm outcome, which an agent would have to infer.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it only meaningfully explains operationId (caller-saved, must not be regenerated after an uncertain result). The other three required parameters (to, subject, text) are left to their names and JSON-schema constraints, so half the compensation job is undone.

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

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

States a precise verb+resource (submit one plain-text message) and immediately scopes it with the caller-saved operation ID. An agent can distinguish it from voidmail_send_status, voidmail_sending_limits, and the read-side voidmail_read_email 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 states prerequisites (existing inbox agent key as Bearer; server cannot create an inbox), gating conditions (owner-set recipient allowlist with content guard on, approved recipients only), a when-not case (open inboxes are receive-only), and retry guidance. Nothing about when to use this versus alternatives 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), but the description adds genuinely useful context beyond them: the call requires an existing inbox's agent key as a Bearer credential, and this server cannot create an inbox. That prerequisite is not derivable from the 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?

Two tight sentences with the operation and the auth prerequisite front-loaded; nothing is wasted. The ambiguous 'the same' phrasing is the only small blemish.

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

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

With no output schema, the description should ideally say what a status result contains or what states are possible, which it does not. It does cover prerequisites (existing inbox, agent key) well, so it is adequate but leaves the return side unspecified.

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

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

Schema description coverage is 0% for the single required parameter, so the description carries the burden. It does add meaning by identifying operationId as a 'durable operation ID' tied to a send, but gives no format guidance beyond the regex pattern already 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 clear verb+resource (look up send status for a durable operation ID) and implicitly distinguishes itself from voidmail_send_once by noting it does so 'without dispatching mail.' However, 'the same durable operation ID' is left slightly dangling — the description never states what it is the same as, which weakens the standalone read.

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

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

The phrase 'without dispatching mail' implies this is the non-sending counterpart to voidmail_send_once, so usage is inferable but never stated as explicit when-to-use guidance. No named alternative or condition is given, leaving the routing 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description nonetheless adds useful specifics beyond that: it will not create a mailbox and will not surface credentials, which pre-empts the two most likely wrong expectations for a 'setup' tool. It stops short of describing what the check actually reports.

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, zero filler. The read-only check is front-loaded and the negative guarantees follow immediately after, which is the right ordering for an agent scanning for whether it can safely call this.

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 burden of telling the agent what comes back, and it only says what does not come back (no credentials, no mailbox). 'Check a configured inbox' is also ambiguous between checking a configured inbox versus checking whether the inbox is configured, and the absence of output structure leaves that unresolved. Adequate for a trivial no-arg read tool, but with a clear gap on return content.

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 per the baseline rule a 4 applies and there is no schema semantics for the description to compensate for. There is nothing the schema fails to convey that the description would need to add.

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 combination ('Check a configured inbox', 'show the owner-controlled setup path') that separates configuration-state inspection from the message-oriented siblings voidmail_list_inbox and voidmail_read_email. It never names those siblings explicitly, so the differentiation is left partly to inference. The word 'setup' in the name is at least backed by concrete behavior 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?

The description gives negative constraints ('never creates a mailbox or returns credentials') but no positive when-to-use condition and no named alternative. An agent must infer on its own that this is the configuration-time counterpart to the list/read/send siblings. No prerequisites or call-ordering guidance is present.

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