socket.help

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false. The description adds meaningful context by clarifying that the destructive act rewrites the monitor's baseline to the last observed answers, which explains why it's destructive and irreversible. No mention of auth requirements or what happens to prior baseline history.

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

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

Two sentences, front-loaded with the action, then the guardrail. No filler or redundancy.

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

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

For a single-parameter mutation tool with annotations covering safety and idempotency, the description is nearly complete. The remaining gap is what the id identifies (monitor vs. change record) and what happens to the previous baseline, but the essentials to call it safely are present.

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

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

Only one parameter, id, fully documented in the schema as the resource UUID (100% coverage). The description doesn't clarify whether the id refers to a monitor or a DNS-change record, which leaves a small ambiguity, but the schema does the heavy lifting.

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

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

States a specific verb (accept) and resource (DNS changes / monitor baseline), and goes beyond the name by explaining what 'accept' actually means: promoting the last observed DNS answers to the new baseline. It doesn't explicitly differentiate from sibling pause_monitor/inspect_monitor, but the DNS-baseline framing is distinct enough.

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

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

Gives a clear precondition: use only after reviewing that the change is expected. This is real when-to-use guidance. It falls short of naming alternatives (e.g., inspect_monitor to review before accepting), so not a 5.

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

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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds real value beyond them: an authorization prerequisite, the fact that secrets are encrypted and never returned (so the value cannot be read back later), and per-plan quotas (2/25/100). It omits duplicate-name behavior and any confirmation of idempotency, which matters for a write tool.

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

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

Three tight sentences with no filler: purpose and scope first, then the credential/alternative-input mechanics, then the encryption and quota facts. Every sentence carries information an agent needs to call the tool correctly.

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 7-parameter mutation with no output schema, the description covers purpose, auth, input alternatives, secret handling, and quotas. Remaining gaps are modest: no statement of return value (e.g., a generated id) and no guidance on what happens when a name already exists.

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

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

With 57% schema coverage, the description compensates by stating the one-of relationship among uri, secret, and imageBase64, the accepted format for each (otpauth://totp, Base32, PNG/JPEG QR), and concrete image limits (1 MiB, one million pixels) that are absent from the schema. digits, period, and algorithm are left to the schema's enums and bounds, and no defaults are stated.

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

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

States a specific verb and resource ('Store a TOTP authenticator') plus a scoping condition ('for an account your human asked you to create or operate'). An agent can distinguish it from get_totp_code, list_authenticators, and delete_authenticator without opening any schema, though no sibling is named explicitly.

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

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

Gives a clear precondition ('Requires an approved workspace key') and a scope restriction limiting use to accounts the human requested. It also explains that exactly one of uri/secret/imageBase64 should be supplied. It stops short of explicit when-not guidance or naming list_authenticators/get_totp_code as follow-ups.

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

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

Exceeds what the annotations convey: the annotations only say it is a non-readonly, non-idempotent, non-destructive call, while the description adds the delivery channel (emails the workspace owner), the authorization constraint (only they can answer, signed in), and the auth prerequisite (approved workspace key). It also names the return payload (id and answerUrl) despite there being no output schema.

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

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

Three tight sentences, front-loaded with the trigger condition, then the mechanism, then the required follow-up call. The parenthetical risk examples and the 'show it in chat too' aside both carry operational value rather than filler.

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

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

Complete for a four-parameter, no-output-schema tool: the return fields, the follow-up tool, and the auth prerequisite are all covered. What is missing is what happens when nobody answers or the timeout elapses, which matters for an approval gate the agent may be blocking on.

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

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

Schema coverage is 75%, with `question`, `details` and `options` already documented in the schema, so the description is not obliged to repeat them and correctly does not. The only meaningful gap is `timeoutMinutes`, which is undocumented in both schema and description, leaving timeout behavior entirely opaque.

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

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

States a specific verb and resource ('Ask your human') and scopes it with concrete triggering actions (deploying, paying, deleting, emailing real people). The final clause routes the agent to the sibling `wait_for_approval`, so it is distinguishable from the rest of the wait_* family without opening any schema.

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

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

Gives an explicit when-to-use rule ('before a risky or irreversible step') with illustrative examples, plus the mandatory next step ('then call wait_for_approval') and a prerequisite ('Needs an approved workspace key'). An agent has everything needed to decide to call this rather than proceed.

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

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

Goes well beyond the provided annotations: it discloses that the call is subject to the same caller access, rate limits, and revision checks as real HTTP, that management tokens are insufficient, and that authorization redirects return a location. These are real operational facts an agent cannot get from readOnlyHint/destructiveHint alone, though the exact failure mode on a revision mismatch is not described.

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

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

Four tight sentences with the core action and access model front-loaded and no filler. The final clause ('authorization redirects include location') is compressed to the point of being cryptic, which slightly hurts readability without bloating the text.

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

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

For a six-parameter, destructive, no-output-schema tool, the description covers the access model and concurrency checks well but leaves the return shape, the destructive blast radius, and the meaning of revision unspecified. It is adequate to attempt a call but not complete enough to predict 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?

Schema coverage is 50%, so the description must compensate and it only partly does: it clarifies that body carries form fields and that accessToken is a userinfo bearer for owned OAuth providers. It adds nothing about revision (the concurrency token) or about how method and path interact for CRUD versus protocol routes.

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

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

States a specific verb and resource: 'Call a hosted mock route or mutate its CRUD records,' which makes the proxy/execution nature clear versus sibling management tools like create_mock_api or inspect_mock_api. It never names those siblings explicitly, so the differentiation is inferable rather than stated.

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

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

The description implies usage (execute routes as a caller would over HTTP) and gives one important exclusion — management tokens do not grant caller access — but never says when to prefer this over inspect_mock_api or create_mock_api, or what prerequisite steps are needed before calling.

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false) the description discloses the real behavioural traits an agent needs: free inboxes expire after activeDays, paid inboxes persist only while subscribed, quotas differ by plan, and retired addresses are never reused. The localPart restriction to paid plans is a genuine policy disclosure rather than a restatement of the schema.

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

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

Four compact sentences, front-loaded with the action, then constraints, then the mandatory follow-up call; nothing is filler. The opening "Requires a Free account:" reads slightly ambiguously (required prerequisite vs. free-tier offering), which is the only rough edge.

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

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

For a non-idempotent creation tool with no output schema, the definition covers prerequisites, quotas, expiry semantics and the follow-up call, which is nearly everything needed. It never states what the call returns (the created address/ID), so an agent must infer the response shape before chaining into wait_for_email.

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 earns an extra point because it explains the interaction between parameters and plan: activeDays governs free inbox lifetime while paid inboxes remain active while subscribed, and localPart only meaningfully applies on paid plans, which the schema states only tersely.

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?

"Create an owned agent email address" gives a specific verb and resource, and the lifetime/quota language makes clear this produces a persistent, owned mailbox rather than a temporary one. It does not explicitly contrast with neighbouring creators such as create_webhook_inbox or create_phone_number, but the resource noun is distinct enough that an agent will not confuse 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?

It states the prerequisite (a Free account), the per-plan quotas (1 free / 10 Pro / 50 Team), and hands off to the correct next tool: "Then call wait_for_email." Missing are explicit when-not conditions, e.g. what happens if a quota is already exhausted, but the usage context is otherwise clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description adds one genuine behavioral fact beyond annotations — that mocks expire — but never says how long they live, whether name must be unique, or how creation interacts with existing mocks. Useful but thin for a mutation tool with nested config.

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, and the core action is front-loaded before the mode-specific detail. Every clause carries information an agent needs.

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

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

This is a complex tool with 7 parameters, nested objects, and no output schema, yet the description covers only the HTTP-route and WebSocket shapes. The llm test double, crud mock, visibility and expiration timing — all present in the schema — go unmentioned, so an agent must read the schema to understand most of the tool's surface.

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

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

Schema description coverage is 43%, so the schema only partly documents the 7 parameters. The description compensates for the websocket branch by naming echo, welcome messages and exact text replies, and it explains the routes=[] coupling. It says nothing about the llm, crud, visibility or name parameters, leaving several significant gaps unfilled.

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 opens with a specific verb and resource: "Create an expiring HTTP or WebSocket mock." It also states the two modes (HTTP routes vs WebSocket), which lets an agent distinguish it from sibling call_mock_api, inspect_mock_api and delete_mock_api. It does not explicitly name those siblings, so it stops short of a 5.

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

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

The second sentence gives concrete mode-selection guidance: set routes to [] and configure echo/welcome/replies in websocket for WebSocket mocks. That is real how-to guidance for one branch, but there is no guidance on when to use create_mock_api versus call_mock_api or inspect_mock_api, and no mention of prerequisites or the lifetime of an "expiring" mock.

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

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

