Agentline NZ: email inboxes for AI assistants

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

Annotations only cover the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds a genuinely important behavior not in structured data: the secret is returned exactly once and must be stored immediately. It still says nothing about required permissions or how many keys can exist.

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

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

Two short sentences, no filler. The core action leads and the critical one-time-secret warning follows immediately; 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 simple one-parameter creation tool with no output schema, the description covers the most failure-prone aspect (the secret is shown once). It is close to complete, though it omits what the created key can do (scopes/permissions) and that the key lives until revoked.

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?

With a single parameter at 100% schema description coverage, the schema already documents "name" with an example label. The description adds no syntax, format, or constraint detail beyond that, 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 states a specific verb+resource ("Create an API key") and adds scope ("for another agent or script"), which clearly separates it from the sibling read/list tools. It doesn't explicitly name the alternatives (list_api_keys, revoke_api_key), but the action 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?

"For another agent or script" implies the intended usage context, but there is no explicit when-to-use vs when-not, no prerequisites (e.g. owner verification), and no mention of the sibling revoke_api_key for lifecycle management. Usage 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 already establish the safety profile (readOnlyHint, idempotentHint, non-destructive, non-open-world), so the bar is lower. The description adds real value by disclosing what is returned — plan, subscription status, trial end date and allowances — which is otherwise unavailable since no output schema exists. It stops short of stating return format or freshness.

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

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

A single, front-loaded sentence with zero filler. The most important information (this shows billing status) leads, and the enumerated contents follow compactly.

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

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

With no input parameters and no output schema, the description is the sole carrier of return-value information, and it does enumerate the key fields. What remains thin is guidance on related billing tools, which matters given the three other billing-adjacent siblings.

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 rubric this scores at the baseline of 4. There is nothing for the description to disambiguate.

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 ('Show') and enumerates the exact resource contents: plan, subscription status, trial end date, allowances. An agent can immediately tell this apart from get_billing_portal_link (a redirect link) or get_checkout_link (a purchase flow), though the description never names those siblings to reinforce the distinction.

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

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

No when-to-use, when-not-to-use, or prerequisite guidance is given. The description never mentions the closely related get_billing_portal_link or get_checkout_link, so the agent must infer from the resource name alone which billing tool to pick.

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 the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true), and the description adds real side-effect context beyond them: the link is emailed to the owner, and any plan change or cancellation made in the next 24 hours is also emailed. That is valuable behavioral disclosure for an external-system write.

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 core action and followed by the side-effect detail. Both sentences carry information, though the 24-hour clause could be trimmed for some readers.

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 annotations already carrying the safety profile, the description covers what is created, who it targets, and the email side effects. Nothing an agent needs to call 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?

There are zero parameters and schema coverage is 100%, so the baseline of 4 applies; the description adds actor scoping (the link targets 'the owner') without needing to document any 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 gives a specific verb and resource: 'Create a Stripe Customer Portal link' plus the concrete capabilities it exposes (update card, switch plan, cancel). It clearly separates this from the other billing siblings by naming the Stripe Customer Portal, though it never explicitly contrasts with get_billing or get_checkout_link.

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 through the described capabilities (owner card/plan management); there is no explicit when-to-use or when-not-to-use guidance, nor any routing against the closely related get_billing and get_checkout_link siblings. An agent can infer the context but is not told.

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 and openWorldHint=true, so side effects are expected. The description adds genuinely useful context beyond that: the link is emailed to the owner as well as returned, and the agent cannot complete payment itself. Its non-idempotent nature (a new link per call) is not spelled out, which keeps 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?

Two dense sentences with no filler. The action, the side effect (email), the return value, and the agent's limitation are all 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?

For a single-parameter tool with no output schema, the description covers the essentials: what is created, where the link goes, what is returned, and the agent's inability to pay. It could still mention prerequisites (owner verification) or that repeated calls mint new links, but nothing critical to a correct call 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?

