Tillpad

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

No annotations exist, so the description carries the full burden and does so: it discloses no charge / no quota spend, a 10-minute single-use code, that a code is sent whether or not an account exists, the exact auth prerequisite (Bearer tp_… required before any tool runs), and the token-based auth for the follow-up billing 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?

Front-loaded with purpose and the step sequence, and most sentences carry unique operational value. The generic MCP auth line ('Authorization: Bearer tp_… before any tool runs') is boilerplate that applies to every tool and dilutes an otherwise dense, well-ordered description.

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 fully by enumerating the return payload (verificationRequired, bootstrapToken, accountId, expiresIn, next, machinePay with url/sku/amount). Auth, sequencing, alternatives, and follow-up calls are all covered, so an agent needs nothing else.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by tying the parameters to the two-call workflow and by explaining code behavior (emailed regardless of account existence, 10-minute expiry, single use). It does not add anything about the optional 'label' parameter, which keeps it from a 5.

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

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

States a specific verb and resource — 'Start zero-human onboarding from an email address' — and immediately names the former name (agent_bootstrap) plus the sibling tools it feeds into (create_api_key, manage_billing). An agent can distinguish it from every sibling 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 explicit two-step sequencing ('Step 1: call with email', 'Step 2: call again with email and code'), states when to avoid this tool ('When you have no tp_ key yet, use REST POST /api/agents/bootstrap instead'), and routes the agent onward to manage_billing and create_api_key.

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

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

With no annotations provided, the description carries the full burden and does so well: it declares the Pro-subscription prerequisite, the ACL check (support_contact), that no quota is spent, the exact return shape ({ok:true}), and explicitly enumerates what it does NOT touch (billing, storage, inboxes). That is unusually complete side-effect disclosure.

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

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

Front-loaded with the action and the qualifying condition, then each subsequent sentence carries distinct information (delivery, return value, prerequisites, non-effects) with 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 two-parameter tool with no output schema, the description supplies everything an agent needs: preconditions, the return value, and the boundaries of its side effects. Nothing material is missing.

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

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

Schema coverage is 100% and both parameters are already documented with required flags and purpose, so the baseline is 3. The description adds only that subject/message are 'sent to the Tillpad team', which is marginal value 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+resource ('Email Tillpad support') and scope ('from a Pro account'), with no sibling in the list doing anything similar. An agent can immediately tell this is the support-contact channel rather than any inbox/billing/document tool.

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

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

Gives clear qualifying context — must be an active Pro account, and replies are routed to the account email — so the agent knows when this tool is applicable. It does not name an alternative path for non-Pro accounts or state explicit exclusions, which keeps it short of a 5.

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

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

With no annotations, the description carries the full behavioral burden and does so well. It discloses that the tool writes a key row, returns the secret once, returns specific metadata fields, spends no quota, sends no email, applies run-key TTL and wipe defaults, and enforces ACL allow-list rules.

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 dense but front-loaded and every sentence carries operational value: prerequisites, return values, side effects, defaults, ACL rules, and the former name. 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 7-parameter, mutation-like tool with no annotations and no output schema, the description is complete enough. It covers authorization, side effects, return behavior, key defaults, and the non-obvious ACL semantics that an agent would otherwise miss.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema, especially that tools is an ACL allow-list of per-operation names, not merged MCP tool names, and that manage_kv action=put requires kvp_put or an omitted list.

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 precise verb and resource: minting run or sub API keys from the calling account tp_ key. It distinguishes the two key kinds and notes that account keys cannot be minted here, giving an agent enough to separate it from unrelated sibling tools.

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

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

