Conecto E-signature

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?

Adds real context beyond the annotations: signers receive a short email and their links stop working, and the action is free. However, with destructiveHint=true it should state whether cancellation is reversible and whether the request record remains retrievable via esign_get; the 'reason' parameter's effect on the notification is unexplained.

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

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

Three short sentences, front-loaded with the action and its constraint, with zero padding; even 'Free.' carries a distinct fact.

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

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

For a destructive two-parameter mutation with no output schema, the description covers the user-visible consequence (email + dead links), which is the main thing an agent needs. It omits the reason parameter and whether the caller gets back a cancelled-request object, which are modest gaps.

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

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

Schema coverage is only 50% — request_id documents itself ('the request_id esign_send returned') but 'reason' has no schema description at all. The description never mentions either parameter, so it does nothing to close the gap on the undocumented reason field.

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

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

States a specific verb (stop/cancel) and the exact resource state it acts on ('a request before everyone has signed'), which cleanly separates it from esign_remind, esign_send, and esign_get in the sibling list.

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?

'Stop a request before everyone has signed' gives a clear triggering condition, and 'Free' hints that cost is not a barrier. It stops short of naming alternatives, e.g. whether to use esign_remind when signers are merely slow.

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, so the safety profile is covered. The description adds genuine value beyond that by scoping the blast radius (existing sent requests survive) and cost (free). It does not state whether deletion is permanent or restorable, which keeps it below a 5.

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

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

Three short, front-loaded sentences with no filler: the action first, then the blast-radius caveat, then the cost note. Every clause carries information an agent would otherwise have to guess.

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 the essentials: what is removed, what is preserved, and that it costs nothing. It could go slightly further by noting the response on success or how to confirm the template was removed.

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

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

Schema description coverage is 100% and the single `template` parameter is documented in-schema with a format example. The description adds no naming, format, or slug-resolution detail, so the schema does all the work and 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 gives a specific verb and resource ("Delete a saved template"), which clearly separates it from the sibling list/save/send template tools. It stops short of explicitly naming those siblings, but the operation is unambiguous.

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

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

The note that already-sent requests are unaffected implicitly reassures an agent that deleting is safe for in-flight signing flows, and "Free" hints at no billing impact. However, there is no explicit when-to-use versus esign_save_template or esign_list_templates, and no statement of prerequisites (ownership, published state).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the enumerated signer states (waiting, to sign, opened, signed, declined), the condition under which the signed PDF and download link appear, and that the call is free — useful for deciding whether to poll 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?

A single tight sentence with the core purpose front-loaded ('Where a signature request stands') followed by the state enumeration and the PDF condition. The trailing 'Free' is a slightly abrupt append but still earns its place as cost 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?

There is no output schema, so the description carries the burden of describing the return value — and it does, naming the per-signer statuses and the conditional PDF/link. It falls short only on edge cases (unknown request_id, partial signing) for a single-parameter read tool.

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

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

Schema coverage is 100% and the single request_id parameter is fully documented in the schema, including that esign_send produces it. The description adds no additional parameter detail, 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 states a concrete retrieval purpose — showing where a signature request stands, per-signer status, and the resulting signed PDF — which is more specific than the title alone. It doesn't name or distinguish itself from siblings like esign_list or esign_signing_link, so an agent must infer the boundary itself.

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: read this when you want the status of an existing request or the signed PDF once complete. There is no explicit guidance on when to prefer esign_list (enumerate requests) or esign_signing_link (get a signing URL) instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds the meaningful ordering trait ('newest first') that annotations do not carry. It says nothing about pagination or result size, and 'Free.' is left ambiguous for a tool the agent may call repeatedly.

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 lean and front-loaded on the resource, with no filler sentences. The unexplained 'Free.' is the only phrase that does not clearly earn its place.

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

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

For a simple, read-only, two-parameter list tool whose annotations cover safety and whose schema covers types/enums/bounds, this is close to adequate. Missing pagination behavior and the unclear 'Free.' clause leave minor gaps an agent may have to guess at.

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. It explains the purpose of 'status' (filter to one status value) but says nothing about 'limit' beyond what the schema already encodes (default 20, max 100). Partial compensation for a two-parameter schema.

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

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

