Conecto Help desk

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?

Goes well beyond the annotations (idempotent, non-destructive) by describing what actually happens: new mail opens tickets, thread replies are appended and reopen tickets, outbound replies send from the inbox address. It also discloses exclusions (OOO, bounces, list mail, spam) and the cost model ($0.001 per call, free 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?

Dense but front-loaded: the primary effect comes first, then threading, then exclusions, then the flag-off case, then prerequisite and cost. Every sentence carries distinct information; nothing restates the title or schema.

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

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

No output schema exists, but the description covers the effects, side effects, exclusions, prerequisite, and pricing an agent needs before invoking. Nothing material is missing for a two-parameter configuration 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 0%, so the description must carry the load, and it does: the open_tickets flag is fully explained in both states (true = new tickets, false = no new tickets but replies to existing tickets still land). 'Inbox' is contextualized as one of the account's email inboxes created via email_create_inbox.

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 ('Make one of the account's email inboxes a support inbox') and immediately explains the resulting behavior. It is clearly differentiated from sibling email_list_inboxes/email_update_inbox by naming email_create_inbox as the prerequisite.

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

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

Gives an explicit prerequisite ('Create the inbox first with email_create_inbox') and explains the alternative mode of the open_tickets flag. It does not explicitly contrast with email_update_inbox or ticket_update_settings, so routing among configuration siblings is left partly implicit.

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

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

Beyond the annotations (which only hint it is a non-destructive write), the description discloses cost ($0.01 per call, waived on failure), default requester non-notification, the acknowledgement source inbox, and reply-routing behavior. This is substantial behavioral context an agent would not otherwise have.

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

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

Three sentences, purpose front-loaded, with the alternative routing and cost appended. Dense but each clause carries information; could be marginally tighter but no wasted padding.

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

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

For a 10-param mutation tool with no output schema and thin annotations, the description covers cost, notification behavior, and inbox routing well. It omits what a successful call returns (ticket ID/handle) and any inbox-connection prerequisite, which are meaningful gaps but not fatal.

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

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

Schema coverage is only 40%, so the description must compensate. It richly explains email_requester's effect and reply routing, but leaves email, message, name, category, and priority unexplained (priority only has an enum in schema). Helpful for one param but gaps remain for others.

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: 'Open a support ticket for a customer request', and distinguishes it from ticket_connect_inbox (which opens tickets automatically from emails). It does not explicitly differentiate from chat_create_ticket, but the ticket_-namespace and manual-creation framing make the intent clear.

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 parenthetical 'email to a support inbox opens one by itself; see ticket_connect_inbox' tells the agent when not to use this tool, and points to the alternative. It also notes the email_requester conditional, giving a clear context for use, though it stops short of stating prerequisites like a connected inbox.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful non-schema context — the $0.001 per-call cost and that failed calls are free — but says nothing about whether deletion is permanent, what happens to tickets using the reply, or whether confirmation is required.

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

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

Two short sentences, the action and identifier front-loaded, and the cost note second. No filler.

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

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

For a destructive one-parameter mutation with no output schema, the core action and cost are covered, but an agent still lacks the essentials of whether deletion is irreversible and how failures/no-match cases behave beyond 'nothing charged'.

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 one parameter and 0% schema description coverage, the description minimally compensates by stating that the reply is identified 'by name' rather than by ID. It does not describe the name format, case sensitivity, whether a full or partial name is expected, or what happens if no match exists.

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 reply') and the title reinforces it. It is clear what the tool does, though it doesn't differentiate itself from similar siblings like ticket_save_template or ticket_list_templates, and it never uses the 'template' terminology the tool name and siblings use.

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 (e.g. listing templates first to confirm the name, or saving/editing instead of deleting). The only extra information is pricing, not usage context.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description needn't repeat that. It adds real value by disclosing the returned payload's composition and by flagging that attachments and full email text live in email_get_message, i.e. an explicit scope limit. The duplicated 'Free. Free.' conveys zero-cost invocation but is presented as noise rather than explained, so it doesn't reach 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?

The content is front-loaded into a single dense sentence that earns most of its words by enumerating the payload. However, 'Free. Free.' is a duplicated fragment that wastes space and reads as an editing artifact, dragging down structure and 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?

With no output schema, the description carries the burden of saying what comes back, and it does so thoroughly by naming every section of the ticket record plus the SLA state and rating. Combined with the cross-tool note about attachments, an agent has enough to call this correctly; only pagination or size behavior is unaddressed.

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

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

There is a single required parameter and schema coverage is 100%, with the schema itself explaining 'The ticket number, e.g. 42 for ticket #42.' The description adds no meaning beyond that, which is the expected baseline case when the schema already documents the only 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?

The description names the resource (one ticket) and enumerates exactly what comes back: request, replies, customer messages and notes, tags, custom fields, SLA state and rating. It is recognizably distinct from ticket_list because it clearly returns a single ticket's full detail. The verb is only implied by the title ('Read a ticket'), not stated in the description itself, 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?

Usage is implied rather than stated: 'One ticket' signals a single-record fetch versus the list sibling, but no explicit when-to-use or when-not-to-use guidance is given. The one concrete routing hint is the parenthetical pointing to email_get_message for attachments and full text of customer emails, which is genuinely useful but covers only a sub-case.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds scope content by naming the four settings categories exposed, but says nothing about whether sensitive values (API keys, inbox credentials) are included or how inboxes are represented.

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

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

Extremely short but poorly formed: a sentence fragment with no verb and a duplicated 'Free. Free.' token that reads as an artifact. It is not front-loaded with an action statement, so the brevity is under-specification rather than efficiency.

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 is the only place a caller can learn what comes back, and listing the four settings categories partially serves that role. However, it omits the return shape and any note that the response is a read-only snapshot, so an agent still guesses at the payload.

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 schema semantics are a non-issue and the baseline of 4 applies. The description makes no false claims about inputs.

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

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

The title and name carry the action ('Read help desk settings' / ticket_get_settings), while the description only enumerates the settings covered: SLA targets, auto-close, satisfaction survey, support inboxes. It never states a verb or that it returns the current configuration, so it reads as a dangling noun phrase rather than a statement of what the tool does.

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 guidance on when to call this versus ticket_update_settings or ticket_report, no prerequisite or permission notes, and no indication of whether it is safe to call frequently. The only implicit steer is that it is a read, which comes from the name rather than the text.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds useful operational context: default status is open and pending, results are newest activity first, and views have specific sort semantics such as longest-waiting-first or most-overdue-first.

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 and dense with useful information, but it contains duplicated artifacts such as 'Free. Free.' and the awkward 'within within_minutes', making it less tight than it should 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?

For a 12-parameter list tool with no output schema and low schema description coverage, the description covers nearly all filtering and view semantics. It is mostly complete, though it does not discuss pagination/limit behavior or whether filters and view can be combined.

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

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

Schema description coverage is only 17%, so the description carries most of the semantic burden. It explains most parameters in natural language: filters, query text, custom fields, CRM contact/company, since time, status default, and every view enum value, with only the limit parameter left mostly to the schema constraints.

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 establishes that this retrieves tickets, with filtering by status, priority, requester, tag, fields, query text, CRM contact/company, or since time. It also distinguishes the view-based queue mode from ordinary filtering, though it does not explicitly name sibling tools like ticket_get or ticket_report.

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 explains the main usage pattern well: use filters for ticket lists, or use a view for a work queue, and it defines what each view means. It does not state when not to use this tool versus ticket_get, ticket_report, or other nearby 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=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safe-read profile is fully covered. The description adds some value by enumerating the returned fields (text, status, tags), but says nothing about pagination, ordering, or volume. The duplicated "Free. Free." hints at a cost/rate-limit property without ever explaining it, which borders on unhelpful.

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

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

The first sentence is tight and front-loaded, naming the resource and returned fields immediately. But "Free. Free." is duplicated and unexplained, which is pure noise and reads as an error rather than information. About a third of the description 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?

For a zero-parameter read-only list tool with full annotation coverage and no output schema, the essentials are present: what comes back and roughly what fields. What is missing is the shape of the return (ordering, whether all templates are returned at once) and any meaning for the "Free" claim. Adequate but with clear gaps.

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

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

The tool takes zero parameters, so the baseline is 4. The description does not need to explain parameter semantics and correctly spends no words on them.

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 phrase "Every saved reply with its text, status and tags" communicates that this returns the full set of canned reply templates, and the returned fields are named. However, the verb is implied rather than stated, and nothing distinguishes this from the many other ticket_* tools or clarifies canned-reply-vs-ticket scope. The trailing "Free. Free." contributes no meaning.

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 call this versus alternatives such as ticket_list, ticket_get, or ticket_save_template. An agent must infer from name and title alone that this is the read side of the canned-reply workflow, and gains no signal about exclusions or prerequisites.

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

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

Adds substantial behavior beyond the annotations: what data moves (messages, notes, email threads, tags, fields), that future mail in the duplicate's thread reroutes to `into`, that `into` reopens if the duplicate was open, that the duplicate is resolved and linked, and that replies go only to `into`'s requester. It also discloses cost ($0.01 per call, free on failure), which annotations never cover.

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 verb, resource, and param roles; each subsequent clause carries new, actionable information (data moved, mail rerouting, reopen side effect, cost). No filler sentences.

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-param mutation with no output schema, the description covers side effects, downstream routing, and cost/failure pricing thoroughly. It does not state whether the merge is reversible, what permissions are needed, or what errors occur for self-merge or missing tickets.

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 schema gives both integer params an identical, ambiguous description ('The ticket number, e.g. 42 for ticket #42'), so the description's assignment of roles (number = duplicate being absorbed, into = surviving ticket) is the only source of disambiguation. It stops short of covering edge cases like self-merge or invalid numbers, so not a full 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 (merge) and resource (duplicate ticket) plus the direction of the merge: `number` collapses into `into`. An agent can distinguish it from ticket_update, ticket_delete, and ticket_reply 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?

The use case ('a duplicate ticket') is implied clearly, but there is no explicit when-to-use/when-not guidance and no alternative named (e.g., resolve a ticket via ticket_update instead of merging). The agent must infer the selection conditions.

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

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

The description adds a lot that annotations cannot: the reply leaves from the ticket's support inbox in the same thread so the customer's answer returns to this ticket, an alternate support inbox is picked when one exists, otherwise Conecto's standard ticket email is used. It also discloses the $0.05 per-call cost (waived on failure) and the by_person AI-disclosure line, plus the side effect that a reply reopens a resolved ticket. Nothing here contradicts the declared readOnlyHint=false / destructiveHint=false / idempotentHint=false profile.

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

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

The key distinction (internal=false reply vs internal=true note) is front-loaded and every clause carries information, including the cost and AI-disclosure details. The structure is one dense run-on paragraph with stacked parentheticals, which makes the status/template interactions slower to parse than they need to 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?

For an 8-parameter, non-idempotent outbound-communication tool with no output schema, the description covers the important unknowns: delivery channel, thread continuity, fallback sender, template side effects, status side effects, attachment limits, and cost. What it omits is a confirmation of what the call returns or how partial failures (e.g. attachment too large) surface, which is a small remaining gap rather than a blocker.

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

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

Schema coverage is only 38% across 8 parameters, so the description has to carry the load and largely does: internal defines the private-note mode, template explains both the saved reply and its status/tag side effects, body explains placement relative to the template, status explains pending/resolved semantics, inbox explains thread behaviour, and attachments references the file store and the support-inbox restriction. Only the enum value 'open' is left undefined, which is a minor gap.

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

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

The opening clause gives a concrete verb (email a reply) and resource (the ticket requester), and immediately splits the two modes: external reply versus internal-only note. That is precise enough to act on. It does not, however, name or contrast with the nearby siblings an agent might confuse it with, notably ticket_update (status/field changes without a message) or chat_reply, so differentiation is left to inference.

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 context is stated rather than implied: the notes on template applying its status and tags, status setting the outcome afterwards, and 'without it a reply reopens a resolved ticket' tell the agent how to sequence the call. It also constrains attachments to replies from a support inbox. There is no explicit when-not or named alternative tool, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the return content in detail and noting the trailing 'Free' cost signal, which is not encoded anywhere in structured fields; it stops short of saying whether data is live or cached and whether figures are scoped per agent/inbox.

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 single sentence is well front-loaded with the time window before the metric list, and every metric named is informative. However, it is a dense run-on, and the duplicated 'Free. Free.' is an obvious redundant artifact that costs it a point.

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

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

For a one-parameter, read-only report tool with no output schema, the description does the essential work of enumerating the returned metrics and giving the default window. Missing pieces such as data freshness, timezone handling, and any per-agent/per-inbox scoping are minor for this complexity level.

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 for the single `days` parameter. It names the parameter and restates the default of 30, which gives the agent the window semantics, but it omits the 1-365 bounds and whether days are calendar days or rolling, so it only partially compensates for the schema gap.

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

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

The description names a specific resource (support tickets) and enumerates exactly what the report contains: opened/resolved counts, backlog breakdown, first-response and resolution times, SLA met/breached, satisfaction, and channel/priority/tag distributions. That enumeration makes it clearly distinguishable from ticket_list or ticket_get, which return raw tickets rather than aggregates.

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 statement about when to prefer this over ticket_list, ticket_get, or ticket_get_settings, and no exclusions or prerequisites. Usage is only implied by the word 'report' and the metric list, so the agent must infer that this is the analytics/summary entry point.

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?

Rich beyond the annotations: discloses replace-on-name-collision semantics (reinforcing idempotentHint), placeholder interpolation variables, that status/tags are applied on send rather than stored-only, and a per-call cost with a failure exemption. These are exactly the operational facts an agent cannot infer from readOnlyHint/destructiveHint flags.

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

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

Three tight sentences: what it does, the placeholder vocabulary, then the send-time side effects and pricing. The identifying clause is front-loaded and no sentence is filler.

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

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

Covers the mutation semantics, templating, and cost for a four-parameter write tool with no output schema. The only mild gap is not saying what the save returns (e.g., a template id) or how name length limits apply, but these are minor for a definition of this density.

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 'tags' is documented in the schema), so the description carries the load and does it well: it lists the exact supported placeholders for 'body', explains that 'status' changes the ticket state at send time, and ties 'tags' to send-time behavior. That adds meaning well beyond the raw 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 concrete verb and resource ('Save a canned reply (a macro) under a name') plus the key semantics 'replacing the one with that name', which already distinguishes it from ticket_delete_template and ticket_list_templates. An agent can identify the operation without opening the schema.

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

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

Gives a clear use context by tying the saved macro to ticket_reply ('applied each time it is sent with ticket_reply') and notes the upsert/replace behavior. It does not explicitly exclude alternatives such as ticket_list_templates or ticket_delete_template, so it falls short of a full when/when-not statement.

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 disclose non-readonly, idempotent, non-destructive, closed-world behavior. The description adds substantial beyond-annotation context: cost ($0.01 per call, free on failure), the side effect that resolving may email a satisfaction survey, how ask_rating overrides per call, what 'pending' means operationally, that priority affects SLA targets, and that 0 unlinks CRM associations.

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 a dense but waste-free paragraph, front-loaded with 'Change a ticket' and then listing fields. Every clause adds useful behavioral or semantic detail, though the run-on structure could be more scannable.

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 12-parameter mutation tool with no output schema, the description covers the key behavioral side effects (survey email, cost) and parameter semantics well. It omits some detail such as whether unspecified fields are preserved, permission requirements, and error behavior, but remains largely complete for correct invocation.

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

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

Schema description coverage is only 33%, so the description must compensate. It explains enum semantics for status (pending = waiting on customer) and priority (SLA targets follow), clarifies assign_to accepted values ('me', another bot's name, '' for nobody), contact/company unlinking with 0, and ask_rating behavior. It adds little for category, subject, or number, but overall meaningfully supplements 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 (change) and resource (a ticket), then enumerates exactly which ticket fields can be changed (status, priority, category, subject, tags, custom fields, assignee, CRM contact/company). This clearly scopes it apart from siblings like ticket_get, ticket_list, ticket_create, and ticket_update_settings.

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

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

The description implies when to use it (to change ticket fields) and adds context such as cost and survey behavior, but it never explicitly names alternatives or when not to use it. An agent can infer usage but receives no explicit routing guidance against ticket_reply, ticket_get, or ticket_update_settings.

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

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

Goes well beyond the annotations: it discloses that SLA targets are replaced wholesale (a priority left out loses its SLA), that new targets apply to open tickets immediately, how the clock pauses on 'pending', and the $0.001 per-call cost with no charge on failure. Nothing here contradicts readOnlyHint=false / idempotentHint=true; the wholesale-replacement nuance is exactly the kind of destructive-adjacent behavior an agent needs.

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 patch semantics, then per-parameter detail, then cost. The JSON example is the longest element but directly disambiguates the nested sla shape, so it earns its space; there is no filler.

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

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

For a 3-parameter mutation with no output schema, it covers semantics, patch behavior, SLA clock rules, and cost. Minor gaps remain: it doesn't say what is returned, whether closed/resolved tickets are affected retroactively, or any permission requirements, though annotations already cover safety and idempotency.

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, and it does: sla is explained with priority keys, both minute fields, and a concrete JSON example; auto_close_days is defined including the 0 = never sentinel; ask_rating_on_resolve is explained as a one-click Good/Bad email. Only the numeric bounds (e.g., 43200-minute cap) are left to the schema, which is appropriate.

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

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

States a specific verb and resource ('Set the help desk's SLA targets, auto-close and satisfaction survey') and immediately clarifies the patch semantics ('what you leave out stays as it is'). An agent can distinguish this from the read-only sibling ticket_get_settings without opening either schema.

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

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

The 'leave out = unchanged' rule gives clear context on how to call it incrementally, which is the key usage decision here. It does not, however, name alternatives (e.g., inspect first with ticket_get_settings) or warn about when not to call it, so it stops short of the explicit when/when-not guidance a 5 requires.

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