One parameter with 0% schema description coverage, so the description carries the burden. It references 'a plan' and eligibility for the 7-day free trial, which adds a little meaning, but it does not explain the starter/pro enum values or what selecting each implies. Marginal value over the self-documenting enum.

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: creates a Stripe Checkout link tied to a plan, with trial eligibility noted. It is clearly distinguishable from most siblings, though it never explicitly contrasts itself with the similar get_billing_portal_link, which is the nearest alternative.

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

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

Usage is implied by the purpose (start a plan/subscription for the owner) but there is no explicit when-to-use or when-not guidance, nor any statement of prerequisites such as owner verification. The agent must infer the trigger condition.

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 and closed-world, so the safety profile is covered. The description adds value the annotations cannot: it is the only source for what is returned (address, plan, allowance) since there is no output schema, plus a recommended call order. No auth or rate-limit detail is given.

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

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

Three short sentences, no filler, with the actionable ordering cue ('Use this first') front-loaded before the payload and the follow-up use case. 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 zero-parameter, read-only tool with full annotation coverage and no output schema, the description supplies both the return contents and the usage trigger. It is essentially complete, with only marginal omissions such as what the plan values look like or how many addresses may appear.

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 no parameter surface for the description to clarify or obscure.

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 and enumerates the returned payload ('@agentline.nz email address(es), plan and remaining email allowance'), which is far more specific than the title alone. It does not, however, explicitly differentiate itself from plausible siblings such as get_profile or get_my_number, so sibling differentiation is left to 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?

'Use this first' gives explicit ordering guidance, and the second sentence names a concrete use case (services that verify the agent by email). It stops short of naming an alternative tool or stating when-not-to-use, which a 5 would require.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful legacy/deprecation context but does not disclose additional runtime traits beyond that.

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 convey the alias status, backward-compatibility purpose, and preferred replacement. The key guidance is front-loaded with no wasted text.

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 deprecated alias with no parameters and strong annotations, the description is nearly complete. It could still say more about the return value, but it appropriately redirects agents to get_my_inbox for actual use.

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 and schema coverage is complete, so the baseline is 4. The description appropriately does not discuss parameters because none exist.

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 clearly identifies the tool as a legacy alias for get_my_inbox and states that it returns the same result. It does not independently describe the actual return content, relying on the sibling tool and title instead.

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 says the tool is kept for older setups and directs agents to use get_my_inbox instead. This gives clear when-not-to-use guidance and names the correct alternative.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description's only added value is clarifying that the resource is scoped to the calling credentials, which explains why no identifier is needed.

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 and the key scope constraint front-loaded. It is spare to the point of being minimal, 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 an output schema present, return values need no explanation, and full annotations carry the behavioral profile. For a zero-parameter read tool the description is sufficient, though it could note it is the entry point for identifying the account.

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. The phrase 'represented by the current credentials' usefully reinforces that no account identifier is supplied, 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?

Clear verb+resource ('return the Agentline account') with a scope qualifier ('represented by the current credentials'). It is distinguishable from get_billing, get_my_number and get_voice_settings by returning the account itself, though it never names those siblings to sharpen 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is mentioned. The only hint is the implicit 'current credentials' framing, which an agent must infer means 'call this to identify the authenticated account'. No exclusions or prerequisites are 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 and closed-world, so the safety profile is covered. The description adds real value beyond that: the fields returned and the security-relevant fact that secrets are never retrievable after creation, which sets the agent's expectation for what this endpoint can and cannot expose.

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

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

Two short sentences, zero filler, with purpose front-loaded and the security caveat second. 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, no output schema and annotations carrying the safety profile, the remaining burden is describing what comes back and any caveats. The description supplies exactly that by naming returned fields and warning that secrets are not re-shown, so nothing an agent needs to call 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; the baseline for a parameterless tool is 4. The parenthetical naming of returned fields is auxiliary rather than 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?