Goes well beyond the annotations: it discloses the authorization prerequisite ('approved workspace key'), quota and rate constraints ('Free allows 20 monitors every 5 minutes or slower'), the notification channel (email plus optional webhook), and the baseline behavior for dns (compared against its first successful baseline). It does not state what happens when the key is unapproved or whether the response returns an identifier, and the public-URL/DNS/webhook reach is in mild tension with openWorldHint=false.

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

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

Front-loads the core action and outcome, then spends the remaining sentences on per-kind semantics and plan constraints, with no filler. The kind breakdown is a dense run-on, but every clause maps to a real parameter or constraint.

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

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

For a 10-parameter creation tool with no output schema, the description covers kinds, auth, quotas, and alert routing, and hints at the heartbeat return value (pingUrl). It omits what a successful creation returns and leaves graceSeconds unexplained, which are the remaining gaps.

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

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

With only 40% schema coverage across 10 parameters, the description carries real weight: it explains expectStatus, expectText, sslDays, dnsRecordType, and that heartbeat yields a pingUrl the job calls back. graceSeconds and intervalSeconds are left essentially undefined in both places (only an indirect hint via the 5-minute floor), which keeps it out of the top band.

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

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

States a specific verb and resource ('watch something on a schedule and alert the workspace owner'), then decomposes the four monitor kinds (http/ssl/heartbeat/dns) with the distinguishing parameters for each. This is clearly separable from siblings such as inspect_monitor, pause_monitor, ping_monitor, and list_monitors.

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

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

Gives strong selection guidance among the four kinds by naming what each monitors and which parameter governs it, plus the prerequisite of an approved workspace key and the Free-plan cadence floor. It stops short of explicit when-not-to-use guidance (e.g., use inspect_monitor to modify or list_monitors to audit instead).

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

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

Annotations already declare readOnly=false, openWorld=false, idempotent=false, destructive=false, so the safety profile is partly covered. The description adds genuinely new context beyond them: that only synthetic/test identities should be used, that no real credentials should be requested, and that lifecycle management (inspect/delete) happens through other tools and configuration through resource_request. It stops short of describing what is returned (client IDs/secrets, issuer/endpoint URLs) or whether created providers persist indefinitely.

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 dense sentences, front-loaded with the capability statement, then safety constraint, then lifecycle/routing note. Every sentence carries information; the only mild awkwardness is the terse 'Inspect and delete with existing mock tools' clause, which requires the reader to infer which tools.

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 an 8-parameter creation tool with nested objects and no output schema, the description covers purpose, safety and lifecycle well but leaves the parameter space opaque, especially the scenario enum and TTL/persistence behavior. An agent could call it correctly only for the minimal required arguments and would be guessing on the optional ones.

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 0% across 8 parameters, so the description carries the full burden and largely does not meet it. It hints at 'synthetic users' mapping to the users array, but never explains headless, persistent, ttlSeconds, claims, or — most importantly — the nine-value scenario enum, whose failure-injection semantics (access_denied, invalid_pkce_verifier, rotated_signing_key, etc.) are impossible to infer from the schema.

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

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

The description opens with a specific verb+resource pair ('Create a mock OAuth 2.0 and OpenID Connect test provider') and enumerates the concrete capabilities it provisions (synthetic users, S256 PKCE, client credentials, refresh tokens). An agent can tell this apart from siblings like create_mock_api or create_email_inbox without opening the schema.

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

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

It explicitly constrains usage ('Test accounts only. Never ask for real credentials') and routes the agent elsewhere for adjacent operations ('Inspect and delete with existing mock tools; configure through resource_request kind oauth-providers'). What is missing is an explicit comparison against create_mock_api or a statement of when an OAuth provider is the right choice over a generic mock API.

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

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

Goes well beyond the annotations: it discloses the billing model (consumes a pre-paid add-on slot), the provider dependency (operator-enabled Telnyx only), and a critical operational protocol for ambiguous outcomes. Rather than contradicting idempotentHint=false, it explains how to compensate for a non-idempotent purchase using idempotencyKey, which is exactly the context an agent needs before spending money.

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

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

Four short sentences, front-loaded with purpose, then prerequisites, then the safety rule. No filler, and the most consequential instruction (never retry with a new key) is placed last for emphasis.

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

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

Covers the prerequisites, cost source, provider restriction, and reconciliation policy that matter for a money-spending mutation with no output schema. It omits what the call returns on success (a number record? a purchase id?) and any rate or quota limits, which leaves a small gap for a tool whose result the agent will likely need to reference later.

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 still adds value by tying both parameters to a workflow — the number must be sourced from inventory, and the idempotencyKey must be preserved and never regenerated on retry. It stops short of describing key format or lifetime, which the schema also omits.

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

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

States a specific verb and resource ("Buy a US number") plus the funding mechanism ("an already-paid phone add-on slot"), which cleanly separates it from list_phone_numbers and release_phone_number in the sibling set. The Telnyx-only qualifier further narrows the operation.

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

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

Gives an explicit prerequisite ("Obtain a number from the phone inventory API first") and a failure-handling rule (uncertain purchases must be reconciled, never retried with a new key). It does not name the concrete sibling tools (list_phone_numbers / release_phone_number), leaving the agent to map "phone inventory API" itself, but the when-to-use context is unambiguous.

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

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

Annotations only declare the generic non-read-only, non-destructive profile; the description adds the substantive behavior an agent needs: senders need no credentials by default, inspection always requires workspace credentials or the private token, visibility=private flips the sender requirement, and the inbox self-expires in an hour. It also discloses the plan ceiling on TTL, which is real operational context not present in annotations or schema.

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

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

Front-loaded with the purpose, then ordered by what the agent must decide (credentials model, visibility, TTL, token handling, next tool). Dense sentences such as the expiry clause pack two facts together and the pronoun "It" briefly obscures its referent, but no sentence is filler.

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

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

There is no output schema, and the description compensates by naming the two returned artifacts that matter: webhookUrl and the private inspection token that must be saved. For a zero-required-parameter creation tool with full schema coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains the security consequence of visibility=private (sender must supply X-Access-Token) and supplies plan-dependent ttlSeconds maximums (1 hour anonymous, 7 days on Free) that the schema's "from 60" does not convey.

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?

Opens with a specific verb and resource: "Create a webhook receiver." Together with the webhookUrl and inspection-token language, an agent can distinguish this from sibling creators like create_email_inbox or create_mock_api without opening the schema.

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

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

Gives clear operating context: public POST-by-default mode, private mode gated on X-Access-Token, one-hour default expiry, and an explicit next step ("use wait_for_webhook"). It does not explicitly contrast with other inbox types or state when not to create one, so it falls short of full alternative routing.

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

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

Annotations already declare destructive=true and idempotent=true, but the description adds the concrete effect ('permanently removes the stored secret') and an operational warning to preserve recovery codes. It does not describe auth requirements or downstream effects, but it adds useful behavior beyond annotations.

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

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

Three short sentences, front-loaded with the action and immediately followed by permanence and recovery-code warning. 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?

For a one-parameter delete operation with rich annotations and no output schema, the description covers permanence and a critical recovery-code precaution. It could be more complete by pointing to list_authenticators for identifying the target, but nothing critical is missing.

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

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

The sole parameter id has 100% schema description coverage ('Resource UUID.'), so the schema already carries parameter meaning. The description does not add syntax or identification guidance for id; baseline 3 applies.

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

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

The description states a specific verb and resource ('Delete an authenticator') and scopes it to accounts the human asked the agent to create or operate. It clearly distinguishes the delete action from sibling tools such as add_authenticator and list_authenticators.

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

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

It gives clear usage context (accounts the human asked the agent to create or operate) and a pre-deletion instruction to keep recovery codes. It does not explicitly route to list_authenticators for finding the id or state when deletion should not be used.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The word "Permanently" reinforces irreversibility beyond what the hints state, but the description says nothing about whether deletion cascades to associated logs/endpoints or when the token parameter is required.

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

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

A single front-loaded sentence with zero waste and no filler. It is terse to the point of omitting useful context, but nothing present is unnecessary.

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 destructive delete with rich annotations and a fully documented two-parameter schema, this is close to sufficient. The remaining gap is behavioral: cascade effects and the token requirement for anonymous resources are left entirely to the schema.

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

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

Schema coverage is 100%, with both id and token fully documented in the schema, so the baseline is 3. The description adds no additional meaning about identifier format or token usage, but it is not required to.

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

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

The description states a specific verb and resource ("Permanently delete a mock API") that clearly separates it from siblings such as create_mock_api, inspect_mock_api, and delete_monitor. It does not name an alternative, but the resource noun alone is unambiguous.

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

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