The description names the resource (signature requests) and ordering (newest first) plus the optional status filter, which is enough to distinguish it from esign_get (single request) and esign_list_templates (templates). The verb 'list' is only implied, carried by the tool name rather than the description itself.

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 use this versus sibling tools such as esign_get or esign_list_templates, and no prerequisites or conditions are given. The trailing 'Free.' hints at something (cost or plan tier) but is never explained.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds 'Free' and lists returned fields, which is useful context, but it does not cover pagination, limits, or ordering behavior.

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

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

The description is extremely concise (one sentence plus 'Free.') and front-loads the resource and its attributes. The fragmentary style is efficient, though it could be slightly clearer with a verb.

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

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

For a zero-parameter read-only tool without an output schema, the description provides the key returned fields and cost context. It omits any note on whether all templates are returned or if pagination applies, but otherwise sufficient given 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?

The tool has zero parameters, so the baseline is 4. The description appropriately does not discuss parameters since none exist.

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 the resource (saved templates) and the attributes returned (names, titles, roles, fields), making it clear what the tool retrieves. However, it lacks an explicit verb and does not differentiate from siblings like esign_list or esign_get, relying on name and title for that distinction.

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 tool versus alternatives such as esign_list, esign_get, or esign_send_template. The only contextual hint is 'Free,' which relates to cost rather than selection criteria.

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 real context beyond annotations: a per-request daily rate limit, a $0.02 per-call charge, and a no-charge-on-failure policy — the last is especially useful for a non-idempotent, externally-facing email action. It does not say what happens when nobody is left to sign or whether completed/cancelled requests error out.

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

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

Three short sentences, front-loaded with the action, followed by the rate limit and the cost. Nothing is redundant and nothing could be cut without losing information.

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

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

For a single-parameter action tool with annotations and no output schema, the description covers the economically important facts (rate limit, price, failure cost) and the recipient scope. Minor gap: no statement of behavior on requests with zero pending signers or in terminal states.

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

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

Only one parameter with 100% schema coverage, and the schema already explains it is the request_id returned by esign_send. The description only alludes to it via 'per request', so it adds nothing beyond the schema; baseline 3 applies.

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

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

States a specific verb (email) and a specific recipient set (everyone who still has to sign), plus that the reminder carries their link. It is clearly distinguishable from esign_send (new requests) and esign_signing_link, though it doesn't name those siblings explicitly.

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

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

The 'at most once a day per request' line implies this is a nudge/chase action rather than initial delivery, and the cost line discourages casual use. But there is no explicit when-to-use vs esign_get/esign_signing_link/esign_cancel, and no stated precondition such as the request being pending with unsigned parties.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description earns credit beyond them by disclosing the $0.001 per-call cost, that failures are free, the validation rule that every role needs a signature field, and that re-saving a name overwrites it. It does not say what is returned (template id) or whether deletion/replacement is recoverable.

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

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

Front-loaded with purpose and mechanism, and the follow-up sentences about role ordering and name replacement are useful. The cost is stated twice ('$0.001. Costs $0.001 per call'), which is wasted text in an otherwise tight 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 mutation tool with no output schema and 8 parameters, the description covers pricing, failure behavior, coordinate conventions, validation constraints, and overwrite semantics. The main remaining gap is the response shape (template identifier) and any preconditions on the source PDF, which an agent would want before calling.

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?

At 63% schema coverage the schema carries much of the burden, but the description adds genuine meaning: roles are signers 'in order', field coordinates are percentages of the page consistent with esign_send, and every role must carry a signature field. It leaves 'order' (parallel vs sequential), 'message', and 'expires_in_days' unexplained, so not a 5.

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

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

States a specific verb and resource ('Save a PDF from the file store ... as a template') and pins down the differentiator: fields are placed once per signer role so later sends don't need re-placement. That separates it from esign_send (one-off send) and esign_send_template (reuse), which are its nearest siblings.

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 the use case clearly ('contracts, NDAs and waivers go out later without placing a field again') and implicitly contrasts with esign_send by referencing it for coordinate semantics. It also states the replacement rule for reusing a name. It stops short of an explicit 'use X instead when...' exclusion, so a 4 rather than 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 only declare the generic profile (not read-only, open-world, not idempotent); the description adds real behavioral substance the annotations cannot: signers are emailed immediately, parallel vs sequential ordering, per-signer links and browser signing, signed PDF plus certificate returned to everyone, and the exact event names emitted. It even discloses cost ($0.20 per call, nothing on failure), which is a rare and highly actionable detail.

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, then layered into sourcing, signing mechanics, field placement, ordering, and events. Nearly every sentence carries operational information; the base64 warning is a worthwhile guardrail, though the paragraph is dense enough that an agent must read the whole block to extract the field-placement rules.

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

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

