Conecto Email

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

The description goes far beyond the annotations: a held call answers approval_required with an approval_id, must be re-called once with identical arguments, and can be answered via X-Conecto-Approval or _meta.approvalId. It also discloses that the calling person never approves, that each approver gets a personal link, the two_people_over escalation, bill-specific behavior for purchasing_create_bill and purchasing_pay_bill, and the $0.001-per-call cost with no charge on failure.

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

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

The core purpose is front-loaded, but the prose is a run-on with heavy parentheticals, duplicated pricing ('$0.001.' followed by 'Costs $0.001 per call'), and a tangential sentence about rule removal ownership. Some sentences earn their place, but trimming and restructuring would materially improve readability.

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 9-parameter tool with no output schema, the description covers the creation-to-approval lifecycle, approval mechanisms, cost, and removal conditions. It leaves two gaps: it does not say what a successful rule creation returns (e.g., a rule identifier), and it does not state who is permitted to create a rule.

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 78%, and the description supplements it with examples that clarify how 'over' and 'values' are evaluated (amount over 500; method equal to one of several verbs) and that argument may be 'total' for bills. It also explains that the approver can be an email, saved channel, or team, adding meaning for approver_email and approver_channel even though the schema text already covers most parameters.

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

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

The description states a specific verb-and-resource: it makes a named tool's calls wait for a person, with three distinct modes (all calls, calls over a threshold, calls matching listed values). An agent can tell what the tool does, though the opening sentence is syntactically tangled and it never names the sibling account_list_approval_rules it complements.

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?

Concrete scenarios are supplied (invoices_create_credit_note when amount is over 500; connect_call when method is POST/PUT/PATCH/DELETE) that illustrate when a rule applies, and the post-hold approval flow is described. However, there is no explicit statement of when to call this tool versus account_list_approval_rules or when not to create a rule, so the usage guidance is implied rather than directive.

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

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

Goes well beyond the annotations (which only say non-read-only, idempotent, non-destructive): it discloses billing reassignment ('responses ... charged to that team from now on'), that rentals move with the parent, an auth/key restriction, and per-call cost with failure refund. This is exactly the extra context annotations cannot carry.

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 resource list, and every clause carries information. It is docked slightly for the redundant cost sentence – '$0.001. Costs $0.001 per call' repeats the price twice.

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 covers side effects, auth, cost, and the failure case ('nothing if it fails'), which is most of what an agent needs. What is missing is any statement of what a successful response contains, so an agent must infer that from the idempotent/non-destructive annotations.

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 33% (only `id` documented). The description enumerates the accepted `kind` values, but that duplicates the enum already in the schema and adds no format/syntax detail. The required `team` parameter gets only the implicit 'to a team' phrasing, so the description does not fully compensate for the coverage gap.

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

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

States a specific verb ('move ... to a team') plus an exhaustive list of the resource kinds affected, so the agent knows exactly what domain this operates on. It is clearly distinct from siblings like account_save_team or account_pause_team.

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

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