There is no guidance on when to use this versus alternatives — no suggestion to inspect first, no note about needing the token for anonymous resources, and no mention of related cleanup. Usage is only implied by the verb.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say the deletion is permanent, whether monitor history/check data is removed, whether it requires elevated permissions, or how it behaves if the ID 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?

A single front-loaded sentence with zero filler; the action and the keying parameter are stated immediately. Nothing in the sentence is wasted, though the terseness shifts the burden onto other dimensions.

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 an irreversible destructive mutation with no output schema, the description should establish permanence and post-conditions; it establishes neither. An agent cannot tell from this definition whether a failed lookup is an error or a no-op, nor what evidence of success it will receive.

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

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

With a single required parameter and 100% schema description coverage ("Monitor UUID"), the schema does the heavy lifting. The phrase "by ID" merely restates the parameter rather than adding format, scope, or ambiguity-resolution detail.

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

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

States a specific verb and resource ("Delete a monitor by ID") so the agent knows exactly what action and object are involved. It does not explicitly differentiate from siblings such as pause_monitor or inspect_monitor, but the verb-plus-resource pair is unambiguous on its own.

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

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

There is no when-to-use guidance: nothing says when to delete rather than pause a monitor, whether deletion is a prerequisite for recreation, or what preconditions must hold. The only usage signal is the name itself, which the agent could already infer without the description.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so "Permanently" restates structured data rather than adding to it. Nothing is said about error behavior for a missing/expired file, whether anonymous resources need the token, or whether deletion is immediate and irreversible beyond the stated permanence.

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 six-word sentence with the destructive qualifier front-loaded and zero filler. There is no structural waste to trim.

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

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

For a destructive, idempotent delete with full schema coverage and no output schema, the minimum is met: the agent knows what is removed and that it is permanent. However, idempotency behavior (does deleting an already-deleted file error or succeed silently) and required authorization are left entirely to the annotations and schema.

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

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

Schema coverage is 100% and both parameters are documented in-schema, including the useful distinction of token for anonymous resources, so the schema carries the burden. The description adds no meaning about the id or token usage, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Permanently delete an uploaded file"), which is unambiguous and pairs naturally with the sibling tools upload_temporary_file / inspect_temporary_file. It does not explicitly contrast itself with other delete_* siblings, but the resource noun makes the scope obvious without opening the schema.

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

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

No when-to-use or when-not-to-use guidance, no prerequisites, and no pointer to alternatives such as inspect_temporary_file before removing, or download_temporary_file if the caller actually wants the contents rather than destruction. The agent must infer everything from the name alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the bar for additional disclosure is lower. The description still adds meaningful detail by stating that the inbox's entire history is destroyed, not just the inbox record itself. It does not cover error behavior when the id does not exist, even though the annotations imply that repeated calls are idempotent.

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

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

One short sentence with no filler, and the permanence warning is front-loaded ahead of the resource. Every word earns its place, with no redundancy or structural confusion.

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 destructive, irreversible tool with no output schema, the definition is adequate but thin: it does not describe success/failure responses or what happens to dependent webhook deliveries. The schema fully documents both parameters, which offsets part of the gap. An agent can call it correctly, but must rely on annotations for the safety profile.

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%, with both the resource UUID and the optional management/inspection token fully documented in the schema. The description adds no semantics beyond that, such as what happens if a token is supplied for a workspace-owned resource. When the schema already does the heavy lifting, a 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 pairs a specific verb ("Permanently delete") with a specific resource ("an inbox and its history"), so the operation is unambiguous. It also makes clear the target is a webhook inbox rather than an email inbox through the tool name. It stops short of naming sibling tools, but the verb/resource pair already separates it from create_webhook_inbox and inspect_webhook_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 word "Permanently" signals that this is an irreversible action, which is a weak usage cue. The description never says when to choose this tool over inspect_webhook_inbox first, which prerequisites apply, or whether a token-authenticated anonymous inbox behaves differently. An agent gets no explicit routing or precondition guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful content about what the response contains, but says nothing about behavior when the ID is unknown or invalid, which matters for a lookup 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?

A single dense sentence with the action front-loaded and zero filler. The trailing list of returned fields is compact and earns its place, though the comma run-on is slightly harder to parse than a structured list.

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

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

With no output schema, the description correctly compensates by naming the fields returned, which is the right move. However it leaves ambiguous what 'availability' means, omits the missing/unknown-tool case, and does not cover how to obtain a valid toolId, so a lookup tool of this kind is only adequately served.

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

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

There is a single parameter with 100% schema description coverage ('Catalog tool ID or MCP tool name'), so the schema does the heavy lifting. The description never mentions the parameter and adds no format, case-sensitivity, or ID-resolution detail beyond the schema.

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

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

The description gives a specific verb ('Describe') and resource ('a catalog or MCP tool') and enumerates the fields returned (availability, inputs, HTTP route, MCP entry point), so an agent can distinguish it from list_tools or run_tool. It stops short of explicitly naming those siblings as alternatives.

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

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

Usage is only implied: you call it when you need details about a tool you already have an ID for. There is no guidance on where the toolId comes from (e.g., list_tools/search_tools) and no stated when-not-to-use or alternative for executing versus inspecting.

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

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

Goes well beyond the annotations by disclosing three non-obvious traits: the 64 KiB size ceiling, that the call burns a download quota, and that one-time files are destroyed afterward. The consumption/destruction language is fully consistent with destructiveHint=true and idempotentHint=false.

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

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

Four short sentences, front-loaded with what the tool returns and how big it can be, followed by auth, side effects, and the fallback. No filler or repetition of the schema.

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

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

With no output schema, the description still specifies the return encoding (base64) and size bound, and it flags the irreversible quota/side-effect behavior. An agent has everything needed to decide whether to call it and what to expect.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns an extra point by clarifying that accessToken applies only to private files and that workspace access is an acceptable substitute. That conditional framing adds meaning the schema's terse 'when required' does not convey.

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

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

States a specific verb+resource ('Download a file'), plus the output encoding and a hard size ceiling (64 KiB as base64). That is enough to distinguish it from inspect_temporary_file and delete_temporary_file, which it never names explicitly, so sibling differentiation is inferred rather than stated.

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

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

Gives a concrete when-not clause ('Use HTTP for larger files') and a precondition for private files ('need their access token or workspace access'). It does not route the agent to inspect_temporary_file when it only wants metadata, which would be the obvious sibling alternative.

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

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

Annotations already establish this as a safe, idempotent read, and the description adds substantive behavior beyond them: a 25-second wait bound per call and the four possible terminal/pending statuses. It stops short of saying what to do with each status or how many times to poll.

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

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

Two tight sentences with the wait bound and return values front-loaded; essentially no waste, though the status list could be formatted more scannably.

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

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

With no output schema, the description usefully enumerates return statuses and notes that the approved case yields the API key and MCP settings. The only gap is guidance on how to act on each status.

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

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

Schema coverage is 100% and the schema already describes deviceCode as coming from start_login, so the description adds no new meaning about the parameter. Baseline 3 applies.

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

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

States a specific action (wait for the human to approve the login) and anchors it to the sibling tool start_login, so an agent knows exactly which step of the login flow this is.

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 reference to 'the login from start_login' and 'up to 25 seconds per call' makes the call ordering and the need to re-invoke on pending clear by implication, but no explicit when-not or retry instruction is given.

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

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

Goes well beyond the readOnly/idempotent annotations: the URL expires in two minutes, is invalidated when the message or inbox is deleted, and the payload is flagged as untrusted. Those are exactly the operational facts an agent needs before planning a fetch-and-use sequence, and none of them duplicate the structured fields.

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

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

Three short sentences, each doing distinct work: capability, prerequisite plus expiry, then a safety constraint. The scoping and the security warning are front-loaded rather than buried, and there is no filler.

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

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

For a three-parameter tool with no output schema, the description covers capability, prerequisites, lifetime and safety. The only shortfall is that the return shape is described only loosely ('download URL') without saying whether it arrives as a bare string or a field in an object, which matters when there is no output schema to consult.

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 id, messageId and attachmentId are already documented. The description only adds the ownership constraint implied by 'owned email message'; it does not explain ID formats or how to obtain id and messageId. Baseline 3 applies.

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

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

States a specific verb and resource: 'Get a private attachment download URL', scoped to 'an owned email message'. This is enough to separate it from list_emails (which enumerates messages) and download_temporary_file (which handles local temp files) without opening any schema.

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

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

Supplies a concrete prerequisite ('Requires an approved workspace key') and the description plus schema point at list_emails/wait_for_email as the source of the attachmentId. It never names an alternative tool or an explicit when-not-to-use case, so the routing is clear but not exhaustive.

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

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