Specific verb ('List') plus resource ('the account's API keys'), with the returned fields enumerated parenthetically. The verb alone cleanly separates it from sibling mutations create_api_key and revoke_api_key, so an agent can route 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?

No statement of when to use this versus alternatives, no prerequisites, no exclusions. The read-only listing intent is implied by the name only; the description supplies no routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the useful fact that this is a read-only account-event feed spanning several event types, but says nothing about ordering, default window, or result size 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?

A single tight sentence with no filler, front-loading the resource and its content. It is arguably too terse for a list tool, but nothing in the sentence 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?

For a simple, well-annotated, one-parameter list tool with no output schema, the description tells the agent what kinds of events appear, which is the core need. It leaves the limit parameter, ordering, and the meaning of 'recent' unexplained, so it is adequate but not complete.

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

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

Schema description coverage is 0% and the single 'limit' parameter is never mentioned in the description. Only the schema's own min/max (1–200) constrains it; the description does not explain default size, max page size, or whether pagination exists, so it fails to compensate for the coverage gap.

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

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

The description enumerates the exact event categories returned (sign-ins, sends, blocks, opt-outs, key changes, billing events), which makes the resource concrete. It is a noun-phrase fragment rather than an explicit verb+resource, and it does not distinguish itself from any sibling, 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?

There is no when-to-use guidance, no mention of prerequisites, and no alternatives named among the many list_* siblings (list_calls, list_emails, list_messages). The word 'Recent' hints at a recency scope but never defines the window or how to retrieve older events.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description usefully adds ordering ('newest first') and scope (inbox plus sent mail), but says nothing about pagination, default limit behavior, or result 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 front-loaded sentence with zero filler and the scope stated before the ordering. It is efficient, though arguably too terse for a 4-parameter tool with 25% schema coverage.

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

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

With no output schema and ample annotation coverage, the main gap is the four parameters: limit, direction, and since_seconds are only obliquely suggested. It is minimally adequate to call the tool but not sufficient to call it precisely.

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

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

Schema description coverage is only 25% (just unread_only), so the description needs to carry weight. It partially does: 'inbox (and sent mail)' maps to the in/out direction enum and 'recent' hints at since_seconds/limit, but the limit param and the enum values remain unexplained.

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

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

States a clear verb ('List') and resource ('emails') plus scope ('agent's inbox and sent mail') and ordering ('newest first'). It doesn't explicitly distinguish itself from siblings like read_email or list_messages, so an agent must infer the boundary rather than being told.

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

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

Usage is only implied by the scope wording; there is no explicit when-to-use guidance, no stated relationship to read_email (to view one email) or send_email, and no conditions for choosing this over list_messages. The agent must infer routing from the sibling names 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 cover idempotency (idempotentHint=true), non-destructiveness, and non-read-only status. The description adds genuinely new context: listing and reading never change read state, so this is the only way to mutate read status, plus a 100-id cap. It doesn't address side effects like notifications, so not a full 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?

Two dense sentences, front-loaded with the operation and the id source, followed by the usage rationale. 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 two-parameter mutation tool with rich annotations and no output schema, the description covers purpose, timing, defaults, and limits. Only minor gaps remain (no mention of error behavior for invalid ids), which is acceptable here.

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 (read defaults true, ids are email ids, maxItems 100). The description restates read=false and the 100-id limit but adds no syntax or format meaning 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 (mark) and resource (emails) and explicitly ties the ids to their source (list_emails). The distinction from read_email and list_emails is clear without opening any schema.

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

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

Gives explicit timing ('call this once you've dealt with an email') and explains why reads don't require it, plus points to list_emails' unread_only for filtering. This is actionable when-to-use guidance with a named alternative.

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 and destructiveHint=false, so the safety profile is covered. The description still adds value by pinning the exact side-effect boundary (read state untouched) and pointing to the tool that does mutate it, which is not derivable from a generic readOnly flag.

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

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

Two short sentences, zero waste. The core action is front-loaded and the boundary/alternative note follows it.

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

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

For a single-parameter read with no output schema, the description covers what it does, what it returns ('full text'), and what it does not do. 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 description coverage is 100% and the single parameter is documented with its source ('Email id from list_emails'), so the schema carries the load. The description only restates 'by id' and adds no format or lookup detail beyond it; 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?

Specific verb+resource ('Read the full text of an email by id') with scope qualifier ('full text'). It explicitly distinguishes itself from the sibling mark_read, so an agent can route without opening either schema.

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

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

Names the alternative and the condition that selects it: reading does not alter read state, and mark_read is the tool for that. Clear context, but it does not address the other read-shaped sibling (read_message), so the routing guidance is complete only for one axis.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds impact detail beyond them: the revocation is permanent and anything using the key stops working immediately. The required user confirmation is also disclosed. It stops short of 5 only because it says nothing about error behavior for unknown or already-revoked keys.

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

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

Three short sentences, each earning its place: the action, its consequence, and the confirmation requirement. The critical fact (permanent) is 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?

For a single-parameter destructive tool with no output schema and annotations covering the safety profile, this is nearly complete: it covers action, impact timing, permanence, and the confirmation step. Only edge-case behavior for invalid or already-revoked keys is unaddressed.

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

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

One parameter with 100% schema description coverage, and the schema already explains key_id comes from list_api_keys. The description adds no syntax, format, or sourcing detail beyond the schema, so the baseline of 3 applies.

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

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

"Permanently revoke an API key" is a specific verb+resource that is clearly distinct from the sibling tools create_api_key and list_api_keys. An agent can select it 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?

"Confirm with the user first" gives an explicit prerequisite workflow before invocation, which is meaningful guidance for an irreversible action. It does not name alternative tools, but none exist for this operation among the siblings, so the context is adequate.

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 a non-read-only, open-world, non-idempotent operation. The description adds genuinely useful behavior beyond that: the sending identity, a human-confirmation prerequisite, a hard 5-recipient cap, and a transactional-only restriction that rules out bulk mail.

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. The core action and sending identity come first, followed by the confirmation requirement and the usage constraints, so 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?

For a 6-parameter mutation tool with no output schema, the description covers identity, safety prerequisite, and scope limits well. Minor gaps remain on delivery behavior, threading semantics, and any rate limits, but nothing essential to correct invocation 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 83%, so the schema already documents from, html, text, and reply_to_id. The description only restates the recipient limit that maxItems=5 already encodes and gives no guidance on reply_to_id threading or html-vs-text precedence, so it adds little. 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 ('Send an email') and adds the important scoping detail that mail originates from the agent's @agentline.nz address. It does not explicitly distinguish itself from siblings like send_sms or reply-related tools, so it lands at clear-but-undifferentiated.

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?

'Confirm recipients and content with the user first' plus 'transactional and one-to-one mail only' gives real when-to-use conditions and an implied exclusion (no bulk/marketing blasts). It stops short of naming alternatives such as send_sms for text messaging, so it is context-rich but not fully routing.

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

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

Adds substantial context beyond the annotations: a 55s blocking window, the retry-on-found=false pattern, and the single-consumption semantics ('Each code is returned once'), which explains the non-idempotent annotation and is critical to avoid an agent re-reading a consumed code. It also names a return field (found) despite there being no output schema.

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

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

Four short sentences, front-loaded with what the tool does, then prerequisites, then failure handling. Every sentence carries operational value with no repetition of 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?

Given no output schema, the description usefully discloses the found=false outcome and the returned code, plus the timeout/retry loop. It stops short of describing any other return fields or whether a failed wait has side effects, leaving a small gap for a blocking 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 100%, so channel, from_contains, since_seconds and timeout_seconds are already documented with defaults and bounds. The description adds no parameter-level detail beyond implying email delivery, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Wait for a verification code (OTP) to arrive by email and return it.' This clearly distinguishes it from the read-oriented siblings like read_email, list_emails, and get_my_inbox, which do not block or consume a message.

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

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

Gives an explicit prerequisite and ordering: 'Trigger the code first (e.g. submit the sign-up form...), then call this,' plus failure handling ('if it returns found=false, call it again'). It does not name an alternative tool for non-OTP reads, so it stops just short of full when/when-not routing.

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