Provides a real precondition ('Only a key of the company-wide team without limits moves things between teams') and covers the bot-owned edge case ('Something a bot makes already belongs to the bot's team'). It does not explicitly name an alternative tool or a when-not-to-use case, keeping it just below a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real behavior: newest-first ordering, the fact that hash-chain verification 'breaks where an entry was changed or removed', and that the call is free. It stops short of describing pagination/cursor behavior or what an entry looks like, so not a full 5.

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

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

Two dense sentences: the first front-loads scope and the enumeration, the second carries the sibling pointer and the verify semantics plus the cost note. No filler, no repetition of the title.

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 4-param, no-output-schema read tool, this covers scope, ordering, the security-relevant `verify` mode, cost, and the competing tool. Remaining gaps are the two undocumented filters (`since`, `limit`) and any hint about entry shape, but nothing blocking an agent from calling 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 coverage is only 25% (only `action` is documented in-schema), so the description has to compensate. It does explain `verify` semantics well and effectively hints at `action` prefixes by listing event categories, but `limit` and `since` get no treatment at all — no guidance on time-window format or default/max behavior.

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?

Names the resource precisely (the account's admin and security actions) and enumerates the concrete event classes captured: key creation/revocation, limits and auto-reload, owner sign-ins, connectors, exports, vault reads/writes, credential changes, deletions. This is specific enough that an agent can distinguish it from account_events and account_list_calls 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?

Explicitly routes the alternative: 'Ordinary work is in the call log (account_list_calls)', telling the agent exactly when to pick the sibling instead. It also gives a conditional usage rule for a parameter ('verify: true also checks the hash chain'), which is when-to-use guidance at the argument level.

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

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

Annotations already state readOnly, idempotent, non-destructive, and closed-world. The description adds useful behavioral context beyond annotations: the call is free, and AI visibility and phone usage depend on purchased credit. It does not cover auth or rate limits, so it is strong but not exhaustive.

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

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

A single sentence front-loads the resource and then enumerates relevant returned fields; every clause is meaningful. The sentence is dense and slightly convoluted, which keeps it from a 5.

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 explain return values; it enumerates balance components, holds, daily budget, auto-reload state, and free reads/downloads used. With annotations covering safety and zero parameters, this is complete for the tool.

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

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

This tool has zero parameters, so there are no parameter semantics to document. The baseline for 0 params 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 the resource (account balance) and enumerates the specific fields returned, so an agent knows this is a balance/credit-status read. It does not explicitly contrast with account_dashboard_link or other account_* siblings, so it is clear but not fully differentiated.

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

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

No when-to-use, when-not-to-use, or alternative guidance is provided. The word "Free" hints at cost but does not say when to call this instead of sibling account 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?

Annotations only cover read-only/idempotent/no-destruction; the description adds substantial context beyond them: the link is single-use, expires in an hour, an unopened link dies after 7 days, and the page is scoped to what 'this key' may see. Those are exactly the behavioral traits an agent needs before generating a shareable artifact.

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 idea (one-time link to a snapshot of one area) and every sentence carries usable information about usage or lifecycle. The prose is conversational and slightly padded, but not wasteful enough to drop below 4.

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

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

With no output schema, the description does cover the essential return semantics (a link URL that opens once) and its expiry behavior. The remaining gap is the `area` enum meaning, which is the one thing an agent must get right to call it.

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

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

Schema description coverage is 0% for the single required `area` parameter, and the description never explains that it selects among the ~51 product areas. The recruiter/bookkeeper examples loosely gesture at area selection but do not document the enum values or how to pick one. Marginal value over the schema's bare enum.

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

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

The description clearly states the verb+resource: it produces a one-time link to a page showing one area's current state. An agent can distinguish it from data-reading siblings because it explicitly says the link is a snapshot view, not an answer. It does not name the near-duplicate siblings (hiring_dashboard_link, hr_dashboard_link, analytics_view_link, view_link), which keeps it from a 5.

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

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

Explicit when-to-use ('when the person you work for asks to see it themselves'), explicit when-not ('Do the work and answer with the area's own tools first; a link never replaces that'), and a concrete trigger ('when an answer would be a long list they would rather look through, offer a link and make it once they say yes'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and a closed-world scope, so safety is covered. The description adds value beyond that by disclosing the shape of the content (company, country/region, contents), the baseline that all areas use Conecto's database and servers with some using an additional named service, and that the call is free. It stops short of describing pagination or exact return structure.

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

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

Two sentences plus a short purpose tag and cost note; the content-of-return sentence is front-loaded and no sentence is filler. The 'Free.' fragment is terse but carries distinct information.

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

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

With one optional parameter, no output schema and full annotation coverage, the description supplies what the agent otherwise lacks: what the returned rows contain and the GDPR-driven reason to call it. Only the exact return shape/pagination is left unspecified, which is minor for a simple read.

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

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

Schema description coverage is 100% — the single optional 'areas' parameter is documented with an example and a default of 'all'. The description only implicitly references areas ('each area's data'), adding no syntax or filtering 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 the concrete resource: per-area data storage/processing locations, including the operating company, the country or region, and what is held. That is specific enough to distinguish it from every account_* and books_* sibling, none of which cover data residency, though the verb is implied rather than stated.

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

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

It gives a clear use context — the business's records of processing and transfer assessments under GDPR Art. 30 and 44 — which tells the agent when this tool is the right call. It does not name an alternative or any explicit exclusion, so it falls 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?

Goes well beyond the annotations by disclosing per-channel cost ($0.005, free with no subscribers), a 10 KB data limit, and that sent_by is auto-appended with bot and team. Does not mention that repeats are non-idempotent (duplicate events) or what happens on an unmatched kind, which the annotations leave to inference.

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?

Cost is stated twice in near-identical sentences, which wastes space in an otherwise dense paragraph. The delivery model is front-loaded well, but the long parenthetical from the first sentence to the last hurts readability.

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 mutation tool with no output schema, it covers destinations, payload limits, auto-injected metadata, and pricing—the things an agent needs before calling. Remaining gaps are the semantics of title/text/link and the non-idempotent behavior implied by annotations.

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

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

Schema coverage is only 20%, so the description must compensate; it does for kind (pattern restated with examples), data (any JSON, 10 KB cap) and sent_by (injected, not an input). It says nothing about title, text, or link, leaving three of five params explained only by bare schema types.

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

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

States a specific verb (send/emit) and resource (event), pins the naming scheme to custom.<name> with two concrete examples, and names where the event lands (subscribed channels plus account_events). This clearly separates it from the read-only sibling account_events.

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?

Explains the routing model (notify_subscribe with 'custom.*' or exact name) and the downstream alternative of another team's bot picking the event up from account_events. Lacks an explicit 'do not use when…' exclusion, but the context is concrete enough to choose correctly.

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

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

Annotations only declare destructive/idempotent/not-readOnly. The description goes far beyond them: what is anonymised vs deleted vs retained (with reasons surfaced in the result), that the suppression lists block future outreach, that the action is irreversible, and that the owner is emailed. This is genuinely decision-relevant context an agent cannot get from the annotations.

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

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

Front-loaded with the action and the precondition, which is good, but the body is a single run-on sentence enumerating dozens of data areas, and 'Free. Free.' is duplicated — an obvious editing artifact. Density is justified by the tool's complexity, but the delivery costs readability.

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 highly destructive multi-system erasure with no output schema, the description covers irreversibility, the anonymise/delete/retain split, the error path, side effects on outreach, and that the return value carries per-item retention reasons. An agent has enough to call it correctly and to warn the user.

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 real meaning: it explains that 'correspondence' governs whether emails and tickets are deleted or retained for legal reasons, and that email/phone are the identity anchors used for matching and suppression. Only the phone parameter's role is left implicit.

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 ('Erases one person across every area') plus the legal trigger (GDPR Art. 17). An agent can immediately distinguish this from account_export_person or account_find_person, which operate on the same person without destroying data.

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

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

Gives an explicit precondition for invocation ('once you know it is them — they wrote from that address, or confirmed it') and a routing rule for the owner_required case. It never names a sibling alternative, so it stops short of a full when/when-not comparison.

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

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

Annotations already declare readOnlyHint/idempotentHint/no-destructive, so safety is covered; the description adds genuinely new facts: 30-day retention window, oldest-first ordering, and that calls are free. It omits any mention of rate limits or event object shape, but the added context is substantial.

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 scope statement and ordering are front-loaded, then the event-family list, then operational notes (retention, polling, cost). Dense and mostly waste-free, though the long semicolon-chained event list is heavier than a shorter enumeration would be.

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

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

With no output schema, the description does the heavy lifting by naming what kinds of events appear and how to page through them; an agent could use it correctly without further context. It does not describe the shape of a returned event record, which is the remaining gap for a read tool of this kind.

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

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

Schema covers 67% of parameters ('after' and 'kinds' documented, 'limit' not). The description adds meaning beyond the schema by explaining the polling idiom for 'after' (last event_id you saw) and clarifying the wildcard area syntax indirectly via the 'hiring.*' framing in the schema. Minor gap on limit and default behavior.

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 — reading recent account events caused by actors outside the bot — and enumerates the event families (applications, bookings, form responses, signatures, emails, goals) plus custom events from account_emit_event. This makes it easy to distinguish from account_audit_log and from the write-side sibling account_emit_event.

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 consumption pattern — 'Poll with after = the last event_id you saw' — and implicitly delineates scope as external-actor activity versus bot-emitted custom events. It does not explicitly say when to prefer it over account_audit_log, so it stops short of full routing guidance.

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

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

Goes well beyond the annotations: discloses that the job is asynchronous with a call_id and download link per part, that credentials are excluded, that parts are decryptable only by this key and by owner/admin keys with sufficient permissions, and that a non-company team key gets owner_required. It also warns that the owner is emailed and that free-tier quotas apply, so the agent knows the side effects of a non-readOnly, non-idempotent 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?

The core content is front-loaded and useful, but there is real duplication: 'Free' is stated twice and the background/polling instruction is given twice with different wording ('poll the call with account_get_call; the result has a download link for each part' vs 'the reply has a call_id; poll it with the account_get_call tool or GET /v1/calls/<id>'). The garbled sentence about which keys can open the parts also costs clarity.

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

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

For a zero-parameter, no-output-schema job tool, the description carries the burden well: it explains what is produced, how to retrieve it, and what access and quota rules apply. It omits retention/expiry of the download links and leaves the key-permission rule phrased ambiguously, which is the only 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly offers no parameter discussion.

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 with precise scope: everything the account holds, as JSON Lines per area plus stored files, in ZIPs up to 24 MB written to the file store. That scope distinguishes it from the narrower account_export_person and books_export siblings without needing to name them.

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

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

Gives clear operating context: it is an asynchronous job, you must poll with account_get_call, and it is rate limited to one at a time and three per day. It never explicitly routes the agent to account_export_person or books_export for narrower exports, so the alternative-selection guidance is implied only by scope.

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?

Placeholder

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?

Placeholder

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?

Placeholder

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?

Placeholder

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?

Names a specific action and resource ('everything account_find_person finds about one person in one ZIP') and enumerates the contents (JSON Lines records minus credentials, plus referenced files like a CV). An agent can distinguish it from account_export_all and account_find_person without opening a schema.

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

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

Gives a clear trigger (

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

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

Annotations already cover read-only, idempotent and non-destructive, so the bar is lower; the description still adds real value by disclosing the return shape ('each kind with its count and ids') and that the call is free. It stops short of stating match strictness (exact vs. partial), result caps, or what happens with zero hits, which for a read with no output schema would be useful.

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 verb and scope, and each sentence carries distinct information (purpose, GDPR use case, return shape, alternatives, cost). The long enumeration of areas is partly redundant with 'across every area' and 'with their chats and CRM history', which is the only wasted space.

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-optional-param lookup with annotations covering the safety profile and no output schema, the description covers purpose, trigger, return contents, cost and sibling routing. Nothing an agent needs in order to choose and call this correctly is missing.

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

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

Schema coverage is 100% and both properties already document their formats, so baseline is 3. The description adds one meaningful nuance the schema does not — that either an email or a phone can identify the person — but does not say whether both may be supplied together or how they are combined.

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 ('Every record this account holds about one person') with an explicit scope ('across every area') and an explicit matching key (email or phone). It also names the two closest siblings, account_export_person and account_erase_person, so an agent can differentiate without opening any schema.

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

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

Gives a concrete triggering scenario ('For a person who asks what the business keeps about them (GDPR Art. 15)') and routes the adjacent intents away: export for a copy, erase for deletion. When-to-use and the alternatives are both spelled out, not inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description's only behavioral contribution beyond that is the cryptic 'Free', which reads as a stray fragment rather than a disclosed trait (no-cost read? free tier?) and is not 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?

One short sentence is appropriately sized, but it is a verbless noun phrase followed by a dangling 'Free.' fragment, so it is not front-loaded with an action the agent can act on. The trailing 'Free' does not earn its place without explanation.

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 no-param, read-only tool with full annotation coverage and no output schema, the description is close to sufficient but omits what actually comes back (e.g. a URL vs. raw values) and never states the read action. It is adequate rather than 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 there is nothing for the description to disambiguate and the baseline is 4. The enumeration of brand fields is a small bonus that hints at the returned content.

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

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

The description enumerates what the brand consists of (name, logo, colour, footer line) and where it appears (emails and published pages), which is genuinely informative about the resource. But it never states the action – that these values are returned/read – so the verb is only inferable from the tool name. The sibling account_set_brand is not mentioned, so nothing distinguishes get from set.

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

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

There is no statement of when to call this versus account_set_brand, or any prerequisite such as authentication or account scope. The single word 'Free' gestures at a cost condition but is not framed as guidance. The agent must infer usage entirely from the name.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive), and the description adds useful behavioral context: the call status values, returned cost/result, and polling usage. It does not describe auth or rate limits, but adds meaningful detail beyond annotations.

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

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

Three short sentences, front-loaded with the core action and return fields, followed by usage guidance and a useful cost note. No wasted text.

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

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

For a simple read tool with annotations and no output schema, the description covers the key return values and polling use case well. Minor gaps around missing/invalid call IDs or exact response shape remain, but the essential context is present.

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

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

Schema description coverage is 0%, so the description must compensate for the single call_id parameter. It only says the lookup is 'by id' and does not explain where the ID comes from or its expected format, leaving the schema to carry nearly all parameter meaning.

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

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

The description gives a specific verb and resource ('One call by id') and names the returned fields (status, cost, result). It clearly distinguishes a single-call fetch from the sibling list operation.

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

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

It explicitly states the primary use case: polling a background call until it finishes. It does not mention when not to use it or point to account_list_calls for discovering call IDs, but the intended context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds two real signals beyond that: the returned fields (standard, current, maximum, plus past requests and answers) and that the call is free of charge. It says nothing about auth requirements or pagination of the requests list.

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

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

A single dense sentence with no filler; the parenthetical examples of limit kinds are the one mildly expendable element. The payload (what is returned) is front-loaded.

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

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

There is no output schema, so the description must describe the response, and it does: per-limit standard value, current value, maximum askable value, plus the business's requests and their answers. For a zero-parameter read tool with full annotation coverage, nothing an agent needs is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool 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 read of a specific resource: the account's limits, their standard/current/max values, and the business's limit requests with answers. It is clearly distinguishable from the sibling account_request_limit by describing only retrieval. However, it never names that sibling to make the read-vs-request split explicit.

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

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

Usage is only implied: an agent infers it should call this to inspect limits before calling account_request_limit. There is no explicit 'use when' or 'do not use when' statement, and no prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description does add value beyond them by disclosing a cost trait ('Free', presumably no quota/credits consumed) and by indicating the payload includes thresholds and approvers. It omits ordering, pagination, and whether inactive rules are included.

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

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

Two short sentences with no filler, and the substantive content leads. The telegraphic 'Free.' at the end is efficient but under-explained, and the opening phrasing reads awkwardly.

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 no-parameter read with full annotation coverage and no output schema, the description covers the essentials: what the records are and roughly what fields come back. It still leaves open whether all rules or only active ones are returned, and what 'Free' actually constrains.

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; baseline 4 applies. The mention of thresholds and approvers usefully previews what the result records contain.

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 gestures at approval rules ('the tools that wait for a person's approval, with their thresholds and approvers'), but calling them 'tools' rather than 'rules' muddies the subject, and it never states plainly that this returns the account's configured approval rules. An agent can roughly infer the resource, but the verb and the object are not clean.

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

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

There is no when-to-use guidance and no mention of the obvious alternative, account_add_approval_rule, which creates the very objects this lists. 'Free' hints at cost but says nothing about selection criteria or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral facts: results are sorted newest first, scoped to this account, and "Free" (no billing/quota cost). It does not mention pagination or windowing beyond "recent".

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?

Roughly twenty words, front-loaded with the resource and ordering, and every clause carries a filter or a behavioral fact. The telegraphic phrasing ("or one area's") is slightly clipped but not wasteful.

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

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

With no output schema, the description should tell the agent what a returned call record looks like, and it does not. Combined with an unstated limit parameter and an undefined notion of "call", an agent cannot reliably predict the response shape before invoking.

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

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

Schema description coverage is 0%, so the description must carry the parameters and it only half does. It explains status as failed/succeeded but omits the reserved and running enum values, gestures at area ("one area's") without explaining its 52-value enum, and never mentions limit, its default of 20, or the 100 ceiling.

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 the resource and its scope ("Recent calls on this account") and states an ordering, so the basic operation is inferable. But it never says what a "call" is here – the sibling list contains phone_list_calls/phone_get_call, so an agent cannot tell whether this is phone call history or logged API/tool invocations. The verb is also only implied by the title.

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 names optional filters (failed/succeeded, one area) but gives no when-to-use guidance and no alternative. Nothing tells the agent to prefer account_get_call for a single record or phone_list_calls for telephony, both of which are adjacent siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that content is returned 'as they are now' (live, not cached) and that calls are free, but says nothing about volume, ordering, or pagination for what is implicitly a full enumeration.

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

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

A single dense sentence front-loads the resource and its scope, then the returned fields, with the parenthetical category list doing real work in telling the agent what is covered. The trailing 'Free.' is terse but earns its place as a cost signal.

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

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

With no output schema and no parameters, the description carries the return-value burden and does so by naming the concrete fields (timing, subject, headline, opening words, variables). Only ordering/volume expectations are missing, which is minor for a small per-account listing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and no risk of a caller guessing at argument semantics.

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

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

The description enumerates exactly what the tool returns: every customer-facing email type (bookings, invoices, newsletter sign-ups, etc.) plus send timing, subject, headline, opening words and available {variables}. That is a specific resource picture, but the verb 'list/retrieve' is only implied and the sibling account_set_email_template (the write counterpart) is never referenced to sharpen the boundary.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives even though account_set_email_template sits adjacent in the sibling list as the editing counterpart. The 'Free.' tag signals cost of calling but not the selection context.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior: deterministic ordering (company-wide team first), the fact that paused teams and keys are included, and that the call is 'Free' (no billing impact). It does not address pagination or completeness of the result set.

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

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

The core content is front-loaded, but it is delivered as one very long run-on sentence enumerating roughly seven aspects of each team. The trailing sentence 'A person's own assistant works within their teams' is unclear and does not obviously help an agent decide or invoke; the field list would be far easier to parse as a structured enumeration.

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

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

With no output schema, the description carries the burden of describing return values, and it does so thoroughly: areas, read-only flag, budget type/period/alert line, period spend, ERP code, paused state, keys, and members with manager. What's missing is ordering of the non-company teams and whether the result is paginated or truncated.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the description contradicts or needs to explain a request shape.

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

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

The description states it returns the account's teams with the company-wide one first, and enumerates what each team record contains. It's clear this is a read of team configuration, though the verb 'list' comes from the title rather than the description. No sibling also lists teams, so no sibling-differentiation is needed.

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

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

There is no explicit when-to-use or when-not guidance, and no alternative tool is named. The phrase 'A person's own assistant works within their teams' gestures at context but doesn't tell an agent when to call this versus siblings like account_find_person or account_balance.

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

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

Adds genuinely non-obvious traits the annotations don't carry: single use, 30-minute validity, passwordless, and no cost. That is exactly the operational detail an agent needs before handing a credential out. Minor tension: a credential-minting, single-use artifact sits oddly beside readOnlyHint/idempotentHint=true, though nothing persistent is mutated.

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 front-loaded 'a link that signs the owner in with no password' is strong, but the middle becomes a disorganized run-on ('the balance, adding credit, auto-reload, limits, what the bots did, people, rentals and keys') that reads as a page inventory rather than wording tuned to page selection. The trailing 'Free.' is a fragment that would be better merged.

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

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

With no output schema, the description does the necessary work: it says the return is a link, that it expires in 30 minutes, that it is single use, and what the recipient does with it. It stops short of stating the return type/format explicitly or the consequence of requesting a second link.

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

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

Schema coverage is 0% and the single 'page' parameter has nine enum values, but the description only names two of them ('people' for role assignment, 'settings' for email-domain joins) and never addresses the 'home' default. It conveys that the page decides where the owner lands, which is real added meaning, but leaves most of the enum unmapped.

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?

Identifies a specific resource (a passwordless sign-in link for the business owner) and its effect (signs the owner into their Conecto page). It never uses an action verb like 'generate' and never distinguishes itself from the sibling account_dashboard_link, which is the nearest ambiguity an agent will face.

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?

'Hand it to the owner' gives the downstream action, and the middle sentence hints at when to target a specific page (people, settings for domain join). But there is no explicit when-not guidance, no mention of account_dashboard_link or account_set_owner_email as alternatives, and no stated prerequisites (does the owner need to exist / have an 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?

Annotations only declare the generic flags; the description adds the substantive behavior: all keys stop, calls are refused, and the state persists until the owner resumes on their account page. It also discloses that the call is free. It omits who is permitted to invoke it and whether an already-paused team errors out (relevant given idempotentHint=false).

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

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

Front-loaded and short, but the duplicated "Free. Free." is dead weight and the clause "this one too if it is the team's" is ambiguous enough to cost the reader a re-read. Trimming those two would make this a tight two-sentence definition.

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 mutating one-param tool with annotations and no output schema, the effect and recovery path are covered, but the missing identifier format and the missing permission/precondition info leave an agent without what it needs to call this confidently.

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

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

Schema description coverage is 0% for the single required "team" parameter, so the description must compensate and does not: nothing says whether "team" is an ID, a slug, or a display name. The phrase "this one too if it is the team's" is confusing and does not clarify the parameter.

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?

"Stops every key of a team at once" states a specific verb (stops) and resource (team keys) and clarifies the blast radius is all keys, not one. It is clearly distinguishable from account_save_team or account_assign_team, though it never names a sibling to differentiate against.

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

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

"For a bot that misbehaves or a team that spends too fast" gives concrete trigger scenarios, and "until the owner starts the team again" implies reversibility. But there is no explicit when-not guidance (e.g. pausing a single key vs. the whole team) and no alternative tool named.

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

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

Beyond the destructiveHint annotation, the description explains the financial effects: credit and first top-up bonus leave the balance, the card is credited back with tax, and the service fee is kept. This is exactly the kind of consequence detail an agent needs before invoking a destructive refund operation.

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

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

The description is front-loaded with the refund action and key constraints, but it is awkwardly phrased and contains a duplicated trailing sentence: 'Free. Free.' That redundancy and the run-on eligibility sentence reduce polish.

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

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

For a one-parameter destructive tool with no output schema, the description covers eligibility, default behavior, financial effects, and fee treatment. An agent has enough information to decide whether and how to call it.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does so by explaining that topup_id is optional and that omitting it refunds the newest top-up, with GET /v1/topups as the way to list ids.

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

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

The description states a specific verb and resource: refund a top-up. It also specifies the core eligibility condition (paid in the last 24 hours and unused), so the agent can distinguish this from unrelated account and books 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 clearly states when the tool applies: a top-up paid in the last 24 hours that has not been used. It also explains the default behavior when topup_id is omitted, though it does not name a sibling alternative or explicitly describe 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?

Goes well beyond the annotations by disclosing that the outcome is asynchronous (account.limit_request_answered event plus email to the owner), that approval may be partial ('maybe with less'), and that the owner is notified immediately as a side effect. That is exactly the mutation-and-notification context the readOnlyHint=false / destructiveHint=false pair does not convey.

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 dense with useful facts in two sentences, but it ends with a duplicated 'Free. Free.' and packs the eligibility, throttling and async-answer mechanics into one overloaded clause.

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

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

With no output schema, the description correctly explains how the answer arrives (event plus owner email) rather than what is returned. It stops short of saying whether a request identifier is returned or how to check a pending request, which an agent handling a follow-up would want.

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 all four parameters are already documented, including the enum list, the 40–2000 character reason bounds and the `other` fallback. The description restates those facts ('which one (or other, saying which)', 'the number it needs', '40 to 2,000 characters') without adding format or unit guidance the schema lacks, 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?

Names a specific verb and resource: asking Conecto to raise one of the business's limits, with the inputs spelled out. The read/write split against account_get_limits is obvious from the phrasing, but the description never names that sibling, so the differentiation is inferred rather than stated.

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

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

Gives concrete eligibility and throttling conditions: only for an account that has topped up, one request per limit at a time, five in 30 days, and free. It lacks an explicit alternative or exclusion (e.g. 'to see current limits use account_get_limits', 'do not use for billing/top-up issues, use account_refund_topup'), which keeps it below 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?

Beyond the annotations, it discloses the hard-vs-soft budget enforcement outcome ("a hard budget refuses the call that would pass it, a soft one only warns"), the alert event and email emitted at alert_percent, key-scoping effects of read_only/drafts_only/mailboxes, the special company-wide team behavior, and the cost model including no charge on failure. None of this is inferable from readOnlyHint/idempotentHint alone.

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

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

It is a single dense paragraph in which the most important fact (this tool creates or changes a team) appears only after a long definitional preamble, making it hard to scan. The cost is stated twice ("$0.001." and "Costs $0.001 per call; nothing if it fails."), which is wasted space in an otherwise information-dense 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 13-parameter upsert with no output schema, the description covers permissions, budget enforcement, alerting, drafting/mailbox scoping, the company-wide special case, and billing behavior. The only gap is the return value, which is not critical for calling the tool 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 77%, so the baseline is around 3, but the description adds real meaning: budget_period is tied to monthly_budget_usd, budget hard/soft behavior is spelled out, erp_code is contextualized as a cost center for statements, and drafts_only is explained as writes waiting for a manager or owner. Some parameters (name, new_name, alert_percent range) get no narrative help beyond the schema, keeping it out of 5 territory.

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 defines the resource precisely ("A department, location or project group of the account...") and later states the operations it performs ("You may make a team and narrow one"), so an agent can identify it as the create/update tool for teams. However, the actual verb+action is buried mid-paragraph rather than front-loaded, and the distinction from siblings like account_list_teams or account_pause_team is only implicit.

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 draws an explicit boundary of what this tool can do (create a team, narrow its areas) versus what only the owner can do on the account page (widening areas, enabling writes, ending drafts-only, soft-to-hard budget switching, raising/removing budgets), including the precondition "when the account has an owner email." That is a clear when/when-not with a named alternative path.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add operational context, which it does: conjunctive case-insensitive matching, ranking (titles first, then newest), and the fact that each result names the tool that opens it. Pagination and result-count behavior remain unspecified.

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

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

Front-loaded with the core purpose, then matching rules, ranking, and result format in tight sentences. The long enumeration of content types is informative but stretches the first sentence; nothing else 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?

Covers purpose, matching semantics, ranking, result shape, narrowing, and cost, which is enough to call it correctly even without an output schema. The only real gap is how many results come back by default and how limit interacts with the 50 maximum.

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

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

Schema description coverage is 0%, so the description must carry the load; it defines query semantics ('Every word must appear (any case)') and the purpose of areas ('Narrow it with areas'), which the enum alone would not explain. The limit parameter, including its default and 50 cap, is left entirely to 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 ('One search over what this account holds') and enumerates exactly what is searched, from files to CRM records to book entries. An agent can distinguish this cross-domain search from the many single-domain siblings 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?

'Narrow it with areas' gives clear narrowing guidance, and 'Free' signals there is no cost barrier to calling it broadly. However, no alternative is named and no when-not-to-use case is given, despite siblings like account_find_person or account_list_calls that overlap with the CRM and email scopes.

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?

It provides highly valuable behavioral constraints beyond annotations, such as listing every specific location of brand usage (e.g., 'forms, status, views'), specifying file formats for the logo (PNG, JPEG, etc.), and critically, stating 'Only what you pass changes; an empty string clears 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?

The description is dense and long, which reduces conciseness. However, this length is necessary to cover the vast scope of affected systems and behavioral rules, making the verbosity justified.

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

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

The description is exceptionally complete, detailing not only the parameters but also the cost of the operation and the exact scope of its influence across the application, addressing potential agent questions about side effects.

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

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

Given the very low schema coverage (20%), the description is essential. It explains the functional purpose of each parameter (e.g., 'Hex, like #1a73e8' for color) and defines critical operational semantics like using an empty string to clear a setting.

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

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

The description explicitly states the goal: setting the business's brand (name, logo, color, and footer). This is immediately clear and distinguishes it from potential retrieval tools like `account_get_brand`.

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 tool clearly defines its comprehensive scope—branding applies to all customer emails and published web pages. It doesn't compare it to other setters, but its detailed list of effects defines its operational niche well.

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

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

Goes well beyond the annotations by disclosing cost ($0.001 per call, free on failure), the reversibility contract (empty string restores the original), the blast radius (facts, links and buttons are untouched), and the text format rules (plain text, blank line = new paragraph). These are all consistent with destructiveHint=false and idempotentHint=true.

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

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

Four tight sentences, front-loaded with the verb and scope, then the dependency, the reversibility rule, the formatting rule and the cost. No filler, and each sentence carries a fact an agent needs to call it correctly.

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

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

For a 4-parameter mutation with no output schema, the description covers scope, cost, failure behavior, variable sourcing and formatting. It does not say what the response contains or whether the change is immediately live, but with no output schema that gap is minor.

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

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

Schema coverage is only 25%, so the description carries real weight: it explains the empty-string reset semantics, the {variable} placeholders permitted in values, and the plain-text/blank-line formatting for the text fields. It leaves the mapping of individual parameters (e.g. which field the 200 vs 4000 character limits apply to) to the schema, which is acceptable.

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 ('Change an email's subject, headline or opening words') and bounds the scope explicitly: the underlying facts, links and buttons stay fixed. It also names the sibling read tool it depends on (account_list_email_templates), so an agent can distinguish it from listing or brand tools 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 clear operative context: variables must come from account_list_email_templates ({name}, {when}), and passing an empty string reverts to the original wording. It stops short of explicit when-not-to-use guidance (e.g. that this cannot change times, places or amounts, only the wording), so it lands at clear-context-but-no-exclusions.

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

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

Beyond the annotations, the description discloses meaningful behavior: the effect is deferred ("Nothing changes until they open the link") and the consequences of confirmation (owner receives warnings and approval requests, only the owner raises limits). It also signals the call is free. It omits what happens on repeat invocation, which matters given idempotentHint=false, and the duplicated "Free. Free." suggests a drafting error.

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 text is short and the precondition is front-loaded, but the trailing "Free. Free." is a literal duplication that wastes space and looks like a copy error. The sentences otherwise earn their place by explaining the confirmation flow.

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

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

For a single-parameter mutation with no output schema, the description covers the effect and the deferred activation, which is the essential mental model. It is still missing re-invocation semantics and the overwrite/conflict case for an account that already has an owner, gaps that matter for a non-idempotent write.

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

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

Schema coverage is 0%, so the single parameter carries no structured documentation. The description implicitly identifies it as the owner's email address ("send that person a link"), which is useful, but it says nothing about format, validation, or what happens if the address is wrong or already in use.

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 concrete action: sending a confirmation link to the owner's email so they can claim ownership of the account. It is clear what the call accomplishes, but it does not distinguish itself from the sibling account_owner_link, which an agent could easily confuse with this 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?

"When the account was made without the owner's email" gives an implied precondition for use, which is more than most tools offer. However, there is no guidance on when NOT to use it (e.g., when an owner already exists) and no mention of the account_owner_link or account_assign_team 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?

Beyond the annotations (which only mark it as a non-idempotent, non-destructive write), the description discloses price and billing behavior ($1.00 per month, $1.00 per call, free on failure) and the daily attachment caps with what happens when the store is full. That is exactly the extra context annotations cannot carry.

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

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

The core purpose and both option flags are front-loaded in the first three sentences, with billing last. It is dense but every sentence carries operational detail; only the attachment paragraph runs a little long.

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 mutation tool with no output schema, the definition covers what is created, its immediate capabilities, the two behavioral flags, cost, renewal source, and failure cost. Nothing an agent needs to decide or invoke correctly is missing.

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

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

Schema coverage is already 100%, so each parameter is documented; the description still adds value by framing open_tickets in terms of ticket_connect_inbox and save_attachments as the email-in file store use case. It stops short of restating every parameter, so it slightly exceeds the high-coverage 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?

The description names a concrete verb and resource (a new email address on its own subdomain) and gives a literal example, e.g. support@acme.useconecto.com. It is unmistakably distinct from siblings like email_update_inbox, email_list_inboxes, and email_release_inbox.

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

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

It gives clear when-to-use scenarios: open_tickets=true for a support inbox and save_attachments=true for supplier invoices sent to an email-in address, with a pointer to ticket_connect_inbox. It does not explicitly state when not to use this tool (e.g., to modify an existing inbox), 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint false, so safety is covered structurally. The description's real contribution is disclosing the response shape (text, HTML, attachment names), which is useful since there is no output schema. 'Free. Free.' looks like an attempt to signal cost, but the duplication makes it ambiguous rather than informative.

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 first sentence is tight and front-loads the return content, which is good. The trailing 'Free. Free.' is a literal duplicate that adds no information and makes the definition look sloppy.

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

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

For a single-object fetch with no output schema, describing the returned fields is genuinely needed and is done, though attachment handling (names only, not content) could be clearer about how to retrieve actual files via email_save_attachments. The undefined identifier parameter and the missing relationship to thread/listing tools leave real gaps.

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

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

There is one required parameter, message_id, and schema description coverage is 0%. The schema only constrains it to 36 characters; the description does not say whether that is a UUID, where to obtain it (email_list_messages?), or what happens on an invalid ID. With a parameter carrying no description anywhere, the description should compensate and does not.

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 verb is implicit in the name but the description does specify the resource and what is returned: one message in full with text, HTML and attachment names. That is more specific than the title 'Read a message'. It does not differentiate from close siblings such as email_get_thread or email_list_messages, so it stops short of a 5.

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

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

No stated conditions for when to call this versus email_get_thread (thread context), email_list_messages (discovery), or the google_mail_read/m365_mail_read counterparts. The repetition of 'Free' hints at a cost consideration but never explains when that matters.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered structurally. The description adds useful ordering behavior ('oldest first'), but does not mention pagination, size limits, or whether all message bodies/attachments are included.

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

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

The core purpose is front-loaded and short, but 'Free. Free.' is duplicated noise that occupies space without adding meaning. The description is brief but not fully efficient.

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

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

For a simple one-parameter read tool with rich annotations and no output schema, the description gives the basic shape of the result (all messages, oldest first). However, it leaves the parameter meaning and return contents underspecified, so an agent would still need to infer or experiment.

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

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

Schema description coverage is 0% for the single message_id parameter, and the description only implies that a message identifies its conversation. It never explains that any message in the thread can be supplied, nor the expected 36-character ID format.

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

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

The first sentence states a specific resource and scope: every message in the same conversation, oldest first. That is clear enough to distinguish a thread fetch from a single-message fetch, though it never explicitly names the sibling tools it differs from (email_get_message, email_list_messages).

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

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

There is no guidance on when to use this versus email_get_message or email_list_messages, and no prerequisites or exclusions are stated. 'Free. Free.' adds no actionable usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds value beyond that by naming what data comes back for each inbox (ticket vs. file-store mode, renewal timing) and that the call is free — useful context an agent wouldn't get from annotations.

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

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

Extremely short and front-loaded, with no filler. The phrasing is a noun-phrase fragment rather than a complete sentence, which is slightly awkward, but nothing in it is wasted.

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

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

With no parameters, no output schema, and annotations covering the safety profile, the description's main job is to say what the list contains — which it does by naming the per-inbox attributes. A little more on ordering or whether all inboxes are returned would make it complete, but the essentials are present.

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

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

The tool takes zero parameters and has no schema properties, so there is nothing for the description to clarify. Baseline for a parameterless tool 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 identifies the resource (this account's inboxes) and the attributes surfaced for each one — ticket-opening behavior vs. attachment saving, plus renewal date. It lacks an explicit verb, but the title 'List inboxes' plus the attribute list makes the operation unambiguous relative to siblings like email_create_inbox or email_update_inbox.

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

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

There is no statement of when to call this versus alternatives (e.g., email_update_inbox for configuration changes or ticket_connect_inbox for wiring an inbox to help desk). The only hint is the trailing 'Free.', which signals cost but not usage context.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety bar is met structurally. The description adds genuinely useful context - newest-first ordering, default coverage of both directions, and 'Free' (no credit cost) - but says nothing about pagination, result volume or what a message record contains.

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

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

It is short and front-loads the resource and ordering, but the trailing 'Free. Free.' is a duplicated token that adds no information and reads as an editing artifact.

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 should ideally sketch the return shape and note default limits (limit defaults to 25, max 100), neither of which appears. For an 8-parameter list tool with low schema coverage, this is adequate but has clear gaps.

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

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

With only 38% schema coverage across 8 parameters, the description compensates partially by explaining inbox, from, since and direction (in/out). It leaves query, limit, label and state unmentioned, so half the surface is undocumented in the description on top of thin schema text.

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 the resource (messages in this account's inboxes) and the scope (received, sent or both, newest first), which lets an agent distinguish it from email_get_message and email_get_thread by granularity. It doesn't explicitly name those siblings, keeping it below a 5.

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

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

Usage is implied through the filter list ('optionally for one inbox, one sender or since a time'), but it never says when to reach for this versus email_list_inboxes or email_get_thread, and gives no exclusions or prerequisites.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds valuable non-obvious consequences: subsequent mail bounces, stored messages stay readable, and the action is free. It does not explicitly discuss reversibility or authorization requirements, but it meaningfully extends the annotation-provided safety profile.

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

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

The description is four short, front-loaded statements with no wasted prose. Each sentence carries useful information: the action, the bounce consequence, message retention, and cost.

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

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

For a simple one-parameter mutation with rich annotations, the description covers key effects and cost, but it leaves gaps around parameter format and when to choose this over adjacent email tools. It is adequate but not fully self-contained.

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

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

There is one required parameter, 'inbox', with 0% schema description coverage, and the description does not explain whether it expects an inbox ID, email address, or another identifier. The description refers to 'an inbox' conceptually but adds no format or selection guidance beyond the schema's type and maxLength.

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

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

The description clearly conveys ending an inbox rental and names the concrete effects: future mail bounces while stored messages remain readable. It is not a tautology, but it does not explicitly distinguish itself from sibling tools such as email_update_inbox or email_create_inbox.

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

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

The phrase 'Stop renting an inbox' implies a usage context, but the description gives no explicit when-to-use guidance, prerequisites, or alternatives to consider. An agent must infer that this is the correct action when an inbox rental should end.

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

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

Annotations only declare the coarse safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false), so the description adds substantial value: dedupe behavior for already-saved attachments, the spam and inline-image exclusions, per-file cost, and a 30-day retention on the source email. The only gap is that the partial dedupe semantics sit somewhat awkwardly against idempotentHint=false without explanation of what still repeats on a second 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?

The opening sentence and exclusions are well front-loaded, but the pricing is stated twice ('$0.001 per file saved' then 'Costs $0.001 per file saved; nothing if none are found'), which is visible duplication that should be collapsed into one clause.

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

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

With one simple parameter, no output schema, and annotations already covering the safety profile, the description covers the important unknowns: side effects, cost, retention, exclusions, and how to read the saved files. The missing piece is how the agent learns which files were created on a given call, since there is no output schema to describe the return.

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

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

Schema coverage is 0% — message_id carries only a 36-character length constraint and no description. The description compensates partially by specifying that the id must belong to a received email, but it never says where to obtain the id (email_list_messages / email_get_message) or what form it takes beyond the implicit length.

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 ('Save the attachments of one received email into the file store'), plus the resulting linkage to the email and the follow-up read path. An agent can distinguish this from sibling tools like email_get_message or files_upload 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?

Explicit when-not conditions: inline pictures such as signature logos and mail marked as spam are not saved, and only attachments of a received email qualify. It also names the concrete follow-up alternatives (files_read_text, documents_read_pdf, files_ocr) for consuming the result, leaving nothing to inference.

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

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

Beyond the annotations, the description discloses material behavior: cold-outreach checking, possible account pausing, the AI-assistant disclosure line unless by_person is set, attachment and recipient limits, exact cost structure, and that failures are not charged. These are important operational consequences an agent cannot infer from the schema or annotations.

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

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

The description is dense but front-loaded: it opens with the core action, then layers threading, attachments, recipient limits, policy, disclosure, and cost. The cost sentence is long but useful. It could be split for readability, but no sentence is clearly wasted.

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

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

For a 9-parameter mutation tool with low schema coverage and no output schema, the description covers the critical behavioral context: limits, policy enforcement, AI disclosure, and pricing. Minor gaps remain around cc/html/subject and the success response, but the essential decision and invocation context is present.

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

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

With only 22% schema description coverage, the description compensates for most important parameters: inbox, to-recipient cap, reply_to_message_id threading, attachments from the file store with size/file limits, by_person behavior, and text usage for download links. It does not explicitly explain cc, html, or subject, but those are comparatively self-evident.

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

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

The description states a specific verb and resource: 'Send from one of this account's inboxes.' It also clarifies threading and attachment behavior, so the core action is unambiguous. It does not explicitly distinguish itself from sibling mail tools such as google_mail_send or m365_mail_send, which keeps it from a 5.

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

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

It gives explicit when-to-use guidance ('For support, operations and replies, not cold outreach'), states hard limits ('at most 20 new addresses a day'), describes enforcement ('the third within 7 days pauses the account's email'), and names an alternative for large files ('Big files are cheaper as a download link (files_get)'). This is unusually complete routing and policy guidance.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false. The description adds genuinely useful context beyond them: the $0.001 per-call cost, 'nothing if it fails', and detailed downstream behavior of save_attachments (store space counting, skipping when full, listing non-saved attachments).

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 editable aspects in one dense sentence, and the parenthetical for save_attachments is informative. Minor redundancy in stating '$0.001' twice ('$0.001. Costs $0.001 per call...'), which is slightly 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?

For a 5-param mutation tool with annotations and no output schema, the description adequately explains behavior, cost, and field effects. The only gap is no explicit statement of permissions or how to identify the target inbox, but overall it is complete 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 coverage is 60%, and the description fills key gaps: it maps display_name as 'sender name' (schema has no description for it) and explains save_attachments/save_files_per_day/save_mb_per_day semantics. Only the required inbox param is left undescribed, which is self-evident.

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 (change) and resource (an inbox), and enumerates the three updatable aspects: sender name, email-in toggle, and 24h save limits. It is clearly distinguishable from create/list/release inbox siblings, though it does not explicitly name them.

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

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

Usage is implied by describing what each editable field does (e.g., turning email-in on/off, raising save limits), but there is no explicit when-to-use guidance, prerequisites, or comparison against siblings like email_save_attachments or email_create_inbox.

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

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

Annotations already declare idempotent=true, destructive=false, readOnly=false, so the safety profile is covered. The description adds genuinely new behavior: labels replaces the existing set, and an inbound message from outside will reopen a thread, plus cost-per-call with no charge on failure — useful for a paid mutation.

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

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

Purpose is front-loaded, but the pricing is stated twice ('$0.001.' followed by 'Costs $0.001 per call; nothing if it fails'), which is pure redundancy. The single long colon-chained sentence also buries the reopen rule at the end.

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 3-param mutation with no output schema, the description covers state semantics, label replacement, re-open behavior, and billing — enough to call it confidently. It never clarifies that state is optional and labels can be updated alone, which is a minor omission.

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

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

Schema coverage is 67% and already documents message_id and the labels replacement behavior. The description adds meaning the enum lacks by glossing states — open as needs-a-reply, waiting as on-the-other-side — which is real value over a bare enum 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?

States a specific verb ('mark') plus the resource ('email thread') and enumerates the accepted states and label setting. It also names the sibling consumer, email_list_messages, so the agent can distinguish this mutation from the read-side filter 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?

Explains the motivating context ('so you never reread or answer twice what you already dealt with') and points at email_list_messages as the filtering counterpart. It does not, however, give an explicit when-not or contrast with email_update_inbox, so alternatives are only implied.

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