Goes well past the annotations (which only say it is non-read-only, non-destructive and idempotent) by disclosing the required scope (resources:write), the need for an approved workspace key, the logging of every generation, a hard rate limit of 30 per workspace per minute, and a secrecy constraint on printing codes. It even explains the return shape, including nextCode appearing only when fewer than five seconds remain.

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?

Six tight sentences with no filler, ordered from what it does, to authorization, to return values, to operational limits. The most decision-critical constraint (scope of permitted use) 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?

There is no output schema, and the description compensates by naming the returned fields and the conditional nextCode. Authorization, rate limits, audit logging, and handling constraints are all covered, so an agent has everything needed to call it correctly and safely.

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

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

Schema coverage is 100% and the single parameter is already documented as a resource UUID, so the bar is a baseline 3. The description adds genuine meaning by identifying which kind of resource that UUID must reference — a stored TOTP authenticator in the workspace — which matters in a workspace with many resource types.

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

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

States a specific verb and resource ("Generate a code from a stored TOTP authenticator") and immediately scopes it to accounts the human asked the agent to create or operate. It is trivially distinguishable from siblings like list_authenticators or add_authenticator, which list or create authenticators rather than producing a live code.

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

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

Gives strong when-to-use framing (only for accounts the human asked you to create or operate) and explicit when-not conditions (viewers and read-only keys cannot generate codes; an approved workspace key is required). It does not name an alternative route when the condition fails, so it stops short of the top band.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: a management-access authorization requirement and the fact that event history is capped at the 20 most recent items. It omits whether history beyond 20 is retrievable or paginated, which keeps it short of a 5.

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

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

Two short sentences, zero filler. The content scope comes first and the access prerequisite second, so an agent can decide from the opening clause whether this is the right tool.

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

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

With no output schema, the description does the work of telling the agent what comes back: configuration, usage, and recent traffic. That is adequate for a two-parameter read tool whose annotations cover the safety profile. The one gap is what happens past the 20-event cap, which an agent may need to know before relying on this as a complete history source.

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%, with both id and token documented in the schema itself, so the baseline is 3. The description adds only tangential meaning ('management access' loosely maps to the token parameter) and gives no syntax or format detail beyond the schema.

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

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

States a specific verb (read) and enumerates the resources returned: mock configuration, usage, and the 20 most recent HTTP calls or WebSocket events. That is far more informative than a tautology like 'inspects a mock API.' It does not explicitly distinguish itself from call_mock_api or delete_mock_api, but the read-only inspection scope is unmistakable.

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 prerequisite 'Requires management access' is stated, which is real usage guidance. However, there is no explicit when-to-use statement or routing to alternatives such as call_mock_api (to exercise the mock) or inspect_monitor (for the analogous monitor resource). Usage must be largely inferred from the name and verb.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description contributes one extra behavioral fact — that the response includes recent status events, not just configuration — but does not say how many events or over what window, and no output schema exists to clarify.

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 short sentence with no filler, and the primary action is front-loaded before the incidental return content. Nothing in it is redundant with the name or schema.

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

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

For a one-parameter read tool with full annotations and complete schema coverage, this covers the essentials: what is fetched and that status history comes along. Minor gaps remain — the meaning of "recent" and behavior for an unknown or unauthorized monitor ID — but they are small for an idempotent read.

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

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

There is a single required parameter with 100% schema description coverage ("Monitor UUID."), so the schema fully documents the input. The description adds no format, source, or lookup guidance for the ID beyond what the schema already says, which is the expected baseline when schema coverage is complete.

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

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

States a specific verb and resource ("Read one workspace monitor") plus scope (single item) and secondary content ("recent status events"), which separates it from list_monitors and delete_monitor. It stops short of naming the sibling it replaces, so differentiation is inferred from wording rather than stated.

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

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

The word "one" implies this is the single-item fetch versus the sibling list_monitors, and nothing about creation/deletion/pausing is implied. However, there is no explicit statement of when to use this instead of list_monitors or a wait_for_event-style tool, leaving routing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds two useful behavioral hints beyond that: a token is needed for anonymous resources, and the result includes remaining download allowance. It does not disclose whether inspecting itself consumes a download, which is the key risk for a quota-bearing resource.

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

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

A single front-loaded sentence with no filler. The trailing 'with its private token' reads slightly awkwardly, but every element carries information and nothing is wasted.

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

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

With rich annotations and full schema coverage, the definition is nearly sufficient for a two-parameter read tool. However, it never says what metadata is returned or whether inspection affects the remaining-download counter, which are meaningful gaps for a quota-tracked temporary resource with no output schema.

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

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

Schema description coverage is 100%, and the schema even explains when to omit the token for workspace-owned resources. The description's phrase 'with its private token' reinforces the token parameter but adds no syntax, format, or semantics beyond the schema. Baseline 3 applies when the schema already does the heavy lifting.

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

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

The description gives a specific verb and resource: read file metadata plus remaining download count, gated by a private token. That distinguishes it reasonably well from the sibling download_temporary_file (fetch contents) and delete_temporary_file (remove). It stops short of explicitly naming those siblings, so the differentiation is inferred rather than stated.

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

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

Usage is only implied: an agent can infer you call this to check a temporary file's status or remaining download quota before acting on it. There is no explicit when-to-use or when-not-to-use guidance, no mention of pairing with download_temporary_file, and no note about what happens if downloads are exhausted.

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

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

Annotations already declare readOnly=true, idempotent=true, and non-destructive, so the safety profile is covered. The description adds the meaningful fact that access can be token-based for anonymous resources, but says nothing about what the captured requests include, their ordering, or any pagination/limit 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?

A single front-loaded sentence with no filler; the verb and resource come first and the access mechanism follows. Nothing could be removed without losing information.

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

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

For a simple two-parameter read tool with rich annotations and no output schema, the description covers what it does and how access works. The remaining gap is what the returned request capture looks like, but the annotations carry most of the behavioral weight here.

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

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

Schema coverage is 100%, with the schema itself explaining both 'id' (resource UUID) and 'token' (omit for workspace-owned resources). The description echoes the token concept but adds no format or convention detail beyond what the schema already states, so the baseline of 3 applies.

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

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

The description names a specific verb ('Read') and resource ('webhook inbox and captured requests'), which clearly separates it from create_webhook_inbox and delete_webhook_inbox. It stops short of an explicit contrast with wait_for_webhook, which is the closest sibling an agent could confuse it with.

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 'using its private token' implicitly signals the anonymous-resource inspection scenario, but there is no explicit when-to-use rule, no mention of when not to use it, and no pointer to wait_for_webhook as the alternative for blocking on new deliveries.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: results exclude secrets, and there is an explicit authorization scoping rule tied to human intent. It stops short of describing return fields or pagination, which keeps it at a 4 rather than a 5.

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

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

Two short sentences, both front-loaded: what the tool returns first, the usage guardrail second. No hedging, no repetition, and every clause carries information an agent needs.

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

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

For a zero-parameter, output-schema-less list tool, the description covers purpose, the key output caveat (no secrets), and the permitted scope. Only minor gaps remain, such as whether results are paginated or what identifying fields an authenticator record carries, which an agent might want before relying on the listing.

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

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

The tool takes zero parameters with a fully closed schema (additionalProperties=false), so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly avoids inventing arguments or filters that the schema does not support.

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

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

"List workspace authenticators" gives a specific verb and resource, and "without secrets" adds an important scope qualifier that distinguishes the output from get_totp_code. It does not explicitly name the sibling tools it differs from (add_authenticator, delete_authenticator), but the list-vs-mutate distinction is evident from the verb.

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

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

"Use only for accounts your human asked you to create or operate" is a real access restriction that tells the agent when this tool is permitted, which is more than nothing. However, it gives no guidance on choosing between this and alternatives such as get_totp_code or add_authenticator, so the when-to-use-vs-alternatives dimension is only implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), so the description's contribution is the behavioral detail it adds: a hard cap of 100 messages and the fact that codes and links are pre-extracted, which tells the agent it needn't parse or fetch per-message. It does not disclose ordering or whether the read is destructive to unread state, which keeps it short of a 5.

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

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

A single sentence, front-loaded with the action and scope, followed by the returned fields. No filler, no restatement of the tool name.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the per-message fields. The remaining gaps are pagination/ordering beyond the 100 cap and whether reading mutates inbox state, both of which matter for a list tool but are minor given the size limit is stated.

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

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