It gives clear prerequisites: the caller must have kind=account and an active plan. It also mentions the related cleanup tool finish_run for wiping a run key early, but it does not explicitly contrast create_api_key with alternate creation paths or state when not to use it.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses that the tool is read-only, performs no writes or quota spend, sends no email, does not consult ACL, and returns allowed/would402/amount/budget. The 402/429 outcomes and legacy budget_estimate equivalence are also explained.

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 dense, front-loaded with the purpose and return shape, and every sentence adds actionable context: return fields, rag_index special case, safety profile, alternative tool, target tools, and migration note. 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 preflight estimator with no output schema and no annotations, the description supplies the return keys, usage context, behavioral constraints, and sibling routing. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly, including kind enum values and the rag_index handling of textLength/byteLength. The description's rag_index note is largely redundant with the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: predict whether a future meter spend would be rejected with 402 or 429 before calling a write or search tool. It distinguishes itself from get_usage by naming that sibling and from write/search siblings by naming them as targets to preflight.

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

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

Explicitly says when to use it (before manage_kv, index_document, search_documents, or read_inbox_message raw/attachment) and names get_usage view=budget as the alternative for seeing remaining budget. It also clarifies it is read-only and does not spend quota.

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

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

With no annotations, the description carries the full burden and does well: it discloses that stored data is deleted, that the ACL run_finish is checked, that there is no usage-meter spend and no email, and that a signed receipt is returned. It stops short of stating irreversibility or any confirmation/undo behavior, 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?

Four short sentences, front-loaded with the core action and its data-destruction semantics, followed by constraints and alternatives. The trailing 'Former name: run_finish' is useful for tool discovery but slightly less essential; otherwise there is no waste.

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

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

No output schema exists, but the description names the return value (signed wipe receipt), and with no annotations it covers permissions, side effects, and alternatives. A note on irreversibility or post-conditions would make it fully complete.

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

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

The tool takes zero parameters, so the schema-side burden is nil and the baseline is 4. The description correctly does not invent parameter details, and the 'run key' scoping is conveyed through context rather than an input field.

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 ('Wipe every namespace bound to this run key') plus the return artifact (signed wipe receipt), and explicitly scopes it to run keys only. It is clearly distinguishable from siblings like manage_kv and the implicit TTL-based wipeOnExpire.

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

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

Gives explicit routing rules: use manage_kv action=delete to remove a single key, or let wipeOnExpire clear a run key at TTL. Combined with the constraint 'Valid only for a run key', the agent has clear when-to-use and when-not-to-use guidance.

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

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

With no annotations present, the description carries the full burden and does so: it declares read-only semantics ('no writes, no deletes, no quota spend, no email'), discloses the required ACL ('Checks ACL inspect_storage'), and notes the former name for alias resolution. This is unusually complete behavioral disclosure for an annotation-free 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 sentences, front-loaded with what it returns, then the read-only/ACL guarantees, then the sibling routing. Every clause earns its place, including the former-name alias hint.

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

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

No output schema exists, so the description must describe return values, and it does at an appropriate level of abstraction (namespace names, key counts, file/vector inventory). With zero params and covered ACL/read-only behavior, nothing material is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the baseline rule for parameterless tools this is a 4. No parameter-level confusion is possible.

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 ('Summarize storage for this account') and immediately enumerates the return contents (namespaces, key counts, file/vector inventory). It distinguishes itself from siblings by naming manage_kv and list_files as the tools for the narrower operations.

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

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