With no output schema, the description usefully substitutes event names for return-value knowledge and covers cost and failure behavior. It stops short on a few things an agent would want: what identifier the call returns, the expires_in_days default/max, and any pointer to esign_cancel or esign_remind for follow-up.

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 43%, so the description must carry weight and it does: it explains the fields array coordinate system (percent from top-left), supplies a sizing heuristic ('30 x 5 fits a line'), and states the hard rule that every signer needs a signature field. The generated-signature-page behavior when fields is omitted is likewise explained. Minor params (expires_in_days, message, title) are left 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?

Opens with a specific verb, resource, and scope: send a PDF from the file store to up to 10 people to sign. An agent immediately knows this is the ad-hoc send path rather than the template path, though the sibling esign_send_template is never named, so the differentiation is inferred from 'from the file store' 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 when-to-use guidance, including how the file gets into the store (files_upload_link page_url or documents_create_pdf) and an explicit when-not ('Never type a PDF out as base64'). It also routes event consumption to account_events or notify_subscribe. The one gap is that it never states when to prefer esign_send_template over this tool.

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 safety and idempotency, and the description adds real value beyond them: per-request cost, that each send produces emails, signing links, and a signed PDF with certificate, plus the 50-set cap. It loses a point for repeating the pricing sentence nearly verbatim and for the opaque clause 'nothing if none are found', which does not say what would not be found.

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 mostly dense, but the pricing appears twice in adjacent sentences ('$0.20 per request sent. Costs $0.20 per request sent...'), which is pure waste in a four-sentence description. The trailing 'nothing if none are found' clause is ambiguous enough to add confusion rather than 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, the description carries the return story by naming emails, links, and the signed PDF with certificate. Missing pieces are modest but real: no mention of expiry behavior, signer-count limits per role, or what happens if a template is not found (the ambiguous 'none are found' hints at it without resolving 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?

With 67% schema coverage it usefully explains the un-inlined `signers` parameter — one signer per template role, in the template's order — and clarifies that each entry in `sets` is one request's signer list. It does not touch `expires_in_days`, which has no schema description either, so that parameter remains undocumented end to end.

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 ('Send a saved template to new signers') and immediately scopes the two modes: one request via signers, or up to 50 batched requests via sets. It explicitly relates itself to esign_send, so an agent can place it 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 the concrete case for the batch mode ('the same NDA to every new contractor') and distinguishes single vs. multi-request sends. It stops short of an explicit exclusion against siblings like esign_send or esign_signing_link — it only says behavior is the same, not which to pick when.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: anyone holding the link can sign as that person, and a read-or-draft-only key receives "[redacted]" instead of a usable link. The "Free" note also discloses a pricing trait not visible in annotations.

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

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

Four short, front-loaded sentences with no filler; the security warning follows immediately after the purpose. The trailing "Free." fragment is terse to the point of being slightly ambiguous.

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

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

With only two parameters, full annotation coverage, and no output schema, the description supplies the critical missing context: the link is a bearer credential and may be redacted by key scope. Edge cases such as already-signed signers or link expiry are not addressed but are not essential to call 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 50%: request_id is documented in the schema, but email has no description there. The description implies a single signer is targeted ("of one signer", "give it only to them") without explicitly stating that email identifies that signer, so it only partially compensates.

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

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

The description names a specific resource ('the signing link of one signer') and disambiguates it from the sibling esign_remind, which emails links rather than returning them. The verb is implied by the tool name/title rather than stated in the description, which keeps it just 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?

It states the intended use case ("to hand over yourself (in a chat, say)") and gives a constraint ("give it only to them"), plus routes email-based delivery to esign_remind. There is no explicit when-not-to-use beyond the delivery caveat.

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