Schema coverage is 100%, so both parameters (id, token) are already fully documented in the schema, including the anonymous-resource token case. The description adds nothing about either parameter, so the baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('every message in an email inbox') plus the concrete payload an agent gets back (sender, subject, text, HTML, codes, links, attachment names). This clearly separates it from wait_for_email and get_email_attachment, though those siblings are never named.

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

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

Usage is only implied: an agent can infer this is the tool for bulk inspection of an existing inbox rather than waiting for new mail or fetching a single attachment. There is no explicit 'use this when... / use X instead when...' guidance, and nothing says whether calling it consumes or marks messages as read.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description contributes one genuinely new behavioral fact — that results include current status and last message — but omits whether the snapshot is live or cached, whether results are paginated or bounded, and how an empty workspace is represented. With annotations carrying most of the burden, a 3 is appropriate.

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

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

A single sentence with zero filler, front-loading the action and scope before the return contents. Nothing in it is redundant with the tool name and nothing could be trimmed without losing information.

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

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

For a zero-parameter, read-only listing tool with rich annotations, the description covers the essentials: scope (workspace), action (list), and payload (status plus last message). The only meaningful gap is that no output schema exists and the description does not say what a monitor entry's other fields look like or how many results to expect.

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

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

The tool takes no parameters and the schema is an empty object, so there is no parameter meaning to convey; the description correctly avoids inventing any. It also does not over-promise filtering or paging options that the schema lacks, which keeps it consistent with the zero-argument contract.

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

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