Explicitly routes to alternatives with their exact selectors: 'manage_kv action=list' for paging keys in one namespace and 'list_files view=files' for file rows. It also states the scoping condition ('narrowed to the key's namespace allow-list when one is set'), so an agent knows both when to use this tool and when to use 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?

With no annotations, the description carries the full burden and does well: it explicitly declares the read-only profile ("no writes, no deletes, no quota spend, no email") and discloses an auth nuance most tools omit ("ACL is not consulted; usage_get, usage_periods_list, and budget_get were ungated reads"). It falls short of a 5 only because it says nothing about rate limits, error behavior, or failure modes.

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 and dense, with the three views presented in a consistent pattern and the read-only/safety note placed after the functional content. The repeated "Returns X, Y, Z" cadence is slightly mechanical and longer than strictly necessary, but every sentence carries usable information.

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

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

With no output schema, the description compensates by enumerating what each view returns (usage totals/budget view/current flag; periods/hasMore/currentPeriodYm; budget/keyBudget), which is the key missing structured data. It is nearly complete, lacking only error/edge-case behavior for an unknown view or empty period.

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 spells out each parameter's meaning, defaults, and cross-view ignoring (e.g. limit default 12/max 100, cursor format). The description largely restates that information rather than adding new semantics, 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 ("Read this account's usage and quotas") and immediately decomposes the resource into three named views (summary, periods, budget) with their scopes. Naming estimate_usage and manage_billing as the adjacent tools makes it distinguishable from siblings without opening a schema.

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

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

Gives explicit conditions per view: view=summary for one calendar month with the periodYm-omit rule, view=periods to page stored months, view=budget for quotas and checkout URLs. It also names the alternatives and their trigger points ("Choose estimate_usage before a spend, and manage_billing to pay"), which is exactly the routing an agent needs.

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

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

With no annotations, the description carries the behavioral burden well: it discloses capacity preflight, metering (1 kvp_ops), ACL checks, and return fields. It doesn't mention rate limits, idempotency, or failure modes, but covers core behavior.

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

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

The description is dense and front-loaded with the core action, then mode-specific details and cross-references. It's appropriately sized, though slightly crowded with parenthetical former ACL names.

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

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

Given no output schema and no annotations, the description is complete: it covers both modes, ACL requirements, metering, return values, and points to related tools. An agent has enough to invoke correctly.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema. The description adds some context about 'kind' defaults and 'title' behavior, but largely repeats what the schema already provides. 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 states a specific verb+resource: 'Add UTF-8 text to the RAG index.' It clearly distinguishes the two modes (file vs note) and their ACL checks, but doesn't fully separate itself from all siblings beyond naming search_documents and list_files.

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

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

It explicitly states when to use each kind, points to search_documents for querying and list_files for listing, and directs PDF/Excel binaries to the REST endpoint. However, it doesn't provide when-not-to-use guidance for text uploads or alternative indexing tools.

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

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

With no annotations, the description carries the full behavioral burden and delivers: ACL checks (files_list for files, none for supported_types), quota behavior (supported_types spends no quota), the former name of supported_types, that neither view mutates or sends mail, and the MCP-vs-REST input-format constraint (UTF-8 only vs PDF/Excel).

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

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

Front-loaded with the core purpose and then organized by view, with each sentence carrying distinct information. It is fairly dense and the opening fragment "File catalog reads" is slightly clipped, but no sentence is wasted.

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

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

Despite there being no output schema, the description sketches the return shapes ({files}; kinds/extensions/mimeTypes/extract notes) and discloses the key operational constraints. An agent has everything needed to select a view and invoke correctly.

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

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

Schema coverage is already 100%, so the baseline is 3; the description goes beyond it by restating view effects in the narrative (ACL/quota per view) and clarifying that namespace filtering is optional and ignored by supported_types, adding context the schema only partly conveys.

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+resource ("File catalog reads") and then enumerates both operating modes with their exact contents. It clearly distinguishes itself from index_document by stating "Use index_document to upload," so an agent can route without inspecting 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?

Explicitly ties each view to its condition (view=files for upload metadata filtered by namespace, view=supported_types for the type catalog) and names the alternative tool for the write case. It further rules out misuse by stating neither view writes, deletes, or sends email.

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

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

With no annotations, the description carries the full burden and delivers: 'This call does not charge', 'No quota spend and no email', 'Fails when the account cannot open a portal', and the notable 'ACL is not consulted'. These are the side-effect, cost, and authorization disclosures an agent needs before calling.

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

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

The description is dense but each sentence earns its place by tying an action to its return value, default, or constraint. The opening 'Payment helpers' is slightly vague, but action-by-action structure keeps it navigable.

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-action tool with no output schema, the description documents each action's return shape ('sku, amount, currency, periodDays, and the POST URL', '{url}', 'purchases and a cursor') and the relevant failure and cost behavior, leaving no material gap for correct invocation.

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

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

Schema description coverage is 100% and the schema already documents defaults, enums, and the includeStripe merge behavior in nearly identical wording. The description restates defaults ('Default sku is pro_prepaid_30d') rather than adding meaning beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific resource and then breaks down all three actions with their exact effects: machine_pay returns MPP payment instructions, portal returns a Stripe Customer Portal URL, purchases lists payment history. It explicitly distinguishes itself from siblings bootstrap_agent and get_usage, so an agent can route correctly.

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

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

Explicitly routes each action: 'Use action=machine_pay to...', 'Use action=portal for a Stripe Customer Portal URL', 'Use action=purchases to list...'. It also names prerequisites (top-up SKUs require active Pro), sibling ordering (bootstrap_agent creates the account first), and a failure condition ('fails when the account cannot open a portal').

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

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

With no annotations, the description carries the full burden and does well: it discloses ACL scopes per action, the plan prerequisite, that delete purges stored messages, that temporary inboxes expire and purge, and that calls themselves do not meter but inbound mail meters inbound_email. It stops short of stating reversibility of delete, error behavior on an inactive plan, or whether list is paged.

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

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

Purpose is front-loaded in the first sentence, then one clause per action, then cost and sibling routing. Dense but every sentence carries information; the ACL parentheticals make some clauses run long and could be trimmed.

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, five-action tool with no output schema and no annotations, this covers purpose, gating, destruction, cost, and alternatives. The remaining gap is return shape for list/get and whether list results are bounded, which matters more here because limit/offset apply only to audit.

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 action-level meaning beyond the schema by mapping each action to its ACL and noting that delete purges messages and create returns inbox plus address. It does not restate per-parameter detail, which the schema already supplies.

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

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

Opens with a specific verb set and resource: "Create, read, delete, and audit receive-only email inboxes," and closes by naming each sibling it is not (read_inbox_message, manage_inbox_webhook, manage_inbox_blocklist). An agent can distinguish this tool from its neighbors 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?

States the selection rule for every action (action=create/list/get/delete/audit) and explicitly routes mail reading, HTTPS notifications, and sender blocks to the three sibling tools. Also gives the precondition (requires an active plan) and the exclusion (no outbound email).

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

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

With no annotations, the description carries the full burden and does well: it discloses that listing/adding/deleting checks specific ACLs, that there is no quota spend, and that no email is sent. It omits auth requirements and reversibility of a delete, but the quota and side-effect disclosure is meaningful context an agent would otherwise lack.

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 purpose, then enumerates actions in a compact, parallel structure. Slightly redundant in repeating the ACL names that also appear in the action parameter's schema description, but 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 multi-action mutation tool with no output schema, the description explains what each action returns (entries / the entry / removal) and the side-effect profile. Only authorization requirements are left unstated, which is a gap but not a blocker.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the action/kinds and their required-for-action conditions. The description largely restates the action enum semantics already present, so baseline 3 is appropriate.

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

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

States a specific verb (block) and resource (senders for every inbox on the account), then enumerates the three supported actions with their backing ACLs. An agent can distinguish it from manage_inbox, which the description explicitly names as the sibling for a different concern.

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 per-action context (list vs add vs delete) and routes the agent to manage_inbox for managing the inboxes themselves. It does not state prerequisites such as required permissions, but the when-to-use signal is explicit for each action.

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

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

With no annotations, the description carries the full burden and does so well: delete is a soft disable (sets disabled_at, row stays), create returns the signing secret exactly once, calls do not meter and do not send email, and ACLs are named per action. These are non-obvious behaviors an agent could not infer from 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?

The description is dense but front-loaded with the most important constraint (metadata only, no body), then walks through actions in order. It is a single long paragraph, so it is slightly harder to scan than a bulleted structure would be, but nearly every sentence carries information.

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

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

For a four-action tool with no annotations and no output schema, the description covers per-action semantics, the one-time secret, soft-delete behavior, and non-metering. It does not describe the shape of list/deliveries results, but with no output schema that is the only meaningful residual gap.

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

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

Schema description coverage is 100%, so the schema already documents url, limit, offset, secret, status, and webhookId per action. The description largely restates the same routing (create/list/delete/deliveries) and adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific resource (HTTPS webhooks for email.received metadata) and enumerates the four operations it multiplexes via action. It also explicitly excludes the message body and routes the agent away from the sibling manage_inbox, so the tool's identity 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?

Each action is documented with its effect and the ACL it checks, which tells the agent exactly which action to pick for which goal. It closes with an explicit alternative ('Use manage_inbox for the inbox itself') and clarifies that later delivery attempts are not part of this call.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses writes vs reads vs deletes, per-action ACL checks (kvp_put, kvp_get, kvp_delete, kvp_list), metering (1 kvp_ops), and return shapes for each action. It stops short of error behavior, atomicity, or rate limits, but is unusually thorough for an unannotated 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?

The description front-loads purpose, then routing guidance, then per-action details. Every sentence has a job, and the density is appropriate for a four-action tool. It could be slightly more scannable with list formatting, but there is little wasted text.

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

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

No output schema exists, so the description compensates by listing return payloads for each action ({value, budget, keyBudget}, {ok, budget, keyBudget}, {keys, cursor, budget, keyBudget}). Combined with full schema coverage for parameters and explicit sibling alternatives, it is nearly complete, missing only error and edge-case behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates action-specific requirements already documented in the schema (key required for put/get/delete, namespace allow-list, action behavior) and adds no new parameter syntax, format, or constraint details beyond what the schema provides.

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

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

States a specific verb+resource ('Read and write arbitrary namespace strings') and enumerates the four supported actions. It clearly distinguishes this tool from siblings manage_memory, index_document, search_documents, and get_storage_summary, so an agent can route without opening schemas.

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

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

Explicitly directs to manage_memory when the namespace is prefs, facts, or run, to index_document/search_documents for semantic search, and to get_storage_summary for inventory. It also states a clear exclusion ('No email'), leaving no ambiguity about when to use this tool versus alternatives.

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

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

With no annotations provided, the description carries the full burden and does so: it discloses the ACLs checked (memory_put/memory_get), the metering cost (1 kvp_ops per call), the exact return shapes for both actions, and the read/write asymmetry of the actions. This is unusually rich behavioral disclosure for a tool with zero annotation coverage.

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 scope, then behavior, then alternatives; every sentence earns its place. Slightly dense with parenthetical ACL/metering clauses, but none are 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?

No output schema exists, and the description compensates by spelling out the return objects for both actions. Combined with the scope/namespace semantics and the sibling routing, an agent has everything needed to call this correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: it clarifies that the run scope maps to the run key's bound namespace (or 'run' when unbound) and that put returns budget/keyBudget meters. That goes beyond the schema's field-level descriptions.

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

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

States specific verbs and resources ('Store and read short strings') and enumerates the exact scopes (prefs, facts, run), which immediately distinguishes it from the generic manage_kv sibling. An agent can tell what this tool does 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?

Explicitly routes the agent: semantic recall goes to search_documents source=memory, other namespaces to manage_kv, and run-namespace cleanup to finish_run. It also states exclusions ('No deletes and no email'), covering when-not as well as when.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses metering (create does not meter, later attempts meter outbound_http, success actions meter kvp_ops/rag_index/outbound_http), the delivery contract (10s timeout, 3 attempts, exponential backoff capped at 300s, 2xx success, auto-disable after 5 consecutive exhausted failures), lapse behavior with disabled_reason=no_active_plan, and that delete retains the row. These are exactly the side effects and constraints an agent needs before mutating state.

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 purpose is front-loaded and nearly every clause carries operational information, but the delivery-contract details interrupt the action enumeration in the middle of the paragraph, so create/list/get/delete/runs are not presented in one clean block. Slightly reordering would improve scanability without losing content.

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 17-parameter tool with no annotations and no output schema, the description covers actions, permissions, metering, failure/lapse behavior, and delete semantics. Return values are only summarized ('returns schedules', 'returns one schedule and the contract'), so an agent still does not know the field shape of a schedule or run record, which keeps this from a 5.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by tying action values to ACLs and metering, defining the delivery contract that governs intervalMinutes and retry semantics, and clarifying that delete only disables future runs. It does not explain the onFailure/onSuccess object shapes beyond pointing at the schema, but the added contract context is substantive.

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 ('Account HTTPS interval jobs') and then enumerates every action (create/list/get/delete/runs) with what each writes or returns, plus the ACL each checks. An agent can distinguish this from siblings like get_usage or manage_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?

The action-by-action breakdown effectively tells the agent which mode to pick, and it explicitly routes the related-but-different need ('Use get_usage to see outbound_http remaining'). What is missing is a clear when-not-to-use statement or named alternative for scheduling itself, but the context is otherwise 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?

With no annotations provided, the description carries the full behavioral burden and does so: it discloses ACL checks per action, that list/get spend no quota while raw/attachment meter 1 kvp_ops each, and that pagination is newest-first. These are exactly the operational costs and constraints an agent needs before calling.

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

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

Front-loads the purpose, then moves in parallel per-action sentences that each carry quota, ACL, and return info with no filler. It is dense and fairly long, but essentially every clause earns its place; only the duplicate of schema-level ACL text is redundant.

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

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

There is no output schema, so the description must describe returns itself, and it does for all four actions (metadata, message+attachments, rawBase64 MIME, filename/contentType/sizeBytes/dataBase64). Combined with cost and prerequisite disclosure, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents limit, offset, inboxId, messageId, and attachmentId, including which actions ignore or require them. The description largely restates the enum's own ACL/quota documentation for the action parameter rather than adding new parameter meaning, so baseline 3 applies.

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

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

States a specific verb+resource (read mail stored on an inbox) and then decomposes the tool into four named actions with their distinct return shapes (metadata list, full message + attachment list, raw MIME as rawBase64, single attachment bytes). An agent can tell exactly what each mode produces 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 per-action routing (list vs get vs raw vs attachment), states explicit exclusions ("No deletes and no email send"), and names the prerequisite tool ("Use manage_inbox to create the inbox first"). This is when-to-use and when-not guidance in explicit form.

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?

No annotations are provided, so the description carries the full burden, and it does: it discloses metering cost ('Meters 1 rag_query'), ACL checks per source (rag_search vs memory_search), the return payload ('hits plus budget and keyBudget', plus scope and namespace for memory), and safety posture ('Read only: no writes and no email'). These are exactly the behavioral traits an agent needs before invoking it.

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 cost, then mode behavior, then alternatives in a logical order. It is dense but almost every clause earns its place; the parenthetical legacy names ('former rag_search'/'former memory_search') and a few repeated wordings add slight bulk without new decision value.

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

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

For a 5-parameter, no-output-schema tool, the description covers the return shape, metering, ACL requirements, both source modes, and sibling alternatives, so an agent has enough to call it correctly without reading the schema. Nothing material for correct invocation appears to be missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes further by explaining the semantic role of source (which index and which ACL each value implies) rather than restating types. It adds marginal value on scope/namespace via the mode descriptions, though much of that ('ignored when') is already duplicated in the schema.

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

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

States a specific verb and resource ('Semantic search over indexed notes and files') and immediately branches into its two modes, source=documents vs source=memory, so an agent can tell what it is and how it differs from siblings like manage_memory. It also surfaces the ACL each mode checks, which is a distinct, discriminable facet.

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

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

Explicitly routes the agent: 'Use index_document to add text first' and 'Use manage_memory action=get to read an exact key', naming the alternatives and the conditions that select them. It also states which source enum value to pick and what each scopes over, leaving little to inference.

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