Test-inbox API for email and SMS: create inboxes, long-poll messages, extract OTPs and links.
Scored across 41 tools
Every tool targets a distinct resource-action pair (domain, inbox, hook, webhook, key, phone number, message, SMS, link, OTP, etc.), and the verbs clearly separate create/list/get/wait/clear/delete/follow/verify operations. There is no overlap or ambiguity between tools.
The overwhelming majority of tools follow a consistent verb_noun pattern (create_inbox, list_messages, wait_for_otp, etc.), but 'webhook_deliveries' is a noun phrase rather than a verb_noun command, which is a minor deviation.
With 41 tools, the server exceeds the 25+ threshold for 'too many' tools. While each tool is justifiable for the comprehensive email/SMS/webhook testing domain, the sheer number makes the surface feel heavy and harder to navigate.
The tool set covers full lifecycles for all major resources—create, list, get, wait, clear, delete—and includes specialized operations like verify_domain, follow_link, and webhook_deliveries. There are no obvious gaps or dead ends for the stated purpose of testing email, SMS, and webhooks.
Delete a hook's captured requests but keep the hook and its ingest URL — rerun hygiene between test runs.
| Name | Required | Description | Default |
|---|---|---|---|
| hook_id | Yes | Hook id (uuid) from create_hook or list_hooks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It accurately describes the two key behaviors (deleting requests, keeping hook and URL). However, it omits details like whether the operation is reversible, any required permissions, or potential side effects (e.g., does it affect other hooks?). For a simple destructive action, this is adequate but not 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?
The description is a single, front-loaded sentence that efficiently conveys the action, what is preserved, and a use case. Every word earns its place with no 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?
Given no output schema, the description should explain what the tool returns (e.g., success confirmation, count of deleted requests). It does not. The use case 'rerun hygiene' is helpful, but overall completeness is average for a simple 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%—the only parameter 'hook_id' has a description in the schema. The tool description adds no new information about the parameter beyond what the schema already provides. Thus, it meets the baseline of 3.
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 states the tool deletes captured requests while keeping the hook and ingest URL, differentiating it from 'delete_hook' (which would remove the hook entirely). However, it does not explicitly name 'delete_hook' as the alternative, leaving some ambiguity for an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'rerun hygiene between test runs' gives useful context for when to use this tool (to clean up between tests). However, it does not provide explicit guidance on when not to use it or mention any alternative tools (like 'clear_inbox' or 'delete_hook').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete all messages in an inbox but keep the address receiving. Use to reset state between test steps that reuse one inbox.
| Name | Required | Description | Default |
|---|---|---|---|
| inbox_id | Yes | Inbox id (uuid) returned by create_inbox or list_inboxes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Clearly explains that messages are deleted while the receiving address is preserved. Does not mention permissions or reversibility, but the main behavioral trait (destructive but not deleting the inbox) is well communicated.
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 with no wasted words. First sentence states function, second gives use case. Information is front-loaded and efficient.
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 tool with one parameter and no output schema, the description covers purpose, use case, and behavioral distinction. Missing explicit return value information, but the low complexity makes it nearly 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% with a clear description of inbox_id. The tool description does not add additional meaning beyond the schema, so baseline score of 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?
The description clearly states the action ('Delete all messages in an inbox') and distinguishes from sibling 'delete_inbox' by noting the inbox address is kept. The verb 'clear' is specific and the resource 'inbox' 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?
Explicitly states when to use: 'reset state between test steps that reuse one inbox'. This provides clear context for testing scenarios. Does not explicitly state when not to use, but the guidance is sufficient for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register a custom domain for receiving test mail. Returns the DNS records (TXT challenge + MX) to publish; the domain accepts mail only after verify_domain passes.
| Name | Required | Description | Default |
|---|---|---|---|
| fqdn | Yes | The domain to receive test mail on, e.g. mail.example.com. The response carries the TXT + MX records to publish. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It discloses return of DNS records and the verification dependency. Lacks auth or rate limit details, but is sufficient for a simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. Purpose is front-loaded. Every word serves a purpose.
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?
Single parameter, no output schema, yet description fully explains the tool's action, return, and lifecycle. Adequate for its 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 covers 100% of parameters. Description adds value by explaining the response (TXT + MX records) and the requirement for verify_domain, exceeding baseline of 3.
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?
Description clearly states 'Register a custom domain for receiving test mail', with specific verb and resource. It distinguishes from siblings like verify_domain by mentioning the prerequisite.
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 notes that domain accepts mail only after verify_domain passes, guiding when to use that tool. No explicit when-not or alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a capture hook: a public HTTPS URL that records every HTTP request sent to it (webhook capture). Point the app under test's webhook config at the returned ingest_url, then call wait_for_hook_request. Receive-only: mailfixture answers a fixed 200 and never forwards or replays. Returns {id, token, ingest_url, label, ttl_expires_at}.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Optional human label ("checkout-service webhooks"). | |
| ttl_seconds | No | Auto-delete the hook (and its captured requests) after this many seconds (60..2592000). Omit for a long-lived hook. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: records all requests, returns fixed 200, never forwards/replays, auto-deletes based on ttl_seconds, and describes the return object.
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 concise sentences front-load core purpose, then procedural details, constraints, and return fields; every sentence is essential.
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?
Despite no output schema, the description includes return fields and covers all relevant aspects: purpose, usage, limitations, and lifecycle, making it complete for a creation 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% with descriptions; the description adds marginal context (auto-delete, long-lived) but does not significantly elaborate 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?
The description clearly states the tool creates a capture hook (public HTTPS URL) that records HTTP requests, distinguishing it from siblings like create_webhook or list_hooks.
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 explicit guidance on pointing the app's webhook config at the ingest_url and then calling wait_for_hook_request, though it does not explicitly list when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a programmatic email inbox and get its address. Call this at the start of a test flow, then drive the app under test with the returned email_address. Use one inbox per test for isolation.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Domain the inbox lives on (fqdn). Omit for the shared utility domain; set to one of the account's verified custom domains otherwise. | |
| local_part | No | Local part of the address (1-64 chars of [a-z0-9._-]). Omit for a random one — the safe default for inbox-per-test isolation. | |
| ttl_seconds | No | Auto-delete after this many seconds (60..=2592000). Omit for no TTL. Prefer a TTL in test suites so abandoned inboxes clean themselves up. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes creation and address retrieval but does not mention mutability, consequences, authorization, or cleanup behavior. Adequate but not 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?
Three concise, well-structured sentences with key information front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with optional parameters and no output schema, the description is complete enough. Includes usage pattern and isolation advice. Minor gap: no mention of TTL or domain defaults.
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 has 100% description coverage, so baseline 3. Description adds no parameter-specific guidance beyond what schema 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?
Description clearly states the tool creates a programmatic email inbox and returns its address. The verb 'create' and resource 'inbox' are specific, and it distinguishes from siblings like clear_inbox or delete_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?
Provides explicit advice: call at the start of a test flow, drive app under test with returned address, use one per test for isolation. Does not explicitly state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new API key. The raw key is in this response ONLY — it is stored hashed and can never be shown again. Handle it as a secret.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Human-readable label for the key (shown in listings). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the raw key is only available in this response, is stored hashed, and must be handled as a secret. No annotations present, so description carries full burden.
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: first states purpose, second gives crucial behavioral info. No wasted words, 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?
Tool is simple with one parameter and no output schema. Description covers the key behavior and security note. Could mention response format but not necessary given context.
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 only parameter 'label' is fully described in the input schema (human-readable). Description adds no further meaning, 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?
Description clearly states 'Create a new API key' with a specific verb and resource. It distinguishes from sibling tools like revoke_key and list_keys.
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 critical usage note about key being shown only once and stored hashed, but does not explicitly state when not to use or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provision a dedicated US phone number for receiving SMS (paid plans only; numbers are receive-only — mailfixture never sends). Returns {id, phone_number, status}. If status is 'pending', call list_phone_numbers until it becomes 'active' before using the number in the flow under test; then call wait_for_sms_otp.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that numbers are receive-only, returns {id, phone_number, status}, and explains pending status behavior. Transparent about limitations.
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, dense with information. The first sentence covers purpose and constraints; the second covers workflow. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description specifies return format and related tools. Given zero parameters, it provides sufficient context for an agent to use 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?
Input schema has 0 parameters, so no parameter info needed. Baseline 4 for zero-param tools. Description does not add param info, but not required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provisions a dedicated US phone number for receiving SMS, with specific verb and resource. It distinguishes from siblings like list_phone_numbers and release_phone_number.
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 mentions 'paid plans only' and 'receive-only', and provides conditional workflow: if status is 'pending', call list_phone_numbers then wait_for_sms_otp. Could be more explicit about when not to use, but adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a webhook endpoint (paid plans) receiving signed message.received and domain.verified events. The signing secret is in this response ONLY. Message bodies are never delivered over webhooks.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | HTTPS endpoint to receive signed message.received / domain.verified events. | |
| description | No | Optional description shown in listings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description discloses critical behavioral traits: the signing secret is only shown in the response, and message bodies are never delivered over webhooks. This is valuable transparency.
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 concise sentences, each adding essential information: purpose and behavioral constraint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters and no output schema, the description covers the core purpose and key behavioral constraints. Could mention HTTPS requirement explicitly, but it's in the parameter description.
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% (both parameters have descriptions). The tool description adds context about the events and plans but does not significantly enhance understanding of the parameters beyond what the schema 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 clearly states the tool creates a webhook endpoint for specific events (message.received and domain.verified) and includes the constraint that it's for paid plans. It distinguishes from sibling tools like test_webhook, delete_webhook, etc.
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 mentions the tool is for paid plans and specifies the events it handles, implying when to use it. However, it does not explicitly state when not to use it or compare to alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a custom domain and every inbox and message on it. Irreversible.
| Name | Required | Description | Default |
|---|---|---|---|
| domain_id | Yes | Domain id (uuid) from create_domain or list_domains. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the destructive behavior: deletion of domain, all inboxes, and messages, plus irreversibility. This is good but could detail potential impacts like webhook breakage.
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, concise sentence conveys the essential information without waste. Front-loaded with 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?
For a simple delete operation, the description covers scope and irreversibility. Lacks details on error cases or prerequisites, but is complete enough for typical 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 input schema has 100% coverage with a description for domain_id. The tool description adds no additional parameter meaning, 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?
The description clearly states 'Delete a custom domain and every inbox and message on it. Irreversible.' It uses a specific verb and resource, and distinguishes from siblings like create_domain or verify_domain by noting the cascading delete.
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 use for removing a domain entirely, but lacks explicit when-to-use or when-not-to-use guidance. No alternatives or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a capture hook and all its captured requests. The ingest URL answers 404 afterwards. Irreversible.
| Name | Required | Description | Default |
|---|---|---|---|
| hook_id | Yes | Hook id (uuid) from create_hook or list_hooks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses irreversibility, deletion of captured requests, and resulting 404 behavior. This is adequate for a simple delete 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?
Two concise sentences with no filler. The main action is front-loaded, and key consequences (deletion of requests, 404, irreversibility) are immediately provided.
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 fully covers the effect, outcomes, and permanence. No further detail is needed given the 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 describes the hook_id parameter sufficiently. The description adds no extra parameter information, meeting the baseline but not 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?
The description clearly states the tool deletes a capture hook and all its captured requests, distinguishing it from siblings like clear_hook (which likely clears requests but keeps the hook). It also notes the ingest URL returns 404, adding specificity.
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 usage for permanent deletion but does not explicitly contrast with alternatives like clear_hook. It lacks when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an inbox and all its messages. Mail to the address is rejected afterwards. Use as test teardown.
| Name | Required | Description | Default |
|---|---|---|---|
| inbox_id | Yes | Inbox id (uuid) returned by create_inbox or list_inboxes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits: deletes all messages and rejects future mail. With no annotations, description carries full burden; this is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. First sentence states action, second provides use case. Efficient and structured.
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 delete tool with no output schema, the description covers behavior, side effects, and usage context completely.
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 description repeats the schema's parameter description. No additional meaning added 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?
The description clearly states the verb 'Delete' and the resource 'inbox and all its messages', and distinguishes from sibling tool 'clear_inbox' which likely only clears 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 provides explicit context 'Use as test teardown', indicating when to use. Could be improved by explicitly contrasting with alternatives like 'clear_inbox'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a webhook endpoint. Pending deliveries to it are dropped.
| Name | Required | Description | Default |
|---|---|---|---|
| webhook_id | Yes | Webhook endpoint id (uuid) from create_webhook or list_webhooks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions that pending deliveries are dropped, but does not disclose irreversibility or other side effects beyond annotations (none provided).
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, front-loaded sentences with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-param tool, the description covers the action and a key side effect, though it could mention if deletion is synchronous.
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 description adds no extra meaning beyond the schema's parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Delete a webhook endpoint' and the resource, distinguishing it from siblings like create_webhook or test_webhook.
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 explicit guidance on when to use this tool vs alternatives like enable_webhook. The description only states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-enable a webhook endpoint that was auto-disabled after repeated failed deliveries.
| Name | Required | Description | Default |
|---|---|---|---|
| webhook_id | Yes | Webhook endpoint id (uuid) from create_webhook or list_webhooks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the action (re-enable) and the trigger condition, but lacks details on permissions, side effects, or behavior when the webhook is already enabled or does not 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?
The description is a single concise sentence that front-loads the action and context. Every word earns its place with no 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 simple tool with one parameter and no output schema, the description provides sufficient context to understand when and why to use it. It could mention error handling (e.g., if webhook is already enabled) but is generally 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?
With 100% schema coverage, the schema already describes the webhook_id parameter. The description does not add any additional meaning or context beyond what the schema provides, resulting in a baseline score of 3.
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 states the action (re-enable) and the specific resource (webhook endpoint that was auto-disabled after repeated failed deliveries). It distinguishes from sibling tools like create_webhook, delete_webhook, and test_webhook.
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 implicitly provides usage context by specifying the condition (auto-disabled after repeated failed deliveries). However, it does not explicitly state when not to use or mention alternatives, leaving some ambiguity for edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Follow (server-side GET) a link extracted from a message — the 'click the verification link' step without leaving the conversation. Defaults to the first verify-classed link; pass class, index, or an exact url to pick another. Redirects are followed (SSRF-guarded, https-only, max 5). Returns {requested_url, final_url, status, redirects, ok} — the target's response body is never returned.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Follow this exact URL (must be one of the message's extracted links). At most one of url, class, index. | |
| class | No | Follow the first link of this class: verify | reset | unsubscribe | other. Default when nothing is passed: verify. | |
| index | No | Follow the link at this zero-based index of the extracted links. | |
| message_id | Yes | Message id (uuid) whose extracted link to follow. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses key behavioral traits: SSRF-guarded, https-only, max 5 redirects, and that the response body is never returned. It also explains default behavior (first verify-classed link). Minor omission: no mention of error handling or timeout 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?
The description is a single efficient paragraph with no redundancy. It is front-loaded with the main purpose, followed by selection options, then safety and return format. Every sentence adds value.
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 provides the return object structure. It covers selection, safety, and behavior. It is slightly incomplete: missing error scenarios (e.g., invalid URL, timeout) or what happens when no link matches the criteria. Otherwise thorough.
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%, but the description adds meaning beyond schema: explains the default for 'class' (verify), mutual exclusivity among url/class/index, and details about the return object's fields. This helps the agent understand parameter interaction and expected output.
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 states the tool follows a link server-side ('Follow (server-side GET) a link extracted from a message'), specifies the typical use case ('click the verification link'), and distinguishes from siblings like 'get_links' (list only) and 'follow_sms_link' (follow SMS 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?
It provides context for when to use ('click the verification link' step) and explains how to select alternative links via class, index, or exact URL. It does not explicitly list when not to use or mention alternatives, but the guidance is clear for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Follow (server-side GET) a link extracted from an SMS — same semantics as the email follow_link tool: defaults to the first verify-classed link, accepts class/index/exact url, SSRF-guarded, https-only, max 5 redirects. Returns {requested_url, final_url, status, redirects, ok}.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Follow this exact URL (must be one of the SMS's extracted links). At most one of url, class, index. | |
| class | No | Follow the first link of this class: verify | reset | unsubscribe | other. Default when nothing is passed: verify. | |
| index | No | Follow the link at this zero-based index of the extracted links. | |
| sms_id | Yes | SMS id (uuid) whose extracted link to follow. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden. It discloses SSRF-guarded, https-only, max 5 redirects, and the return structure {requested_url, final_url, status, redirects, ok}. This is comprehensive for a server-side GET tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The first sentence covers purpose and behavior, the second covers return format. Structure is ideal.
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?
Despite no output schema, the description explicitly states the return fields. All 4 parameters are explained, behavior is detailed, and the tool's role among siblings (SMS link following) is clear. Complete for a tool of this complexity.
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 input schema has 100% description coverage, but the description adds significant meaning: it explains the default class is 'verify', the mutual exclusivity of url/class/index, and that url must be one of the extracted links. This enriches understanding beyond the schema alone.
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 states the tool follows a link from an SMS via server-side GET, and distinguishes itself by referencing the similar follow_link tool for email. The verb 'follow' and resource 'link' are specific.
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 provides clear guidance on when to use (for SMS links) and mentions defaults (verify class) and options (class, index, exact URL). While it references follow_link's semantics, it does not explicitly exclude cases or differentiate from sibling tools like wait_for_sms, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One attachment's decoded bytes, base64-encoded (up to 1 MiB — larger files must be fetched from GET /v1/messages/{id}/attachments/{index}). Index against the attachments array on get_message.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Zero-based index into the message's attachments array. | |
| message_id | Yes | Message id (uuid). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the base64 encoding, size limit, and alternative endpoint, but does not mention error handling (e.g., out-of-bounds index) or authentication requirements.
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 key information (bytes, encoding, size limit, alternative). No filler or 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?
Given no output schema, description explains return format and size limit. Covers main usage but lacks error behavior or rate limits. Adequate for a simple retrieval 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 baseline is 3. Description adds no additional semantic detail beyond what is already in the parameter descriptions ('uuid', 'zero-based index'). No extra value.
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?
Description clearly states it returns one attachment's decoded bytes base64-encoded, specifies size limit and alternative for larger files, and explains indexing against the attachments array. Distinguished from sibling tools like get_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?
States when to use (for attachments up to 1 MiB) and provides alternative for larger files. Mentions indexing context but lacks explicit when-not-to-use or alternatives beyond the REST endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full detail of one captured request: method, path, headers (names lowercased; same-name duplicates keep their order, cross-name order not preserved), body as text (body_base64 rides along only when the raw bytes were not valid UTF-8 — signature checks need exact bytes), remote_ip, expiry.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | Yes | Captured request id (uuid) from list_hook_requests or wait_for_hook_request. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals important details: header names are lowercased, duplicate names preserve order but cross-name order is not preserved, body is text with body_base64 included only when raw bytes are not valid UTF-8. It does not state read-only nature but is largely transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose and lists all key fields with nuanced details. Every word adds value without 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?
Despite lacking an output schema, the description comprehensively covers the returned fields and their behaviors. It accounts for edge cases like body_base64 and header ordering. Minor omission: no mention of response format (assumed JSON), but given the simplicity, it is sufficiently 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?
The input schema has 100% description coverage for the single required parameter request_id, providing its type, format, and source. The description does not add extra meaning beyond the schema, 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?
The description clearly states the tool's purpose: retrieving full details of a captured request including method, path, headers, body, remote_ip, and expiry. It immediately distinguishes itself from sibling tools like list_hook_requests and wait_for_hook_request by focusing on a single request's complete detail.
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 usage after obtaining a request_id from list_hook_requests or wait_for_hook_request, but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusion criteria. The context is clear but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All links extracted from one message, each with anchor text and a class guess (verify | reset | unsubscribe | other). If you are still waiting for the email, prefer wait_for_link.
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | Message id (uuid) from list_messages or wait_for_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the tool extracts links, implying a read-only operation, but does not explicitly confirm non-destructiveness or discuss error cases (e.g., missing message). The classification aspect ('class guess') adds some value, but transparency is incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the first sentence clearly stating the tool's function and the second providing usage guidance. Every word adds value, no redundancy, and key info 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 simple one-parameter tool with no output schema, the description adequately covers purpose, parameter source, output details, and an alternative tool. It feels complete and leaves no obvious gaps for an agent to misunderstand.
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 parameter, but the description adds meaning by specifying the parameter comes from list_messages or wait_for_message, which is not in the schema. It also describes the output format (anchor text and class guess), going beyond the bare schema definition.
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 states it extracts all links from a single message, including anchor text and class guesses. It distinguishes itself from wait_for_link by advising to use that tool when still waiting for the email. The verb 'extracted' implies retrieval, but a more explicit verb like 'get' or 'list' would be clearer.
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 explicitly advises preferring wait_for_link if still waiting for the email, which is a clear alternative. It does not mention other exclusions or prerequisites, but the guidance is specific and helpful for choosing between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full detail of one message: text/html bodies, headers, extracted OTP candidates and classified links, attachment metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | Message id (uuid) from list_messages or wait_for_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes output content but does not disclose behavioral traits like side effects, permissions, or idempotency. For a read operation, minimal behavioral info is acceptable, but more would improve transparency.
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?
Single concise sentence that front-loads the purpose and lists contents efficiently. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-param tool with no output schema, the description covers what it returns well. However, it lacks contextualization against many sibling tools; still sufficient for basic 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?
Schema coverage is 100% with the parameter description already providing context (message id from list_messages). The description adds no additional parameter meaning beyond what is 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?
The description clearly states it retrieves full details of one message and lists specific components (text/html bodies, headers, OTP, links, attachment metadata). It distinguishes from siblings like list_messages and specific extractors like get_otp.
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 explicit guidance on when to use this vs alternatives like get_links or get_attachment. The parameter description implies it requires a message id from list_messages, but usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The OTP/verification code extracted from one message: best candidate plus ranked alternatives. If you are still waiting for the email, prefer wait_for_otp.
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | Message id (uuid) from list_messages or wait_for_message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'best candidate plus ranked alternatives' but does not explain what determines 'best' or how the ranking works. It also does not disclose whether this is a read-only operation (likely) or any side effects, leaving significant behavioral ambiguity.
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 composed of two succinct sentences that front-load the key information. Every word adds value, and there is no redundancy or unnecessary 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?
Given the low complexity (one parameter, no output schema), the description is fairly complete. It explains what the tool returns and when to use an alternative. However, it could be more complete by clarifying the output format or how to interpret 'ranked alternatives.'
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 input schema already provides a full description for the only parameter (message_id: 'Message id (uuid) from list_messages or wait_for_message.'). The tool description adds no additional meaning beyond this, so the baseline score of 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?
The description clearly states 'OTP/verification code extracted from one message: best candidate plus ranked alternatives.' It specifies the resource (OTP from a message) and the action (extract), and hints at the output format with 'best candidate plus ranked alternatives,' distinguishing it from sibling tools like get_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when not to use this tool: 'If you are still waiting for the email, prefer wait_for_otp.' This provides clear guidance on choosing between siblings, and the context is directly actionable for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full detail of one SMS: text, sender, extracted OTP candidates and classified links, expiry.
| Name | Required | Description | Default |
|---|---|---|---|
| sms_id | Yes | SMS id (uuid) from list_sms or wait_for_sms. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the specific data returned (text, sender, OTP, links, expiry). However, it does not state that the operation is read-only or any side effects, but the nature of 'get' implies no 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?
Single sentence with no superfluous words. Essential information is front-loaded and efficiently packed.
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 single parameter and no output schema, the description adequately covers what the tool returns. It does not mention related sibling tools explicitly, but the context is sufficient for an agent to infer usage.
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% with a clear parameter description ('SMS id (uuid) from list_sms or wait_for_sms'). The tool description adds no extra meaning for the parameter, 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?
The description uses a specific verb ('get') and resource ('SMS'), and details the output fields (text, sender, OTP candidates, links, expiry), clearly distinguishing it from siblings like list_sms (lists) or wait_for_sms (waits for arrival).
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 ('Full detail of one SMS'), but no explicit guidance on when to use versus alternatives like get_otp (only OTP) or get_message (possibly email). No when-not-to-use or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's domains (custom ones with verification state and pending DNS setup records, plus the shared domains).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral aspects: it returns domains with verification state and pending DNS setups. It does not mention authentication, rate limits, or pagination, but for a zero-parameter list tool, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured sentence that efficiently conveys the tool's scope without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters, the description completely covers what is returned and the distinction between custom and shared domains. No output schema exists, but the description adequately informs the agent of the output 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 has no parameters, so the description does not need to add meaning beyond the schema. Schema coverage is trivially 100%, and no additional parameter info is needed.
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 states the tool lists domains associated with the account, specifically mentioning custom domains with verification state and pending DNS setup records, along with shared domains. This distinguishes it from sibling tools like create_domain or delete_domain.
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 usage for listing domains but provides no explicit guidance on when to choose this tool over alternatives or any exclusions. It lacks explicit context for when-not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List requests captured by a hook (id, method, path, content_type, body_size, received_at per request; bodies stay on get_hook_request). Set wait to long-poll for new requests; use since as a cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Long-poll up to this many seconds (max 60) for a matching request instead of returning an empty list immediately. | |
| match | No | Filter: `method:POST` (exact verb), `path:term` or `body:term` (substring); a bare term matches the body. Body matching scans the first 32 KiB; detail responses remain complete. | |
| since | No | Only requests received after this RFC 3339 timestamp. Use the received_at of the last request you saw as a cursor. | |
| hook_id | Yes | Hook id (uuid). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return value (request metadata) and key behaviors (long-poll, cursor). With no annotations, it carries the transparency burden; misses details like ordering, pagination limits, or whether response is an array, but is adequate for a simple list.
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-loads core purpose, then usage hints. No redundant words; highly efficient.
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, so description must cover response shape. Lists returned fields and notes body location. Missing ordering, pagination details, and explicit statement that result is an array, but covers essentials.
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%, baseline 3. Description adds context for 'wait' and 'since' beyond schema descriptions (long-poll, cursor usage), enhancing understanding.
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?
Clearly states 'List requests captured by a hook', specifying the verb and resource. Explicitly lists metadata fields returned per request and distinguishes from get_hook_request by noting bodies remain there.
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 guidance on using 'wait' for long-polling and 'since' as a cursor for pagination. However, does not explicitly contrast with sibling tools like wait_for_hook_request or list_hooks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's capture hooks with id, ingest_url, label, ttl_expires_at, created_at.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Minimal behavioral disclosure; no annotations provided, so description should indicate side effects or limitations, but only states fields returned.
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?
Single sentence, concise, no unnecessary words, effectively communicates the tool's output.
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?
Adequate for a simple list tool with no parameters; lacks details on ordering, pagination, or limits, but covers basic functionality.
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?
No parameters exist, baseline is 4; description adds value by enumerating returned fields, which is beyond 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?
The description clearly states the action 'List' and the resource 'capture hooks' with specific fields, distinguishing it from sibling list 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?
No guidance on when to use this tool versus alternatives like list_inboxes or list_messages; implied usage but lacks exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's active inboxes with their addresses and message counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates a read operation (listing), but does not disclose other behavioral traits such as side effects, rate limits, or authentication requirements. The description is minimal and lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that effectively communicates the tool's function without unnecessary words. It is front-loaded and efficient.
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 provides basic information (addresses and message counts) but omits potential details like whether an inbox ID or other metadata is returned. For a simple list tool, it is functional but could be more 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?
With zero parameters, schema coverage is 100%. The description adds no parameter specifics because none exist, so baseline for no parameters is appropriate. It does not need to add meaning 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?
The description clearly states it lists inboxes, specifying 'active inboxes' with 'addresses and message counts'. The verb 'list' and resource 'inboxes' are direct, distinguishing it from sibling tools like create_inbox or delete_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?
The description implies usage for retrieving inbox information but provides no explicit guidance on when to use this tool versus alternatives like list_messages or list_domains. The distinction is based solely on the resource type, which is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's API keys (metadata only — never the key material).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that only metadata is returned, not key material, which is a critical safety trait. However, it lacks details on pagination, ordering, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no wasted words, and the parentheses add clarity. Extremely concise while conveying the key point.
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 description should clarify what metadata is returned (e.g., key names, IDs). It fails to do so. However, for a zero-param list tool, the description is minimally complete but leaves ambiguity.
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?
No parameters exist, so baseline 4 applies. The description does not need to elaborate on parameters, but it correctly states the tool's scope without adding param info.
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 states the verb 'List', resource 'API keys', and scope 'account's'. It distinguishes itself from sibling tools like 'create_key' and 'revoke_key' by emphasizing 'metadata only — never the key material'.
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 does not explicitly provide when to use or compare to alternatives. It only states what the tool does, leaving usage guidance implicit. For a simple list tool, this is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List messages in an inbox (id, from, subject, received_at, tls per message). Set wait to long-poll for new mail; use since as a cursor to skip messages you already processed. Returns summaries — call get_message for bodies and extracted data.
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Long-poll up to this many seconds (max 60) for a matching message instead of returning an empty list immediately. | |
| match | No | Filter: `subject:term`, `from:term`, or `to:term`; a bare term matches the subject. | |
| since | No | Only messages received after this RFC 3339 timestamp. Use the received_at of the last message you saw as a cursor. | |
| inbox_id | Yes | Inbox id (uuid). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses it returns summaries, long-poll behavior, and cursor usage. Since no annotations, description carries burden; it adequately covers read-only nature and key behaviors, though missing pagination details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and return fields, followed by usage tips. No redundant information, every sentence 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?
Covers key behaviors: return summaries, long-poll, cursor. Missing pagination or limit information, but sufficient for a simple list tool with well-documented parameters.
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 has 100% coverage, baseline 3. Description adds context for 'wait' and 'since' usage but does not enhance 'match' parameter beyond schema. Minimal added value over schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool lists messages in an inbox and specifies the returned fields (id, from, subject, received_at, tls). It clearly distinguishes from sibling get_message by noting it returns summaries.
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 guidance on when to use long-poll (wait parameter) and cursor usage (since). Differentiates from get_message for full body retrieval. Does not explicitly state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's active phone numbers with id, phone_number (E.164), status, created_at, and release_after (non-null when a plan downgrade scheduled the number for auto-release; upgrading before that date keeps it).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden; it explains the returned fields and the special meaning of release_after. It does not mention pagination or ordering, but given zero parameters, simple listing is assumed.
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?
Single sentence, front-loaded with key information, no wasted words; every part adds value.
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 list tool without output schema, the description is fairly complete, explaining return fields and the release_after nuance. However, it could mention whether it includes only numbers in active state and if any filtering is possible.
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 has no parameters, so description is not required to document them; the baseline score of 4 applies as there is no need for additional parameter information.
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 uses the verb 'list' and specifies the resource 'active phone numbers' with exact fields returned, distinguishing it from sibling list tools that target different resources like domains or inboxes.
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 usage for viewing active phone numbers but provides no explicit guidance on when to use this tool versus alternatives like release_phone_number, nor does it mention prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List SMS received on a phone number (id, from_number, text, received_at per message — the text rides in the summary). Set wait to long-poll for new messages; use since as a cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Long-poll up to this many seconds (max 60) for a matching message instead of returning an empty list immediately. | |
| match | No | Filter: `from:term`, `to:term`, or `body:term`; a bare term matches the body. | |
| since | No | Only messages received after this RFC 3339 timestamp. Use the received_at of the last message you saw as a cursor. | |
| phone_number_id | Yes | Phone number id (uuid). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It mentions that 'text rides in the summary' (clarifying output format) and describes long-poll behavior. However, it does not disclose auth requirements, rate limits, or whether the operation is read-only, leaving 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?
The description is two sentences: the first states the purpose and output fields, the second explains key parameters. No redundant wording, and essential information 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?
Given no output schema, the description lists return fields (id, from_number, text, received_at) and mentions the text in summary. It covers filtering via 'match' and cursor via 'since', but lacks explicit pagination or ordering details, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the typical use pattern for 'wait' and 'since' beyond the schema descriptions, such as 'Set wait to long-poll for new messages; use since as a cursor.'
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 states 'List SMS received on a phone number' with specific fields (id, from_number, text, received_at). The verb 'List' and resource 'SMS' are explicit, and it distinguishes from siblings like 'get_sms' (single) and 'wait_for_sms' (polling only).
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 explains when to use 'wait' (long-poll for new messages) and 'since' (as a cursor), providing clear usage context. However, it does not explicitly contrast with alternative tools like 'wait_for_sms' or state 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.
List the account's webhook endpoints (secrets masked to a hint).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions the secret masking behavior, but lacks details on pagination or idempotency. Adequate but not comprehensive.
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?
Single sentence, no wasted words, straight to the point.
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 tool with no output schema and 0 parameters, the description is reasonably complete but could hint at the output structure (e.g., list of endpoint objects).
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?
No parameters exist, so baseline is 4. The description adds value by noting the secret masking, which relates to the output schema not the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists webhook endpoints and adds a specific detail about secrets being masked, which distinguishes it from sibling tools like create_webhook or delete_webhook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. For example, it doesn't mention that this lists all webhooks or that filtering is not supported.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Release a phone number back to the provider and delete its messages. Irreversible — the number returns to the provider pool and may be assigned elsewhere.
| Name | Required | Description | Default |
|---|---|---|---|
| phone_number_id | Yes | Phone number id (uuid) from create_phone_number or list_phone_numbers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers the irreversible nature, deletion of messages, and reassignment of the number. Provides sufficient transparency for an agent.
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 concise sentences with no wasted words. Front-loaded with the primary action and key consequence.
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 tool with one parameter and no output schema, the description is adequate. It covers the action, irreversibility, and effect, though it could mention any prerequisites.
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 parameter. Description does not add additional meaning beyond the schema, so baseline score 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?
Clearly states the action (release a phone number) and the consequences (delete messages, return to provider pool). Distinguishes well from sibling tools like create_phone_number and list_phone_numbers.
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 explicit guidance on when to use this tool vs alternatives or prerequisites. Only implies it's for releasing a number, but lacks context on conditions or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke an API key immediately. Revoking the key this session authenticated with locks this MCP connection out.
| Name | Required | Description | Default |
|---|---|---|---|
| key_id | Yes | Key id (uuid) from list_keys. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses key behaviors: immediate revocation and potential lockout of the current MCP connection. This provides sufficient transparency for a simple tool, though it could mention reversibility or permissions.
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 highly concise, using two sentences to convey the action, immediacy, and a critical edge case (locking the connection). No unnecessary words or 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 single-parameter tool with no output schema, the description covers the essential action and a key behavioral consequence. It is complete enough for safe invocation, though it could mention the outcome when revoking a non-authenticated key.
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 already has 100% description coverage for the single parameter key_id, explaining it as a UUID from list_keys. The description does not add additional semantic meaning beyond what the schema provides, earning a baseline score of 3.
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 states the action ('Revoke an API key') and the resource ('API key'), distinguishing it from sibling tools like create_key or list_keys. It also adds context about the immediate effect on the current session.
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 (need to revoke a key) and warns about the consequence of locking out the current session if the authenticated key is revoked. However, it does not explicitly mention when not to use or suggest alternatives like deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue a test event to a webhook endpoint to confirm it receives and verifies signed deliveries.
| Name | Required | Description | Default |
|---|---|---|---|
| webhook_id | Yes | Webhook endpoint id (uuid) from create_webhook or list_webhooks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It indicates a write operation ('Queue a test event') and mentions receipt and verification, but does not disclose side effects, idempotency, rate limits, or whether it modifies state. The description adds some behavioral context but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the action and purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema. The description adequately explains the purpose but does not mention the return value or behavior details (e.g., whether it returns delivery status). It is minimally complete but could include more context about expected outcomes.
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 input schema already provides a description for webhook_id: 'Webhook endpoint id (uuid) from create_webhook or list_webhooks.' Schema coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema's parameter documentation.
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 states the verb 'Queue', the resource 'a test event to a webhook endpoint', and the purpose 'to confirm it receives and verifies signed deliveries'. It distinguishes itself from sibling tools like create_webhook (which creates an endpoint) and webhook_deliveries (which lists past deliveries).
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 use when testing a webhook endpoint, but does not explicitly state when to use this tool vs alternatives like enable_webhook or webhook_deliveries. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the TXT + MX DNS checks for a pending custom domain right now and return the result. Call after publishing the records from create_domain.
| Name | Required | Description | Default |
|---|---|---|---|
| domain_id | Yes | Domain id (uuid) from create_domain or list_domains. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states the tool runs checks and returns a result, implying a read-like action. However, it does not specify whether the operation is idempotent, what happens if the domain is not pending, or any side effects like logging or triggers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence states the action and outcome, the second provides usage context. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema. The description explains what it does and when to use it, but lacks details about the result format (e.g., boolean, JSON fields). For a straightforward check, this is adequate but not fully 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?
The only parameter 'domain_id' has full schema coverage (100%) with a description already indicating its source ('from create_domain or list_domains'). The tool description adds no extra meaning beyond the schema, meeting the baseline for covered 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?
The description clearly states the tool runs TXT+MX DNS checks for a pending custom domain, with a specific verb ('verify') implied. It distinguishes from siblings like create_domain (which sets up the domain) and list_domains (which lists 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?
Explicitly instructs to 'Call after publishing the records from create_domain', providing clear context for when to use the tool. Does not mention when not to use it or contrast with all siblings, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Block until a matching HTTP request is captured by the hook (or timeout_seconds elapses), then return its full detail. The one-call answer to 'trigger the flow under test, then assert its webhook fired'.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Filter: `method:POST` (exact verb), `path:term` or `body:term` (substring); a bare term matches the body. Body matching scans the first 32 KiB; detail responses remain complete. | |
| since | No | Only consider requests received after this RFC 3339 timestamp. Omit to accept a request that already arrived. | |
| hook_id | Yes | Hook id (uuid) to watch. | |
| timeout_seconds | No | Give up after this many seconds (default 45, max 60). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the blocking behavior and timeout fallback, which is a critical behavioral trait. Without annotations, it carries the full burden and does so well, though it could mention what happens on timeout (e.g., returns null or error) and if 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?
The description is two sentences: the first delivers the core action and the second provides a concise use-case summary. Every word earns its place, with no 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?
The description covers the essential behavior and use case well. However, without an output schema, it doesn't specify the return structure (e.g., fields like method, path, body). Also, default timeout is in schema but not description. Still, it is largely complete 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?
The input schema covers all 4 parameters with descriptions, achieving 100% coverage. The tool description does not add new information about parameters beyond what the schema provides, so it meets the baseline score.
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 states the tool blocks until a matching hook request is captured, then returns its full detail. It uses specific verbs ('Block', 'return') and resource ('hook request'), and provides a succinct use case that distinguishes it from siblings like get_hook_request or list_hook_requests.
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 explicit context with the phrase 'trigger the flow under test, then assert its webhook fired', indicating when to use this tool. It doesn't explicitly exclude alternatives, but the framing strongly implies its specific role in the testing flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Block until a message containing an extracted link arrives, then return that link (optionally only a given class: verify | reset | unsubscribe | other). The one-call answer to 'trigger the email, get the magic/verification link'. Returns {message_id, link, links}.
| Name | Required | Description | Default |
|---|---|---|---|
| class | No | Only accept links classified as this: verify | reset | unsubscribe | other. Omit for the first link of any class. | |
| match | No | Filter: `subject:term`, `from:term`, or `to:term`; a bare term matches the subject. | |
| since | No | Only consider messages received after this RFC 3339 timestamp. Omit to accept a message that already arrived. | |
| inbox_id | Yes | Inbox id (uuid) to watch. | |
| timeout_seconds | No | Give up after this many seconds (default 45, max 60). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses blocking behavior, return fields (message_id, link, links), optional class filtering, and timeout. It accurately describes the tool's synchronous nature and output.
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 sentences, front-loading the core function, then use-case, then return fields. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description includes return fields and explains blocking and filtering. For a tool with 5 parameters (1 required) and a clear use case, the description covers all necessary context.
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% with descriptions for all 5 parameters. The description adds minimal extra meaning beyond the schema, mainly repeating the class option. 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?
The description clearly states the tool blocks until a link arrives and returns it, with optional class filtering. It distinguishes itself as the one-call solution for getting verification links, setting it apart from siblings like wait_for_message or get_links.
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 (after triggering an email) and mentions optional class filtering, but does not explicitly compare to alternatives or state when not to use it. The guidance is clear but lacks exclusionary context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Block until a matching message arrives in the inbox (or timeout_seconds elapses), then return its full detail. Call this right after triggering an email flow in the app under test.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Filter: `subject:term`, `from:term`, or `to:term`; a bare term matches the subject. | |
| since | No | Only consider messages received after this RFC 3339 timestamp. Omit to accept a message that already arrived. | |
| inbox_id | Yes | Inbox id (uuid) to watch. | |
| timeout_seconds | No | Give up after this many seconds (default 45, max 60). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions blocking and timeout but does not specify what happens on timeout (e.g., returns null or error). It also doesn't clarify if the message is consumed or remains in the inbox. This ambiguity affects transparency.
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 key information (blocking, matching, timeout). No superfluous words. Efficient and clear.
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?
Captures purpose, usage timing, and parameter semantics well. However, lacks detail on timeout behavior and return format (no output schema). Also doesn't address whether the message is consumed or remains. This leaves gaps for an AI agent.
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 adds value by explaining the match filter syntax (e.g., 'subject:term') and the context of the 'since' parameter. It also notes the default timeout. This enhances understanding 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?
The description clearly states the action (blocks/wait), the resource (matching message in inbox), and the result (returns full detail). It also provides context for usage, distinguishing from sibling tools like get_message or list_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?
The description explicitly advises to call this after triggering an email flow, giving clear situational guidance. It does not explicitly state when not to use it, but the context is sufficient for an AI agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Block until a message with an extracted OTP/verification code arrives, then return the code. The one-call answer to 'trigger signup, read the OTP, type it in'. Returns {message_id, best, candidates}.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Filter: `subject:term`, `from:term`, or `to:term`; a bare term matches the subject. | |
| since | No | Only consider messages received after this RFC 3339 timestamp. Omit to accept a message that already arrived. | |
| inbox_id | Yes | Inbox id (uuid) to watch. | |
| timeout_seconds | No | Give up after this many seconds (default 45, max 60). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations; description states it blocks but does not detail timeout behavior, error handling, or concurrency implications. Missing edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, front-loaded purpose. Could add minor usage guidance without significant bloat.
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?
Explains return shape, but lacks output schema. Missing details on timeout behavior, prerequisites (inbox existence), and error states.
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 covers all parameters with descriptions (100%). Tool description adds no extra parameter context, 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?
Clearly states verb 'block/wait' and resource 'OTP/verification code', with return type. Distinguishes from siblings like get_otp, wait_for_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?
Mentions signup flow but lacks explicit when-not-to-use or alternatives. Does not differentiate from wait_for_message or get_otp.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Block until a matching SMS arrives on the phone number (or timeout_seconds elapses), then return its full detail including extracted data. Call this right after triggering an SMS flow in the app under test.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Filter: `from:term`, `to:term`, or `body:term`; a bare term matches the body. | |
| since | No | Only consider messages received after this RFC 3339 timestamp. Omit to accept a message that already arrived. | |
| phone_number_id | Yes | Phone number id (uuid) to watch. | |
| timeout_seconds | No | Give up after this many seconds (default 45, max 60). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must cover behavior. It mentions blocking, timeout, and returning full detail, but lacks details on side effects or cancellation.
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 with no wasted words. First sentence states purpose and behavior, second gives usage guidance. Very concise.
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 main points: blocking, timeout, matching, return. No output schema, so return value described as 'full detail including extracted data' is adequate but vague. Fairly complete for a waiting 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% with descriptions for all parameters. The description adds 'including extracted data' but doesn't provide significant additional meaning 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?
The description clearly states it blocks until a matching SMS arrives, using specific verb 'Block' and resource 'SMS on the phone number'. It distinguishes from siblings like wait_for_message and wait_for_otp.
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 explicit usage guidance: 'Call this right after triggering an SMS flow in the app under test.' This sets clear context, though no alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Block until an SMS with an extracted OTP/verification code arrives on the phone number, then return the code. The one-call answer to 'trigger SMS verification, read the code, type it in'. Returns {sms_id, best, candidates}.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Filter: `from:term`, `to:term`, or `body:term`; a bare term matches the body. | |
| since | No | Only consider messages received after this RFC 3339 timestamp. Omit to accept a message that already arrived. | |
| phone_number_id | Yes | Phone number id (uuid) to watch. | |
| timeout_seconds | No | Give up after this many seconds (default 45, max 60). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states blocking behavior and the extracted OTP return structure ({sms_id, best, candidates}). No annotations were provided, so the description carries the full burden, and it does so well without contradictions.
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 delivering the core purpose and return format with zero extraneous information. Front-loaded with the blocking action and result.
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 description covers the main behavior, blocking, and return fields. Given the complexity of waiting for a message with extraction, it is adequate. Minor omission: no mention of timeout behavior or error conditions, but those are handled in parameter 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?
Input schema has 100% coverage with detailed descriptions for all parameters. The description adds no new parameter-level insight beyond the schema, meeting the baseline expectation but not 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?
The description clearly states the tool blocks until an SMS with an extracted OTP arrives and returns the code. It distinguishes from siblings like 'wait_for_sms' by emphasizing OTP extraction and being a one-call answer for verification flows.
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 provides a concrete use case ('trigger SMS verification, read the code, type it in') and positions it as a convenient combined operation. However, it does not explicitly state when not to use it or compare to alternatives like 'get_otp'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent delivery attempts for one webhook endpoint (status, attempts, last error) — the first place to look when events aren't arriving.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max deliveries to return (1..=200, default 50). | |
| webhook_id | Yes | Webhook endpoint id (uuid). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the read-only nature (querying delivery history) and returned fields, but does not specify recency limits or pagination. Adequate but could be more detailed.
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?
Single sentence, front-loaded with purpose and key details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should detail return value structure. It mentions fields but lacks specifics on whether it returns a list or single item, and pagination. Nevertheless, sufficient for a simple diagnostic 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 covers 100% of parameters with descriptions. Description adds minimal value beyond implying webhook_id is the endpoint identifier. 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?
Description clearly states it returns recent delivery attempts for one webhook endpoint, listing fields (status, attempts, last error) and providing a usage context ('first place to look when events aren't arriving'), distinguishing it from diagnostic siblings like test_webhook.
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 suggests using this tool for troubleshooting failed deliveries, but does not mention when not to use it or alternative tools like test_webhook for testing. Good context but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
clear_hookcreate_hookdelete_hookget_hook_requestlist_hook_requestslist_hookswait_for_hook_requestclear_inboxcreate_domaincreate_inboxcreate_keycreate_phone_numbercreate_webhookdelete_domaindelete_inboxdelete_webhookenable_webhookfollow_linkfollow_sms_linkget_attachmentget_linksget_messageget_otpget_smslist_domainslist_inboxeslist_keyslist_messageslist_phone_numberslist_smslist_webhooksrelease_phone_numberrevoke_keytest_webhookverify_domainwait_for_linkwait_for_messagewait_for_otpwait_for_smswait_for_sms_otpwebhook_deliveriesDisposable inboxes for AI agents: create, wait for delivery, and extract email content or links.
Disposable test mailboxes on a real domain: send, receive and assert on real email.
Real email inboxes for AI agents: create inboxes, catch verification codes, extract OTPs, reply.
Disposable email inboxes for AI agents — read messages and verification codes.