States a specific verb and resource ('List the workspace's monitors') and adds what each entry carries ('current status and last message'), which goes beyond restating the name. It does not, however, distinguish itself from the closely related inspect_monitor or from other list_* siblings, so an agent must infer that this is the bulk-enumeration counterpart to the single-monitor inspect.

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

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

Usage is only implied: an agent can reasonably infer 'use this to discover monitors, then use inspect_monitor for detail,' but the description never says so, nor does it mention when a listing is inappropriate (e.g., already knowing the monitor ID). No prerequisites or follow-up routing are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds one genuine behavioral detail beyond that — that disabled providers are surfaced with enabled=false rather than omitted — but says nothing about pagination, ordering, or account scoping.

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

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

Two short sentences, zero waste, with the primary purpose front-loaded before the secondary return-value note. Nothing could be removed without losing information.

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

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

For a parameterless, annotation-covered, closed-world list call with no output schema, the description covers what is enumerated plus the notable enabled=false case. Slightly more detail on the shape of the add-on allowance result would make it fully self-sufficient.

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

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

The tool takes zero parameters, so there is no argument meaning for the description to add; the baseline for a parameterless tool is 4. Nothing in the description misleads about inputs.

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

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

The description uses a specific verb and resource ('List owned phone numbers') and adds a second payload element ('add-on allowance'), which cleanly separates it from create_phone_number and release_phone_number among the siblings. It stops short of naming an alternative explicitly, but the resource 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?

Usage is only implied: an agent can infer this is the enumeration call for provisioned numbers, but there is no stated when-to-use versus when-not, and no guidance on pairing it with related tools such as list_sms or release_phone_number.

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

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

Annotations already establish that the operation is read-only, idempotent, and non-destructive. The description adds useful operational context beyond that profile, particularly code extraction and the paid add-on prerequisite, though it leaves history limits, ordering, and empty-result behavior unspecified.

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

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

Two short sentences front-load the purpose and resource scope, then state the billing prerequisite. There is no redundant or unnecessary wording.

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

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

For a simple one-parameter read tool, the description supplies enough scope and prerequisite information to support correct invocation alongside the schema and annotations. The absence of an output schema makes the lack of result-shape or retrieval-history details more noticeable, and sibling routing remains incomplete.

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 id parameter is already documented as a phone resource UUID. The active/owned wording adds a modest eligibility constraint, but the description does not explain where to obtain the UUID or add further invocation details.

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 and resource: reading received SMS messages and extracted codes for an active owned phone number. It does not explicitly distinguish this existing-message read from the sibling wait_for_sms or list_phone_numbers 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?

The active owned-number scope and active paid add-on requirement provide concrete usage context and prerequisites. However, there is no guidance on when to choose wait_for_sms instead, or how list_phone_numbers can help supply the required resource ID.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds that coming-soon tools are not enabled, which is behavior beyond the annotations. It says nothing about result size, pagination, or ordering for a listing that could be long, leaving a real gap.

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

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

Three short sentences, front-loaded with what is listed and the availability qualifier, then the exclusion caveat, then the sibling routing. Every sentence carries information; no filler.

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

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

With no parameters and no output schema, the description should convey the shape of the return value, and 'tools ... with availability' does that at a high level along with the coming-soon caveat. It stops short of describing the entry structure or whether results are paginated.

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

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

The tool takes zero parameters and the schema is an empty closed object, so there is no parameter meaning to add. Baseline for a 0-param tool is 4, and nothing in the description muddies the no-argument call.

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

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

States a specific verb and resource (list catalog tools and MCP tools) plus the distinguishing attribute (availability). It explicitly names the sibling search_tools, so an agent can separate inventory-listing from focused lookup without opening either schema.

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

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

Provides explicit routing guidance: 'Prefer search_tools for focused results,' which gives the condition that selects the alternative. The when-to-use-this case is only implied by 'list ... with availability' rather than stated as a directive, so it falls short of a full when/when-not pair.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered by structured data. Beyond that, the description adds nothing: it does not say whether deletion is permanent, what happens when the key is absent, or whether a namespace is created/cleaned up, which matters for a destructive operation.

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

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

A single short sentence with no wasted words and the action front-loaded. It is concise but achieves that by under-specifying rather than by editing down a richer statement.

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 destructive, no-output-schema mutation tool, the description should state irreversibility and behavior on a missing key. Neither is covered, and nothing compensates for the vacuous parameter descriptions, so an agent cannot predict failure or side effects.

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 nominally 100%, so the baseline is 3, and the description does not add scope information beyond the schema. Note that the schema's own parameter descriptions ("Key.", "Namespace.") are tautological, so the pair namespace+key must be understood from naming alone—'remembered value' at least implies a namespaced store.

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?

"Forget a remembered value" implies removal of stored memory data, which is enough to distinguish it from siblings like memory_get and memory_list. However, the verb is metaphorical rather than explicit ("delete"), and the resource is described as a "remembered value" rather than naming the namespace/key store, leaving the exact target somewhat inferential.

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 no guidance on when to use this versus memory_set (to overwrite) or memory_list (to inspect), and no mention of prerequisites or state preconditions. An agent must infer entirely from the name that this is the removal path.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety and determinism profile is fully covered. The description adds nothing beyond that, notably silent on what happens when the key is absent or whether entries expire.

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

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

A single front-loaded sentence with the lookup keys placed at the end where they belong. No filler, no 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 simple two-parameter read with no output schema and full annotation coverage, this is nearly enough. The only real gap is missing-key behavior, which matters for an agent deciding whether to call memory_get before memory_set.

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

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

Schema description coverage is 100%, so the baseline is 3, but the schema's own descriptions are placeholders ("Key.", "Namespace."), and the description does not compensate with format, case-sensitivity, or namespace conventions.

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

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

States a specific verb ("Read") and resource ("a remembered value"), scoped by namespace and key. It is distinguishable from siblings memory_set and memory_delete by the read verb, though it never names those siblings explicitly.

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

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

There is no explicit when-to-use guidance and no mention of alternatives such as memory_set or memory_list. The only cue is the verb "Read", which implies retrieval but leaves routing to the agent's inference.

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

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

Annotations already declare read-only, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description usefully adds that values are omitted and that space usage is reported, but says nothing about ordering, pagination, or behavior for a nonexistent namespace.

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 compact sentence with the main action and scope front-loaded and no filler. The trailing 'and the space used' is slightly awkward but carries real information about the 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?

For a simple two-parameter read tool with rich annotations and no output schema, the description tells the agent what comes back (keys and space used) and what does not (values). That is enough to call it correctly; only listing-order and empty-namespace behavior are unstated.

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

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

Schema coverage is 100%, so both parameters are already documented; the description only restates that prefix filtering is optional and that the operation is scoped to a namespace. It adds no format, case-sensitivity, or matching-rule detail beyond the schema.

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

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

States a specific verb and resource ('List keys ... in a namespace') and clarifies scope by noting values are excluded, which separates it from memory_get. It does not name the sibling explicitly, so an agent must infer that memory_get is the value-fetching counterpart.

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

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

The phrase 'without values' implicitly signals that this is the metadata-only listing and that memory_get should be used when values are needed, and 'optionally by prefix' describes the filter case. No explicit when-to-use/when-not or named alternatives are given.

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

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

The annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely new behavioral facts: a 256 KiB per-value cap, an optional ttlSeconds, the requirement for an approved workspace key, and plan-dependent quota (5 MiB on Free). The main omission is the overwrite/upsert semantics when a key already exists, and what happens on TTL expiry.

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

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

A single dense sentence cluster that front-loads the core action and example before moving to limits and auth. Nearly every clause carries information an agent would otherwise lack; only the plan/Free-tier detail is slightly tangential.

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 4-parameter write tool with full annotations and no output schema, the description covers the key operational facts an agent needs: auth prerequisite, size limit, quota, and TTL option. Remaining gaps are limited to overwrite semantics and post-write return behavior, which are minor given the rich annotation set.

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

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

Schema coverage is 75%; namespace and key constraints are already documented in the schema, and the description's example adds a little orientation but nothing new about formats. The one undocumented parameter, ttlSeconds, is merely called 'optional' with no units confirmation, range, or expiry behavior, so the description only partially compensates for the gap.

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

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

The description states a specific verb and resource: persist a JSON value under a namespace/key pair for later sessions, and gives a concrete namespace/key example. It is clearly distinct from siblings like memory_get, memory_list, and memory_delete by implication of the name and 'remember' framing, though it never names those alternatives explicitly.

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

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

'for later sessions' implies this is for cross-session persistence, which is useful context for when to reach for it. However, there is no explicit when-not guidance, no mention of when to prefer memory_get/memory_list for reading, and no note on what happens when the key already exists.

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

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

The annotations already declare a non-read-only, idempotent, destructive mutation in a closed world. The description adds that the monitor itself is not deleted, which is useful, but it does not explain what pausing actually affects (e.g., event delivery, alerts) or any permission 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?

It is a single, front-loaded sentence with no filler. Every phrase contributes to purpose or scope.

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

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

For a simple two-parameter toggle with annotations and no output schema, the description covers the core action and non-deletion guarantee. However, it leaves gaps around side effects, permissions, and explicit parameter semantics for 'paused.'

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

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

Schema coverage is only 50%, with 'id' documented as Monitor UUID but 'paused' left undocumented in the schema. The description's 'Pause or resume' gives implied meaning for the boolean, but it does not explicitly map true/false or add operational detail beyond that.

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

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

The description states a specific verb pair ('Pause or resume') and resource ('workspace monitor'), and it immediately distinguishes the operation from deletion with 'without deleting it.' An agent can tell this is a state-toggle tool rather than create/delete/inspect.

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

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

The phrase 'without deleting it' implies the relevant alternative is delete_monitor, but it does not explicitly say when to pause versus delete or when to choose pause over other monitor operations. Usage is inferable but not richly guided.

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

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

Annotations declare non-read-only, idempotent, non-destructive, closed-world, but the description adds a genuinely important disclosure not in the annotations: the token is a bearer secret and anyone holding it can report a heartbeat. It stops short of saying what a failure report triggers (e.g., alerting) or how an invalid token is handled.

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

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

Three short sentences, front-loaded with the action, then the parameter clarification, then the security caveat. No redundant restatement of the tool name or schema types; every sentence adds information.

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

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

For a two-parameter, no-output-schema tool, the description covers the action, the identifier ambiguity, and the security model. Nothing an agent needs to invoke it correctly is missing, and return values need not be described without an output schema.

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

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

Schema coverage is only 50%, with the `failed` boolean having no schema description at all, so the description must compensate. It does so for `token` by disambiguating it from the monitor UUID and locating it in the pingUrl; the success/failure framing implicitly maps to the `failed` flag, though that mapping is never made explicit.

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

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

States a specific verb and resource: 'Report success or failure for a heartbeat monitor.' This is immediately distinguishable from siblings like create_monitor, pause_monitor, and inspect_monitor, which manage rather than ping a monitor.

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 context for calling it is clear: report a heartbeat (success or failure) for a monitor with a known ping token. No exclusions or named alternatives are given, so an agent must infer that monitor lifecycle operations belong to the create/pause/inspect siblings.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the business-level consequence the annotations cannot convey: provider billing stops and the action 'cannot be undone'. It does not describe what happens to the number's messages or state after release, which is the remaining gap for an irreversible 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 sentences, both load-bearing: the first defines the action and its effect, the second carries the irreversibility warning and disambiguation. The irreversible warning is front-loaded before the clarifying negative.

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

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

For a one-parameter irreversible mutation with no output schema, the description covers effect, irreversibility, and the main confusion vector. Slightly incomplete in that post-release behavior (e.g., idempotent re-release, fate of associated resources) is left to annotations and inference.

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

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

Only one parameter exists and schema description coverage is 100% ('Phone resource UUID'), so the schema fully documents it. The description adds no format, lookup, or sourcing guidance for obtaining that id, so baseline 3 applies.

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

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

States a specific verb and resource ('Release an owned number at Telnyx') plus the consequence ('stop its provider billing'), and explicitly separates it from a nearby confusable action (cancelling the paid Dodo add-on). An agent can distinguish it from create_phone_number and list_phone_numbers without opening a schema.

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

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

Gives a clear exclusion ('do not interpret it as cancelling the paid Dodo add-on'), which prevents the most likely misuse. It does not name a positive alternative such as list_phone_numbers for discovery or describe prerequisites (ownership check), so it stops short of full when/when-not/alternatives coverage.

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

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

Annotations already declare non-readonly, destructive, idempotent, and closed-world behavior. The description adds meaningful operational constraints: authenticators are limited to human-requested accounts, config.reset restores defaults, mail reading stays private, and deliveries reads forwarding history.

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 four sentences organized by resource and action, with no obvious filler. It is dense and compresses several constraints into long clauses, but it remains front-loaded and usable.

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

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

For a 10-kind, 13-action tool with 8 parameters and no output schema, the description leaves major gaps: four kind enum values are never mentioned, most parameter behavior is undocumented, and return/response behavior is not described. It covers several important special cases but is not complete enough for reliable invocation across the full tool surface.

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

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

Schema description coverage is only 25% across 8 parameters, with only id and token documented in the schema. The description names some actions and resource types but does not explain kind enum values such as oauth-providers, status-pages, scheduled-jobs, or smtp-inboxes, nor does it clarify persistent, ttlSeconds, visibility, or config shape.

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

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

States the verb 'Manage' and enumerates resource types including webhook, email, mock API, file, authenticator, and mock MCP resources through HTTP lifecycle routes. It is clear enough to understand the tool's domain, but it does not clearly distinguish the generic resource_request route from dedicated sibling tools such as create_webhook_inbox or list_emails.

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 action-specific guidance for authenticators, mock calls/history, webhook response/forward, deliveries, and email lifecycle operations. However, it does not say when to use this generic tool versus the many dedicated sibling CRUD tools, so tool selection remains partly inferred.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false and idempotentHint=false, so the mutation profile is partly covered. The description adds genuinely new behavioral context: 'Hosted quotas apply' (a rate/usage limit) and 'Music returns download URLs' (a return-value quirk) — useful since there is no output schema. However, it says nothing about what a failed run looks like, whether repeated runs are safe, or what executing an arbitrary utility can affect, which matters for a non-idempotent dispatcher.

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

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

Four short sentences, front-loaded with what the tool does, followed by the discovery prerequisite and two caveats. Dense and largely waste-free, though the domain list in the first sentence is long and partially redundant with the catalog itself.

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 generic dispatcher with nested objects, 5 parameters, 40% schema coverage and no output schema, the description covers purpose, discovery flow and quotas but leaves the file/files/options semantics and general return shape unaddressed. It is adequate to start the discovery flow but not complete enough to invoke confidently across the catalog's range.

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

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

Schema coverage is only 40%, with toolId and input documented in the schema while file, files (nested array, max 20) and options (string map) are undocumented. The description mentions discovery of 'inputs' via describe_tool but never explains the file/files/options parameters or their interaction, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource: 'Run a utility from the complete catalog', then enumerates domains (developer data, test fixtures, images, PDF, audio, video, email inspection, DNS/network). This clearly separates it from discovery siblings like search_tools, describe_tool, and list_tools. It stops short of naming the execution mechanism (toolId dispatch) explicitly, but the purpose is unmistakable.

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

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

Gives an explicit prerequisite workflow: 'Find inputs with search_tools and describe_tool', which tells the agent to discover before invoking. It also carves out an exclusion ('Hosted resources use dedicated tools'), steering the agent away from this tool for those cases. No error-handling or retry guidance, so it is not a full 5.

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

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

The annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavior: a 25-match cap on results, the existence of 170 tools in 12 categories, and the fact that resources/utilities appear with their MCP entry point. It still doesn't say how matches are ranked or what happens to results beyond the cap.

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 opening sentence front-loads scope and size, and the closing pointer to describe_tool is well placed. The middle sentence ('Resources and utilities include availability and their MCP entry point') is grammatically awkward and slightly hard to parse, but nothing is wasted.

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

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

With only one optional parameter and no output schema, the description carries the burden of explaining results, and it does state the match cap and the kinds of entries returned. It is adequate for a single-parameter search tool, with the only real gap being result ordering and how truncation affects discovery.

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

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

Schema description coverage is 100%, so the query parameter's meaning and the empty-query behavior are already documented in the schema. The description's mention of 'up to 25 matches' is consistent but adds little the schema doesn't already convey.

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 and resource ('Search all 170 catalog tools across 12 categories, plus native MCP tools'), so the agent knows exactly what corpus is being queried. It does not, however, differentiate itself from the sibling list_tools, which appears to overlap in function, leaving the agent to infer which to pick.

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 points forward to describe_tool for input schemas and implies keyword-based lookup, which is useful next-step guidance. But it never states when to use this versus list_tools or describe_tool, nor does it mention when-not to use it (e.g., for known tool names).

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

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

Adds substantial behavior beyond the annotations: monthly/daily quotas per plan, recipients-per-message caps, idempotency key reuse rules, replyTo threading semantics, and the fact that suspension and suppression cannot be bypassed by retrying. The annotations only declare mutation/idempotency/open-world status; the description explains what those mean operationally.

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

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

Front-loaded with purpose and prerequisite, then quotas, then idempotency and threading constraints. Dense with numbers but each sentence carries operational information; the quota sentence is slightly crowded but not wasteful.

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

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

Covers the preconditions, rate limits, idempotency contract, and threading behavior an agent needs before sending. No output schema exists, so a brief note on return value (message ID) is the only meaningful omission; the 'id' parameter's role as the source inbox is implied rather than stated explicitly.

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

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

Schema coverage is already 86%, so the baseline is 3. The description still adds value by clarifying that idempotencyKey must be unique and reused only for identical-message retries, that replyTo is a received message ID used for threading, and by stating per-message recipient caps that complement maxItems.

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

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

States a concrete verb and resource — sending email from an owned socketspace.xyz inbox — and immediately scopes it with the 'operator-enabled' precondition. This is clearly distinguishable from siblings like create_email_inbox or list_emails.

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

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

Gives clear eligibility context: owned inbox, operator-enabled, verified owner email for the Free tier. It does not name alternatives (e.g., wait_for_email for receiving, list_emails for reading), so an agent gets strong preconditions but no explicit routing to a sibling.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, so the description's job is to add operational detail — it does, with the 200-599 status range, the 0-5000 ms delay cap, the 16 KiB body limit, and the reset behavior that restores a default JSON receipt. It still doesn't say whether omitted fields are preserved or cleared on a partial update, which matters for a mutating configuration call.

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

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

Two tight sentences, front-loaded with the action and followed by a resettable default. The parenthetical parameter inventory is dense but every clause carries a constraint; only minor cost is that headers and delayMs are packed into a long list.

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 an eight-parameter, nested-object mutation tool with no output schema, the description covers the behavioral limits and the reset path well. The remaining gap is the update model (partial merge vs full replacement) and any auth expectations for anonymous resources, which an agent would need to call this correctly in edge cases.

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

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

Schema coverage is only 38%, so the description carries real weight: it supplies the status range, delayMs bound, body size cap, the allowed contentType values, and the 'X- headers' prefix constraint that the schema does not express. It says nothing about the id or token parameters beyond what the schema already documents, and doesn't clarify merge-versus-replace semantics for body or headers.

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 opens with a concrete verb and object: 'Choose what a webhook inbox answers senders with', naming the resource (webhook inbox) and the effect (the reply sent to senders). It is distinguishable from siblings like create_webhook_inbox and inspect_webhook_inbox, though it never names them explicitly.

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

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

Usage is only implied: you call this to configure an existing inbox's canned response, and reset:true is the escape hatch back to defaults. There is no statement of prerequisites (ownership vs token-based anonymous resources), no guidance on when to use this versus inspect_webhook_inbox or create_webhook_inbox, and no exclusions.

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

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

Annotations only declare the generic profile (not read-only, not idempotent, non-destructive), so the description carries the real burden and does it well: it discloses the return payload (link, code, deviceCode) and the fact that a human must approve in a browser. The explicit 'Never ask the human to paste an API key into the chat' adds a security-relevant behavioral rule not present in annotations.

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

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

Three short sentences, front-loaded with the purpose, then the return shape, then the safety rule. Nothing is redundant and each sentence adds information an agent needs.

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

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

With no output schema, the description correctly explains what comes back and what to do with deviceCode. It leaves the intermediate approval step (e.g., wait_for_approval) implicit, which is a minor gap for a multi-step auth flow.

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

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

Schema description coverage is 100% and both parameters are optional, so the schema already explains name and client with examples. The description adds no further meaning about these parameters, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Connect this agent to its human's socket.help workspace') and immediately names the sibling that continues the flow ('a deviceCode for finish_login'). An agent can distinguish it from finish_login and wait_for_approval without inspecting any schema.

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

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

