Tillpad

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: it discloses that a bootstrap account is written, that no email is sent, that nothing is charged, and that there is no quota spend. It also surfaces the Authorization: Bearer tp_… requirement that would otherwise cause a silent failure, and enumerates the response 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?

Front-loaded with the core action and its outputs, then the edge cases (no email, no charge) and the auth/REST guidance. It is dense but every clause carries operational value; only the trailing 'Former name: agent_bootstrap' alias note is marginal.

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 write tool with no annotations and no output schema, the description supplies the missing pieces: the auth requirement, the return-field list, the no-side-effect guarantees, and the follow-up call sequence. Nothing an agent needs to invoke it correctly is absent.

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 both email and label, including the disposable-domain rejection. The description adds only that email is an address, so per the rubric the baseline of 3 applies rather than a penalty or a bonus.

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'), names the artifact it writes (bootstrap account) and the exact return fields. It is clearly distinguishable from siblings like manage_billing or create_api_key, which it explicitly casts as follow-on steps rather than 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?

Gives an explicit when-not path ('When you have no tp_ key yet, use REST POST /api/agents/bootstrap instead') plus the auth precondition for this endpoint. It also sequences the tool correctly by naming the follow-up actions (manage_billing action=machine_pay, create_api_key) and their conditions.

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 so well: per-action ACL enforcement, billing behavior ('these calls do not meter; inbound mail later meters inbound_email'), temporary-inbox expiry and purge, and delete purging stored messages. It leaves error behavior, idempotency, and rate limits undisclosed.

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 purpose then walks the actions, with zero filler sentences. The action= clauses are dense but each carries distinct information; the only cost is length from enumerating five actions inline.

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 multiplexed tool with no output schema and no annotations, the description covers provisioning, ACLs, lifecycle/expiry, metering, and sibling routing. Gaps remain around pagination semantics for audit and error surface, but an agent has enough to invoke each action 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 kind, domain, localPart, ttlSeconds, limit, offset, and inboxId with per-action applicability. The description's action= clauses largely restate ACL details already present in the schema, adding little beyond the baseline.

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 pair ('Create, read, delete, and audit receive-only email inboxes') and then enumerates each action with its exact effect and ACL. The receive-only/no-outbound qualifier and the named siblings make it unmistakable against read_inbox_message or manage_inbox_webhook.

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

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

Explicitly routes to the right alternatives: read_inbox_message for mail, manage_inbox_webhook for HTTPS notifications, manage_inbox_blocklist for sender blocks. It also states a prerequisite ('Requires an active plan'), but there is no explicit when-not-to-use guidance or fallback behavior if the plan is inactive.

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: ACL required per action, metering behavior (create does not meter; later attempts meter outbound_http; store_kvp/store_rag/notify_webhook meter specific counters), no email sent, and the full delivery contract (10s timeout, 3 attempts, exponential backoff capped at 300s, HTTP 2xx = success, auto-disable after 5 consecutive exhausted failures). It also discloses that delete is a soft disable that keeps the row.

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?

Dense and front-loaded: the create action and its metering/contract are stated first, followed by the remaining actions in a compact list. The telegraphic style ('This call does not meter', 'No email from this call') is efficient, and every clause conveys distinct behavior, though the length is notable for a single 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?

For a 16-parameter multi-action tool with no output schema and no annotations, the description covers the essential behavior: quota/metering, ACLs per action, delivery contract, and soft-delete semantics. Return values are only lightly implied ('returns it plus the delivery contract'), but create's return contract is described enough to call 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 16 parameters including per-action applicability and defaults, making 3 the baseline. The description adds only marginal parameter context (metering for onSuccess types, min interval, authSecret storage), largely restating what the schema already provides.

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

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

The body clearly enumerates the resource (interval HTTPS jobs/schedules) and what each action does — create writes and returns a schedule plus delivery contract, list/get/delete/runs each have defined behavior. The opening fragment 'Account HTTPS interval jobs' is telegraphic, but the per-action verbs and resources make it identifiable. It does not explicitly differentiate itself from siblings like manage_inbox_webhook, only pointing to get_usage for quota.

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 per-action conditions (create requires an active plan, min interval 5 minutes, authMode requirements) and routes quota checking to get_usage, which is genuine usage context. However, it never states when to choose this tool over alternatives such as manage_inbox_webhook or index_document for similar outbound/delivery needs, so usage is implied rather than 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?

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.