Clearly establishes the situation in which to call it (bootstrapping workspace access without an API key) and routes the follow-up to finish_login. It does not state exclusions or what to do if a workspace connection already exists, so it stops short of full when/when-not guidance.

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

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

Annotations only say it is a non-read-only, non-idempotent, non-destructive, closed-world call; the description adds real behavior: a 72-hour lifetime, the anonymous feature set granted, that a claim link is produced for a human, and that email functionality is gated on an approved workspace key. It does not say what happens at expiry or whether repeat calls mint additional keys, which is relevant given idempotentHint=false.

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

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

Front-loaded with the gating condition before the capability, then the alternative and the constraint. Dense and nearly waste-free, though the first sentence's colon construction packs a lot into one clause.

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 purpose, precondition, alternative, key lifetime, feature scope, and the email constraint — ample for a two-optional-parameter tool with no output schema. It stops short of explaining how the returned key should then be used or what the response contains, but the claim-link phrasing implies the return value well enough.

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

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

Schema coverage is 100%, so both properties are already documented. The only added semantics is the effect of passing humanEmail ('Pass humanEmail to notify them'), which slightly extends the schema's 'Optional address to tell your human about the trial' but adds little new meaning. Baseline 3 applies.

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

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

States a specific verb and resource ('get a 72-hour trial key') plus concrete scope ('anonymous limits: webhooks, mocks, files, utilities') and the accompanying artifact ('a claim link for your human'). It is clearly distinguishable from the sibling start_login, which is named directly.

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

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

Gives an explicit precondition ('Only if no human is available right now'), an explicit preferred alternative with the condition that selects it ('Prefer start_login when a human can approve'), and an extra constraint ('Email requires an approved workspace key'). An agent has no ambiguity about when to call this versus start_login.

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

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

The description adds genuinely useful behavior beyond the annotations: the 64 KiB ceiling and the one-hour / 100-download expiry policy. Since annotations already declare readOnlyHint=false, destructiveHint=false and non-idempotency, the remaining gap is the consequence of expiry or name collisions (whether a re-upload under the same name overwrites) and the result of the call, which are not disclosed. That lands just above the baseline the annotations set.

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

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

Three short sentences, the hard limit front-loaded, and the escalation path last. No filler and nothing repeated from the schema beyond what is needed to set the constraint.

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

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

There is no output schema, so the description is the only place an agent could learn what an upload yields — an identifier, URL, or handle needed for the sibling inspect/download/delete tools — and it says nothing about the return. Everything about the write itself (size, format, expiry) is complete, but the post-call workflow is unspecified.

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

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

Schema coverage is 75%, and the description reinforces the most error-prone constraint by tying the 64 KiB cap to the base64 parameter and revealing the tool-level default of 100 downloads that the maxDownloads parameter can override. The visibility parameter has no description in the schema and none here, leaving one parameter's semantics unstated.

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 opens with a specific verb and resource ("Upload a file") and immediately bounds it with a 64 KiB limit and base64 encoding format, so an agent knows exactly what operation this performs. It implicitly separates itself from download_temporary_file/delete_temporary_file by the upload verb, but it never names those siblings to clarify the workflow split.

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 closing sentence "Use HTTP for larger files" is an explicit exclusion that routes the agent away from this tool when the payload exceeds 64 KiB. It does not, however, say when to prefer this tool over the sibling inspect/download tools or what to do after upload, so the guidance stops short of full routing.

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

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

Goes well beyond the annotations (readOnly/idempotent/non-destructive/closed-world) by disclosing that the call blocks, the exact terminal statuses ('answered' with answer and optional note, 'expired', or 'timedOut: true'), the default and maximum timeout values, and the retry semantics for continuing to wait. This is precisely the behavioral context an agent needs before making a blocking call.

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

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

Three compact sentences, front-loaded with the blocking behavior, then return values, then the timeout/retry rule, then the safety directive. No redundant or filler wording; every clause carries actionable information.

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

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

With no output schema, the description carries the full burden of describing return values and does so completely (three possible outcomes plus the answer/note payload). Combined with the timeout guidance and the do-not-proceed rule, nothing an agent needs to invoke and interpret this tool correctly is missing.

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

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

Schema coverage is 50% — the schema documents 'id' but leaves timeoutSeconds bare. The description compensates by stating the default (25) and the hard maximum (30) for timeoutSeconds, which is the key constraint an agent would otherwise guess wrong on. It does not restate the id semantics, but the schema already covers that.

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

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

States a specific verb and effect ('Block until your human answers an ask_human request'), tying the tool directly to the ask_human sibling and making clear this is the wait half of that pair rather than the request half. An agent can distinguish it from wait_for_email/wait_for_sms/wait_for_webhook by the 'human' subject.

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

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

Gives clear context for use: it follows an ask_human request, it should be re-called to keep waiting after a timeout, and it explicitly warns 'Do not proceed without an answer.' It does not spell out a when-not case (e.g., what to do if ask_human was never called), but the usage path is unambiguous.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the non-obvious behaviors that matter here: the call blocks, returns timedOut: true after timeoutSeconds (default 25, max 30), and orders verification links first in the returned messages. These are exactly the traits an agent needs to plan around a blocking call, and nothing contradicts the annotations.

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

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

Three tight sentences, front-loaded with the blocking behavior, then the continuation parameter, then the timeout contract. Every clause carries actionable information with no filler.

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

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

With no output schema, the description does the necessary work by describing the return shape (messages with extracted codes and links, link ordering, timedOut flag). It stops short of covering failure modes such as invalid tokens or unknown message IDs, which is a minor gap for a four-parameter blocking tool.

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

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

Schema coverage is 75%, and the description compensates for the one gap: timeoutSeconds has no schema description, but the description supplies its default (25) and cap (30). It also restates the purpose of 'after' in operational terms (last message ID seen), adding intent beyond the schema's 'only newer messages are returned.'

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 opens with a specific verb and resource: 'Block until the email inbox receives a message, then return new messages with extracted one-time codes and links.' The blocking/waiting semantics plus the OTP-and-link extraction clearly separate it from siblings like list_emails and wait_for_sms.

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 tells the agent how to use the tool across calls: pass 'after' with the last seen message ID for newer messages, and call again after a timeout to keep waiting. What's missing is an explicit contrast with list_emails (when to poll the list instead of blocking), so usage context is clear but the alternative isn't named.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, yet the description still adds real behavioral context: a hard 30-second cap shared with a per-caller wait limit, a per-source cursor model, and the return shape (events with cursors, or timedOut). It also flags environment constraints (SMS needs an active phone add-on; phones=false on this server; SMS stays readable during provider outages) that annotations cannot express.

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

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

The core capability and return contract are front-loaded and dense with useful detail, but the tail end drifts into environment trivia ('This server reports phones=false; scheduled job sources are enabled') and terse jargon ('Expired/denied approval is never permission') that costs reading effort without clear payoff.

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

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

For a read-only polling tool with no output schema, the description covers what matters: the wait window, the multiplexed source model, cursor semantics and the timeout return value. Gaps remain on event payload shape, ordering across sources, and whether consumed events are re-returned on a subsequent wait with the same cursor.

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 schema description coverage reported at 0%, the description partly compensates by enumerating the per-source shape (kind, id, optional token, after cursor) and noting the 1–10 source bound. However, it says nothing about timeoutSeconds beyond the 30-second ceiling already encoded as a schema maximum, and does not explain the default wait behavior or what happens when a source yields no events.

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

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

The first sentence gives a specific verb and resource: wait once for any of 1–10 sources spanning webhook, email, approval, job and SMS kinds. The multiplexed scope implicitly distinguishes it from the single-kind siblings (wait_for_webhook, wait_for_email, wait_for_sms, wait_for_approval), but it never names those siblings to make the distinction explicit.

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

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

Usage rules are scattered rather than front-loaded: check /api/capabilities phones before creating a phone number, email events exclude sent mail, and an expired/denied approval is never permission. There is no explicit statement of when to pick this multi-source wait over the single-kind wait tools, so the selection guidance is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the bar is lower, and the description still adds real behavior: it blocks for up to 30 seconds, it is cursor-driven via a prior message ID, and it silently yields nothing for paused or pending numbers. What it does not disclose is what the call returns on timeout versus on message arrival.

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

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

Three short sentences, front-loaded with the duration limit, then the cursor instruction, then the precondition. No filler or redundancy.

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

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

For a three-parameter read-only tool with no output schema, the definition covers the timing bound, the cursor, and a key failure precondition. The notable remaining gap is the return shape on success versus timeout, which with no output schema the description would need to supply.

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

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

Schema coverage is 67%, with timeoutSeconds undocumented in the schema; the description covers that gap by indicating a default 30-second wait. It also restates 'after' as the last message ID, but says nothing about the required 'id' beyond what the schema already provides, so it only partially compensates.

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

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

States a specific verb and resource ('Wait ... for inbound SMS') with a stated ceiling of 30 seconds, which distinguishes it from list_sms polling. It never names the sibling it replaces, so the differentiation is implicit rather than explicit.

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

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

The 'Pass the last message ID as after' line implies a long-poll-after-listing pattern, and the paused/pending caveat tells the agent when the call is futile. There is no explicit statement of when to prefer this over list_sms or wait_for_email, so usage is only implied.

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

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

Annotations already declare this a safe, idempotent, non-destructive read. The description adds behavior the annotations cannot convey: the call blocks, times out after a default of 25s (max 30s), and signals expiry via 'timedOut: true' rather than an error. It does not discuss what happens to requests that arrive between calls beyond the 'after' cursor, but the latency and timeout semantics are the critical missing pieces and they are covered.

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

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

Three tight sentences with the blocking behavior front-loaded, then the cursor parameter, then the timeout/retry contract. No filler, and each sentence carries information an agent needs to drive the polling loop.

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

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

There is no output schema, so the description carries the return contract; it names the two things that matter (the new requests and 'timedOut: true') but does not sketch the shape of a returned request object. For a four-parameter long-poll tool with full annotation coverage, that is a small remaining gap rather than a blocking one.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds real meaning: it explains 'after' as 'the last request ID you have seen' (schema only says 'requests captured after it'), and supplies the default timeout of 25 seconds, which the schema's '1 to 30 seconds' description omits.

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

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

States a specific verb and blocking behavior ('Block until a webhook inbox receives a request') plus the resource returned ('the new requests'). The webhook-inbox scope distinguishes it from the other wait_for_* siblings (wait_for_email, wait_for_sms, wait_for_event) and from inspect_webhook_inbox without needing to open any schema.

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

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

Gives concrete usage guidance: pass 'after' with the last seen request ID to avoid re-reading old requests, and call again after a timeout to continue waiting — effectively describing the long-poll loop. It does not name an alternative for non-blocking checks (e.g. inspect_webhook_inbox), so it falls short of explicit when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond them by stating that even the "approvals" section is read-only and cannot perform the approval, preventing a plausible misuse. It says nothing about output shape or pagination, which keeps it from a 5.

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

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

Two short sentences, both front-loaded: the capability first, the boundary second. No filler, and the restrictive clause immediately follows the enumeration it qualifies.

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

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

For a one-parameter, no-output-schema, annotation-covered tool this is close to sufficient, but the agent still cannot tell what each section yields or how "approvals" differs from the ask_human and wait_for_approval siblings. A short per-section gloss would close the remaining gap.

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

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

Schema coverage is 0% and the single enum parameter carries five values with no field-level documentation, so the description must compensate. It roughly maps the enum values to resources (agents, activity, plans, usage, approvals), but the correspondence is loose — "human questions" for "approvals", "plan limits" for "plans" — and it never says what each section actually returns.

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?

"Read" plus an enumerated resource list (workspace agents, MCP activity, plan limits, usage, human questions) tells the agent this is a read-only multi-section viewer. The negative clause further pins its identity against siblings like wait_for_approval and ask_human, though the phrase "human questions" does not cleanly map to the enum value "approvals".

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 when-not-to-use guidance: it cannot approve agents, answer questions, or manage billing, which steers the agent away from misusing it for mutations. It stops short of naming the correct alternatives (e.g., wait_for_approval or ask_human), so routing is implied rather than prescribed.

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