Conecto CRM

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Front-loaded with the core action and resource list, and every clause carries information. It is docked slightly for the redundant cost sentence – '$0.001. Costs $0.001 per call' repeats the price twice.

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

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

With no output schema, the description covers side effects, auth, cost, and the failure case ('nothing if it fails'), which is most of what an agent needs. What is missing is any statement of what a successful response contains, so an agent must infer that from the idempotent/non-destructive annotations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For a 4-param, no-output-schema read tool, this covers scope, ordering, the security-relevant `verify` mode, cost, and the competing tool. Remaining gaps are the two undocumented filters (`since`, `limit`) and any hint about entry shape, but nothing blocking an agent from calling it correctly.

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

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

Schema coverage is only 25% (only `action` is documented in-schema), so the description has to compensate. It does explain `verify` semantics well and effectively hints at `action` prefixes by listing event categories, but `limit` and `since` get no treatment at all — no guidance on time-window format or default/max behavior.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

No output schema exists, so the description must explain return values; it enumerates balance components, holds, daily budget, auto-reload state, and free reads/downloads used. With annotations covering safety and zero parameters, this is complete for the tool.

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

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

This tool has zero parameters, so there are no parameter semantics to document. The baseline for 0 params applies.

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

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

The description names the resource (account balance) and enumerates the specific fields returned, so an agent knows this is a balance/credit-status read. It does not explicitly contrast with account_dashboard_link or other account_* siblings, so it is clear but not fully differentiated.

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

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

No when-to-use, when-not-to-use, or alternative guidance is provided. The word "Free" hints at cost but does not say when to call this instead of sibling account tools.

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

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

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

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

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

Front-loaded with the core idea (one-time link to a snapshot of one area) and every sentence carries usable information about usage or lifecycle. The prose is conversational and slightly padded, but not wasteful enough to drop below 4.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100% — the single optional 'areas' parameter is documented with an example and a default of 'all'. The description only implicitly references areas ('each area's data'), adding no syntax or filtering detail beyond the schema, so the baseline 3 applies.

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

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

The description names the concrete resource: per-area data storage/processing locations, including the operating company, the country or region, and what is held. That is specific enough to distinguish it from every account_* and books_* sibling, none of which cover data residency, though the verb is implied rather than stated.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that 'correspondence' governs whether emails and tickets are deleted or retained for legal reasons, and that email/phone are the identity anchors used for matching and suppression. Only the phone parameter's role is left implicit.

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

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

States a specific verb and resource ('Erases one person across every area') plus the legal trigger (GDPR Art. 17). An agent can immediately distinguish this from account_export_person or account_find_person, which operate on the same person without destroying data.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

States a specific verb and resource — reading recent account events caused by actors outside the bot — and enumerates the event families (applications, bookings, form responses, signatures, emails, goals) plus custom events from account_emit_event. This makes it easy to distinguish from account_audit_log and from the write-side sibling account_emit_event.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

States a specific verb and resource with precise scope: everything the account holds, as JSON Lines per area plus stored files, in ZIPs up to 24 MB written to the file store. That scope distinguishes it from the narrower account_export_person and books_export siblings without needing to name them.

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

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

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

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

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

Placeholder

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

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

Placeholder

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

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

Placeholder

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

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

Placeholder

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

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

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

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

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

Gives a clear trigger (

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

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

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

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

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

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

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

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

For a two-optional-param lookup with annotations covering the safety profile and no output schema, the description covers purpose, trigger, return contents, cost and sibling routing. Nothing an agent needs in order to choose and call this correctly is missing.

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

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

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

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

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

States a specific verb and resource ('Every record this account holds about one person') with an explicit scope ('across every area') and an explicit matching key (email or phone). It also names the two closest siblings, account_export_person and account_erase_person, so an agent can differentiate without opening any schema.

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

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

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

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

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

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

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

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

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

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

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

For a no-param, read-only tool with full annotation coverage and no output schema, the description is close to sufficient but omits what actually comes back (e.g. a URL vs. raw values) and never states the read action. It is adequate rather than complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The enumeration of brand fields is a small bonus that hints at the returned content.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool applies.

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

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

States a specific read of a specific resource: the account's limits, their standard/current/max values, and the business's limit requests with answers. It is clearly distinguishable from the sibling account_request_limit by describing only retrieval. However, it never names that sibling to make the read-vs-request split explicit.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The mention of thresholds and approvers usefully previews what the result records contain.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description states a specific verb and resource: refund a top-up. It also specifies the core eligibility condition (paid in the last 24 hours and unused), so the agent can distinguish this from unrelated account and books tools.

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

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

It clearly states when the tool applies: a top-up paid in the last 24 hours that has not been used. It also explains the default behavior when topup_id is omitted, though it does not name a sibling alternative or explicitly describe when not to use it.

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

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

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

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

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

Front-loaded with the core action and dense with useful facts in two sentences, but it ends with a duplicated 'Free. Free.' and packs the eligibility, throttling and async-answer mechanics into one overloaded clause.

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

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

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

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

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

Schema coverage is 100%, so all four parameters are already documented, including the enum list, the 40–2000 character reason bounds and the `other` fallback. The description restates those facts ('which one (or other, saying which)', 'the number it needs', '40 to 2,000 characters') without adding format or unit guidance the schema lacks, so baseline 3 applies.

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

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

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

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

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

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

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

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

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

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

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

It is a single dense paragraph in which the most important fact (this tool creates or changes a team) appears only after a long definitional preamble, making it hard to scan. The cost is stated twice ("$0.001." and "Costs $0.001 per call; nothing if it fails."), which is wasted space in an otherwise information-dense description.

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

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

For a 13-parameter upsert with no output schema, the description covers permissions, budget enforcement, alerting, drafting/mailbox scoping, the company-wide special case, and billing behavior. The only gap is the return value, which is not critical for calling the tool correctly.

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

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

Schema coverage is 77%, so the baseline is around 3, but the description adds real meaning: budget_period is tied to monthly_budget_usd, budget hard/soft behavior is spelled out, erp_code is contextualized as a cost center for statements, and drafts_only is explained as writes waiting for a manager or owner. Some parameters (name, new_name, alert_percent range) get no narrative help beyond the schema, keeping it out of 5 territory.

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

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

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

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

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

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

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

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

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

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

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

Front-loaded with the core purpose, then matching rules, ranking, and result format in tight sentences. The long enumeration of content types is informative but stretches the first sentence; nothing else is wasted.

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

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

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

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

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

Schema description coverage is 0%, so the description must carry the load; it defines query semantics ('Every word must appear (any case)') and the purpose of areas ('Narrow it with areas'), which the enum alone would not explain. The limit parameter, including its default and 50 cap, is left entirely to the schema.

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

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

States a specific verb and resource ('One search over what this account holds') and enumerates exactly what is searched, from files to CRM records to book entries. An agent can distinguish this cross-domain search from the many single-domain siblings without opening the schema.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The tool clearly defines its comprehensive scope—branding applies to all customer emails and published web pages. It doesn't compare it to other setters, but its detailed list of effects defines its operational niche well.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

States a specific verb and resource ('Change an email's subject, headline or opening words') and bounds the scope explicitly: the underlying facts, links and buttons stay fixed. It also names the sibling read tool it depends on (account_list_email_templates), so an agent can distinguish it from listing or brand tools without opening a schema.

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

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

Gives clear operative context: variables must come from account_list_email_templates ({name}, {when}), and passing an empty string reverts to the original wording. It stops short of explicit when-not-to-use guidance (e.g. that this cannot change times, places or amounts, only the wording), so it lands at clear-context-but-no-exclusions.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description states a concrete action: sending a confirmation link to the owner's email so they can claim ownership of the account. It is clear what the call accomplishes, but it does not distinguish itself from the sibling account_owner_link, which an agent could easily confuse with this tool.

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

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

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

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

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

Adds two traits the annotations cannot express: per-call cost ($0.01, free on failure) and the cross-entity propagation rule (a deal note also surfaces on its company's and contact's timelines). Combined with annotations declaring non-readonly, non-destructive, non-idempotent, the agent has a solid behavioral picture; only a note about whether re-posting duplicates a note is missing.

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, front-loaded with the action and targets, then the propagation rule and cost. No filler, and the cost caveat is placed where an agent will read it before calling.

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 write tool with annotations already covering safety, the description supplies the non-obvious pieces (cost, timeline propagation) and identifies valid targets. It falls short only on parameter-level detail — what `body` vs `title` are for and whether target fields are mutually exclusive — which matters at 0% schema coverage.

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 across 6 params. It clarifies the target selectors (contact id or email, deal_id, company_id) but says nothing about the required `body`, the `title`, or whether multiple target ids may be supplied simultaneously — a real ambiguity given four optional target fields and additionalProperties=false.

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

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

States a specific verb+resource (add a note) and enumerates the exact record types it can attach to (contact by id or email, deal, company). That level of target specificity separates it from generic siblings like crm_timeline or hubspot_add_note without needing 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 content-level guidance ('what was said, decided or learned'), which implies the use case of logging CRM activity. However it never states when to prefer this over hubspot_add_note or when to read crm_timeline instead, and offers no exclusions or prerequisites.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description goes beyond them by stating what survives (people, deals, notes), that crm_get_company still reads the record with archived: true, and the $0.001 cost with no charge on failure. The only gap is that it doesn't say what happens if the company_id doesn't exist.

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 dense sentences, each carrying distinct information: scope of hiding, what is preserved, irreversibility and cost. Nothing is redundant and the effect 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?

A one-parameter mutation with no output schema; the description covers consequences, reversibility, read-back behavior, and billing. An agent has everything needed to decide and to call it correctly.

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

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

Schema coverage is 0%, so the single company_id parameter is undocumented in the schema. The description implies a company is identified by identity or name ('even by name') but never describes the company_id argument itself; the single-parameter baseline keeps this at 3.

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 ('Hide a company') and immediately scopes the effect to concrete surfaces: crm_find_companies, crm_search, duplicates and exports. That makes it unmistakable against siblings such as crm_restore_company and crm_save_company.

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

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

Explicitly says re-saving, even by name, will not reverse the archive, and names crm_restore_company as the tool that does. That is a direct when-to-use-this-vs-alternative routing instruction.

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 safety and repeat-call behavior are covered structurally. The description adds genuinely non-obvious context beyond that: history is retained, the change is reversible only via crm_restore_contact, and there is a $0.001 per-call cost with no charge on failure. Only minor gaps remain, such as what happens to already-archived contacts or whether the contact stays readable via crm_get_contact.

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, front-loaded with the action and effect, followed by reversibility and pricing. No filler or 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 one-parameter mutation with annotations and no output schema, the description covers the essential unknowns: visibility effect, data retention, reversibility path, and cost. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 0% and there is one parameter (contact_id) that is self-explanatory by name, so the description is not required to rescue undocumented semantics. It adds nothing about the parameter itself, which is acceptable but not additive, warranting the baseline 3.

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 (archive/hide) and resource (contact), plus the observable effect: removed from searches and lists. It also names crm_update_contact and crm_restore_contact, so an agent can distinguish this tool from its nearest siblings without opening schemas.

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

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

Explicitly routes the agent: crm_update_contact cannot un-archive, crm_restore_contact does. That is a clear when-to-use/when-not-to-use/named-alternative statement rather than implied usage.

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 important behavioral context beyond annotations: it states a per-call cost and that failed calls are free. Annotations already cover safety and idempotency, but the description could say more about side effects, permissions, or whether completion can be reversed.

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 single, efficient sentence with the operation front-loaded and the cost note immediately after. Every phrase earns its place and there is no unnecessary 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 two-parameter mutation, the description covers the core action, status options, and cost. However, with no parameter descriptions and no output schema, it should say more about task_id and the result of completing a task.

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 mentions the status values 'done' and 'cancelled', but does not explain the required task_id parameter or clarify its role in identifying the task to complete.

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: 'Mark a task done (or cancelled).' It is clearly distinguishable from CRM siblings such as crm_create_task and crm_list_tasks, which handle creation and listing rather than completion.

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 operation itself implies when to use the tool, but there is no explicit guidance on alternatives or exclusions. It does not state when to use crm_create_task or crm_list_tasks instead, nor whether this should be used only for final task closure.

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 genuinely useful context beyond the annotations: the $0.01 per-call cost and that failures are not billed. That is real behavioral information an agent can't get from readOnlyHint/destructiveHint/idempotentHint alone, though linkage requirements between email and contact_id remain undisclosed.

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

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

One short sentence with no padding, but it is a noun phrase rather than a front-loaded statement of what the call does. It is concise at the cost of being under-specified.

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 6-parameter mutation with 17% schema coverage and no output schema, the description omits how a task is attached to a record (email vs contact_id), whether title-only calls are valid, and what is returned. Only the billing and priority/due_at notes are covered.

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 17% across 6 parameters, so the description must compensate and does not. It restates due_at/priority (already in schema, including the enum) but says nothing about the crucial email vs contact_id choice or what details is for.

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 ('a follow-up on a contact') and two of its fields, so an agent can infer this creates a task, but it never states the action verb — the verb only appears in the title. It also doesn't distinguish itself from siblings like tasks_create or crm_add_note.

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

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

There is no guidance on when to use this versus tasks_create, crm_complete_task, or crm_add_note, nor any prerequisite or exclusion stated. 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?

Goes well beyond the annotations by disclosing that values in custom_fields are type-validated from then on, that types are immutable once populated, and the pricing model ($0.001 per call, free on failure). The type-immutability and cost details are things no annotation fields encode, and nothing here conflicts with idempotentHint=true or destructiveHint=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 with the action and scope, then behavior, then the type caveat, then cost. Four sentences each carry distinct information, though the type enumeration is a little dense and partly duplicates the enum.

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 schema-less-output mutation tool, the description covers validation behavior, type immutability, and billing, which are the agent-relevant unknowns. Minor gaps remain around whether the field definition is echoed back and whether label/description default to anything.

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 50% schema coverage, the description does real work: it enumerates all eight type values with the date format spelled out (YYYY-MM-DD), and mentions options, label, description, and the three target objects. Only the `key` format detail 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?

"Add a field of your own to contacts, companies or deals" names a specific verb and resource, and the second clause extends the scope to relabeling/editing existing fields. An agent can separate this from crm_delete_field and crm_list_fields 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?

The description covers the meaningful decision point explicitly: "A field that holds values keeps its type; delete it and define it again to change the type." That is real when-and-how guidance, though it never names the sibling tool (crm_delete_field) an agent would need to accomplish the type change.

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 destructiveHint annotation by disclosing the blast radius (value removed on every record), irreversibility, and a per-call cost model with a failure exemption. That cost/rollback detail is exactly the kind of context annotations cannot 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?

Three short sentences, zero filler, and the data-loss warning is placed immediately after the action statement rather than buried.

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?

Behavioral and cost context are complete, and annotations already cover the destructive profile, but both parameters remain undocumented in schema and description alike. For an irreversible deletion that gap matters more than for a read tool.

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

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

Schema description coverage is 0% and the description never mentions either parameter. For a destructive tool, an agent gets no clarification of what 'key' identifies (field key vs. id) or how it relates to the object 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?

Specific verb+resource ('Delete a custom field') with scope added: the field and its stored value on every record. That scope separates it from crm_delete_tag / crm_delete_segment / crm_delete_pipeline, though no sibling is named explicitly.

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

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

The destructive nature implies caution, but there is no explicit when-to-use guidance, no pointer to crm_list_fields or crm_define_field as the inspection/creation counterparts, and no statement about prerequisites or how to obtain a valid field key.

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

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

Annotations already flag destructiveHint=true, but the description adds real preconditions (must be empty, cannot be last) and cost semantics ($0.001 per call, nothing on failure). This is behavior beyond what the annotations 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?

Four short clauses, all earning their place, with the operation and its primary constraint front-loaded. 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 single-param destructive tool with no output schema, everything needed to call correctly is present: identifier form, preconditions, alternative path, and cost/failure behavior.

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

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

Schema coverage is 0%, so the description carries the burden, and it clarifies that the identifier may be an id or a name – meaningful meaning not present in the bare string schema. It does not restate length bounds, but that is minor for a single identifier arg.

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 ('Delete an empty pipeline') and immediately scopes it ('empty', 'by id or name'). The reader knows exactly what it does and how it differs from crm_save_pipeline or crm_move_deal.

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?

Encodes explicit when-not conditions (pipeline holding deals, last pipeline) and names the correct alternative action (crm_move_deal). It tells the agent not just when to call it but what to do when it must not be called.

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=false, so the safety bar is partly met. The description adds genuinely non-derivable behavior: the delete is non-cascading ('records stay as they are') and it carries a per-call cost that is waived on failure — exactly the kind of operational detail annotations cannot express. It stops short of stating what happens on a repeat delete or a nonexistent segment.

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 clauses, front-loaded with the action, and both the non-cascade note and the cost are stated in minimal words. Nothing is wasted and nothing essential is buried.

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 2-parameter, non-nested tool with no output schema and annotations covering the destructive profile, the description supplies the two surprises an agent needs (no cascade, failure is free). The remaining gap is identification semantics — how to obtain a valid segment name/id and the object-type requirement.

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

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

Schema coverage is only 50%: `segment` is documented as 'Name or id', but `object` (enum contact/company/deal) has no description. The description never mentions the object type or the name-vs-id resolution, so it does not compensate for the coverage gap on a tool where choosing the wrong object could target the wrong segment.

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?

Specific verb+resource ('Delete a saved segment') with an added scope clarification that the underlying records survive, which distinguishes this from record-deletion siblings. It does not explicitly differentiate from the adjacent crm_delete_tag / crm_delete_pipeline / crm_delete_field siblings, but the resource is unambiguous.

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

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

Usage is only implied: you call it to remove a saved segment while keeping the records. There is no explicit when-to-use vs. crm_list_segments / crm_save_segment, no prerequisite (e.g. does the segment need to exist, must you know its id from crm_list_segments), and no note on whether the segment can be recreated.

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, but the description goes further by disclosing scope of destruction (all contacts, companies and deals) and the cost model ($0.001 per call, free on failure). These are operational facts an agent cannot get from the structured fields.

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

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

Two short sentences, front-loaded with the action and its scope, then the pricing note. Nothing here 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?

For a single-parameter destructive mutation with full annotations and no output schema, the description covers scope, cost, and failure billing. It stops short of stating whether deletion is reversible or whether a nonexistent tag errors, which would round it out.

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 `name` parameter, so the description carries the full burden, yet it says nothing about matching rules, case sensitivity, or what happens if the tag doesn't exist. The straightforward 'delete a tag' to `name` mapping is inferable, but no additional meaning is supplied.

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 ('Delete a tag') plus the blast radius ('take it off every contact, company and deal'), which separates it from read-only siblings like crm_list_tags. It doesn't name the sibling that only untags a single record (crm_tag_records), so differentiation is implied rather than 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?

The global-removal wording implies when this tool is the right choice (removing a tag everywhere rather than on one record), but it never states exclusions or names an alternative. An agent must infer that per-record untagging lives elsewhere.

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 the description adds genuinely non-obvious behavior: archived contacts and companies are excluded, output caps at 500 rows per call, and you paginate via next_offset. It does not explain CSV header layout or how custom-field keys are rendered as columns, which keeps it below a 5.

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

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

A single dense sentence leads with the resource and format, then layers filters, exclusions, and pagination. Every clause carries information, though the run-on structure makes it slightly harder to scan than separate sentences would.

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 still tells the agent what comes back (CSV text, one row each, tags/custom fields as columns) plus row limits and continuation. The remaining unknowns, such as column ordering and sort defaults, are minor for an export 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 57%, and the description echoes tag/segment/filters and references next_offset for pagination, which the schema's limit/offset parameters leave undescribed. However, sort and limit are not touched, so it only partially compensates 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 (export) and resource (contacts, companies, or deals) and names the output format (CSV text with one row per record, tags/custom fields as columns). This clearly separates it from the crm_find_* siblings, which return records for reading rather than a CSV dump.

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 use case ("for a spreadsheet or for the owner") and ties filtering behavior to the same filters/tag/segment as the find tools. It implies rather than states the choice between exporting and using crm_find_contacts/crm_find_companies, so it stops short of an explicit when-not rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real value beyond them: the default exclusion of archived companies, the paginated return shape (page, total, next_offset), and the cost note ('Free').

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

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

Four short sentences, front-loaded with the search modes, then the archival rule, then the return shape. No filler; each sentence carries distinct operational information.

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

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

For a read-only, zero-required-parameter list tool with no output schema, the description covers the essential contract: how to search, what is excluded by default, and what comes back including pagination. It slightly under-delivers on how offset/limit relate to next_offset and on sort/lifecycle_stage semantics.

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 44%, with query, limit, offset, lifecycle_stage and include_archived undocumented in the schema. The description compensates for the two most ambiguous ones by defining query as name-or-domain matching and explaining include_archived's default, though limit, offset and lifecycle_stage remain unaddressed in both places.

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 (search/find) and resource (companies) and spells out the three search modes: name/domain, field/tag/custom-field filters, or a saved segment. An agent can distinguish it from crm_get_company or crm_save_company, but it never mentions the adjacent generic crm_search sibling, which risks confusion about which entry point to 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?

Usage is implied by enumerating the search modes and by the archived-record rule, but there is no explicit 'use this instead of X when Y' guidance against siblings such as crm_search, crm_find_duplicates, or crm_get_company. The include_archived note is the only conditional behavior stated.

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

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

Annotations already declare readOnly, idempotent and non-destructive, but the description adds output behavior the annotations cannot: a paged result with the total and next_offset, default ordering by most-recently-seen unless sort overrides, and that the call is free. It does not discuss rate limits or cost of large limits, but the pagination contract is a real addition.

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, front-loaded with the search modes, followed by return shape and then the cost caveat. Every sentence earns its place and nothing is repeated.

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 search tool with no output schema, the description covers return contents and pagination, which is the critical missing piece. It is slightly thin on the two undocumented filter-ish params (lifecycle_stage, include_archived), but overall an agent could call it correctly.

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

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

Schema coverage is only 44%, so the description must compensate. It adds meaning for query (name/email/company/phone), filters (any field, tag or custom field) and segment (saved segment), plus default sort semantics, but lifecycle_stage and include_archived go unmentioned and limit/offset are only gestured at via 'page/next_offset'.

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 (search the CRM for contacts) and enumerates the lookup modes: name/email/company/phone, field/tag/custom-field filters, or a saved segment. It does not distinguish itself from the generic crm_search or route to/away from crm_find_companies and crm_find_deals, which are the closest siblings.

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

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

Use is implied through the enumeration of input modes (free-text query, filters, segment), but there is no explicit when-to-use or when-not guidance. It never says how it differs from crm_search, or that crm_find_companies/crm_find_deals should be used for other record types.

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 non-destructive, so safety is covered. The description adds real behavioral context beyond them: the default ordering ("most recently changed first unless `sort` says otherwise") and the cost signal ("Free."). It stops short of mentioning pagination behavior or result shape.

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

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

Three sentences, front-loaded with the primary filter axes, then a default-ordering clause, then a copy-pasteable example. Dense but every clause earns its place; the trailing "Free." is terse and useful.

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, sargable query tool with no output schema, the description covers the filter surface and default sort and gives a realistic example. Gaps remain around pagination (limit caps at 100, offset semantics) and how to retrieve a single deal, but the core calling information 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 low (33%), but the description compensates well by naming nearly every filter input — pipeline, stage, status, company/contact, tag, segment, sort, and arbitrary field/custom-field filters. It also conveys the date arithmetic convention ("today-14") via a worked example. Only query, limit and offset go unaddressed.

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

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

The description states the resource (deals) and enumerates the retrieval axes — pipeline, stage, status, company/contact, filters, tag, custom field, saved segment — so an agent can tell it is a filtered deal lookup. It does not, however, distinguish itself from overlapping siblings such as crm_search or crm_get_deal, leaving the boundary 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?

Usage is implied through the enumeration of filter axes and one concrete worked example ("deals not moved in 14 days"), which shows how to compose a query. There is no explicit statement of when to prefer this over crm_search, or when a saved segment beats raw filters.

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, so safety is covered; the description adds genuinely new behavior: the exact matching heuristics, the archived-record exclusion, that results come back as groups, and 'Free' (no credit cost) — a non-obvious operational fact. It doesn't mention ordering, pagination beyond the limit param, or how large a group can get, keeping it from a 5.

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

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

Front-loaded with the core definition, then the matching rules, then the excluded case, then the recommended follow-up action — a logical order. It is dense and slightly run-on in the rule enumeration, but every clause conveys distinct matching logic that the agent would otherwise have to guess.

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

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

With no output schema, the description does signal the return shape ('each group'), which is the key missing piece an agent needs. Combined with the readOnly annotations and the merge hand-off, an agent can call this correctly. The unaddressed limit semantics and absence of any note on group ordering/cost of large scans are the only remaining gaps.

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

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

Schema description coverage is 0%, so the description carries the burden. It effectively explains the 'object' parameter by giving separate matching rules for contacts and companies, but the 'limit' parameter (default 20, max 100) is never mentioned, nor is what a result 'group' contains. Partial compensation earns a baseline 3.

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

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

States a specific verb+resource ('Contacts or companies that are probably the same') and then defines exactly what counts as a duplicate for each object type, including the normalization rules (case-insensitive email, any phone format, suffix-stripped company names). This is clearly distinguishable from crm_find_contacts, crm_search, and crm_find_companies, which are lookup tools rather than dedupe detectors.

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

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

Explicitly routes the agent to the follow-up action: 'Merge each group with crm_merge_contacts or crm_merge_companies,' which is the correct next step and names the sibling tools. It also notes archived records are excluded, which prevents wasted calls. It stops short of stating when NOT to use this (e.g., when looking up a specific known contact, use crm_find_contacts), so it falls just 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?

Beyond the readOnlyHint/idempotent annotations, the description discloses the payload shape (people, deals with open ones ordered first, notes with by/via author attribution matching crm_timeline) and that archived companies are still returned. It also notes the call is 'Free', a cost signal absent from annotations. The gap is what happens when neither identifier is supplied, which matters since both parameters are optional.

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 the resource and lookup keys front-loaded, followed by the returned contents in decreasing relevance. No filler and nothing repeated from annotations.

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

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

With no output schema, the description usefully sketches what comes back and how notes/deals are ordered, and annotations already cover the safety profile. The remaining gap is the zero-required-parameter ambiguity: an agent cannot tell from the description what the tool does if both name and company_id are omitted.

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 meaning of both parameters, and 'by id or name' does establish that the two are alternative lookup keys rather than joint requirements. However it gives no format, matching, or precedence guidance (e.g. which wins if both are passed, whether name must be exact), and the '(archived: true)' parenthetical is ambiguous since no such parameter 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 opens with a concrete verb and resource ('One company, by id or name') and then enumerates the related data returned (tags, custom fields, people, deals, notes). It clearly signals a single-record fetch as opposed to a search, though it never names a sibling like crm_find_companies to sharpen the distinction.

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

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

Usage is only implied — 'One company, by id or name' suggests a direct lookup once an identifier is known, and the note about archived companies hints at a visibility case. There is no explicit statement of when to prefer this over crm_find_companies or crm_search, nor any prerequisite for obtaining the id/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 establish read-only, idempotent, non-destructive, closed-world behavior, so the description does not need to repeat safety traits. It adds useful behavioral context by listing exactly what contact data is returned and explaining came_from attribution, though it omits any permission or error behavior notes.

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 avoids redundant sentences, covering return contents, lookup method, attribution, and an alternative tool efficiently. However, the long run-on sentence and the vague 'when the site is counted' / 'Free' phrases reduce clarity slightly.

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-output-schema retrieval tool, the description does a reasonable job describing returned fields and the crm_timeline alternative. The main completeness gap is parameter behavior: with no required parameters and no schema descriptions, the agent still lacks clear guidance on identifier requirements or conflict handling.

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 two undocumented parameters. It says lookup is 'by id or email', which helps, but it does not state that at least one identifier is required, whether both may be supplied, which takes precedence, or the expected email format.

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

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

States a specific verb and resource ('Get' / 'One contact') and enumerates the returned data: tags, custom fields, activity, tasks, deals, and came_from attribution. It also distinguishes the tool from crm_timeline, which is described as the place for full history.

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 makes the usage context clear: retrieve a single contact by id or email. It explicitly points to crm_timeline for everything that happened with the contact, but does not distinguish from other retrieval/search siblings such as crm_find_contacts or crm_get_customer.

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, closed-world, non-destructive behavior, so the description's job is to add detail. It does: all lists cap at 5 with the per-area tools holding the remainder, lookup can fan out to a company's contacts' records, and it is explicitly "Free." Only the exact response shape/pagination beyond the cap is unaddressed, and no output schema exists, so a 4.

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

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

Purpose and lookup modes are front-loaded ahead of the long enumeration of returned sections, so the agent gets the essentials first. The manifest of data areas is long but each item earns its place by revealing what comes back; only the volume makes it denser than ideal.

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

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

For a multi-domain aggregate tool with no output schema, the description enumerates the returned sections and the 5-per-list cap well enough that an agent knows what to expect. The gap is the lack of clarity on how the three optional lookup keys interact and which one takes effect, minor against the otherwise rich disclosure.

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 parameter load, and it names all three selectors: contact_id, email, and company_id, noting company_id also pulls its contacts' records. It does not state precedence or mutual exclusivity when multiple keys are supplied, nor that all are optional, so it is strong but not complete.

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 verb (read) and a composite resource (the contact/company plus everything open with them: deals, tickets, invoices, quotes, e-sign docs, meetings, last interactions, newsletters, attribution). An agent can distinguish this aggregate view from the per-record siblings like crm_get_contact, crm_get_company, and crm_get_deal 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?

"One read before you answer someone" positions this as the first call for a customer question, and "each area's own tools have the rest" points the agent to the per-domain siblings for more than the 5-item cap. It stops short of stating explicit when-not conditions or naming the exact alternative tools, so it is clear context without full 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?

Annotations already carry the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real value: it discloses the shape of the payload (stage history with days per stage, note authorship) and the 'Free' note, which presumably signals no credit/quota consumption. It does not say what happens when the deal is missing or inaccessible.

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 sentence, front-loaded with the primary resource and then the returned facets. The parentheticals earn their place by clarifying exactly what the stage history and note attribution contain.

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 well by enumerating the returned entities, which is what an agent needs to decide whether this call suffices. It stops short of error/empty-result behavior and of clarifying the unusual 'Free' qualifier.

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 should carry meaning for deal_id, but it never mentions it. The single required integer id is self-evident from the tool name, which keeps this from being a real gap, but there is no added semantics (format, source of the id, lookup of archived deals).

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?

It states a specific resource and enumerates its scope precisely: a single deal plus pipeline/stage, stage history with dwell days, notes with by/via attribution, and linked contact/company. 'One deal' cleanly separates it from the plural search tool crm_find_deals and from mutators like crm_save_deal/crm_move_deal.

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: 'One deal' suggests lookup-by-id versus search, and the crm_timeline reference hints at a relationship with that tool. There is no explicit statement of when to use this instead of crm_find_deals or crm_timeline, and no mention of preconditions such as a valid deal_id.

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, so the safety bar is covered. The description adds information annotations do not carry: the response contents (type, options, description, and how many records hold a value) and a cost signal ('Free'), which is genuinely useful for planning.

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 front-loaded sentence with no filler, and the parenthetical efficiently delivers both return-shape and provenance information. It is dense to the point of being slightly clipped, but nothing 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 small, read-only discovery tool with no output schema, the description adequately covers what the tool returns and what the custom-field concept means. The only material omission is the behavior when the optional 'object' filter is not supplied.

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%, but the single parameter is an enum that self-documents its three legal values, and the description echoes them as contact/company/deal. The real gap is the optional parameter's default: the description never says what is returned when 'object' is omitted (presumably all three 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?

The description names the resource precisely ('the fields you can read, filter and sort on') and enumerates the three object scopes, so its function is unmistakable. It also distinguishes the standard set from custom fields defined via the sibling crm_define_field, though it does not explicitly contrast itself with other crm_list_* 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?

The framing 'fields you can read, filter and sort on' makes the use case clear: schema discovery before filtering/sorting or before writing custom-field values. It names crm_define_field as the creation counterpart, but gives no explicit 'do not use this to create fields' exclusion or a stated precondition like 'call before crm_find_contacts with custom filters'.

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 non-destructive, so the safety profile is covered. The description adds useful context those annotations cannot: results are ordered, every account is pre-seeded with a 'Sales' pipeline containing a fixed stage sequence, and the call is free. It stops short of saying anything about size limits or whether aggregate counts are live.

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 returned structure and its ordering, which is the most decision-relevant fact. Every clause carries information (field meanings, default stages, no cost), though the

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 carries the burden of describing the return value, and it does so field by field including probability range and outcome enum. It leaves ambiguity about whether deal counts/value are per stage or per pipeline, and says nothing about pagination or size limits for large accounts.

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 zero input parameters there is nothing for the schema to document, so the baseline of 4 applies. The description productively uses the space to describe output fields instead of 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 names the specific resource (deal pipelines) and enumerates exactly what comes back: stages in order with id, name, probability, outcome, deal counts and value by currency. It is not a tautology and is distinguishable from crm_save_pipeline / crm_pipeline_report by name, but it never states the listing action or contrasts with those siblings explicitly.

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

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

There is no statement of when to call this versus crm_pipeline_report, crm_list_segments, or the pipeline mutation tools. The only inferable guidance is that it is a read operation, and nothing tells the agent it should call this before crm_move_deal or crm_save_deal to discover valid stage ids.

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 two genuinely new facts: that match counts are computed live ('right now', implying cost/freshness behavior) and that the call is 'Free' (no credit charge) – useful context that structured fields don't 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?

Two short sentences, front-loaded with the payload description, so nothing is padded. However, 'Free' is dropped in without explanation and the extreme brevity leaves the one parameter and the return ordering unaddressed – under-specification rather than true conciseness.

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 partially describe the return shape (segments, their filters, match counts). It stops short of covering the object filter semantics, whether counts are expensive to compute, or ordering – gaps an agent would notice on first call.

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

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

There is one parameter, 'object', with an enum of contact/company/deal and 0% schema description coverage, yet the description never mentions it. The agent cannot tell whether omitting it returns all segments or errors, nor that it filters segments to a single record type.

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 (saved segments) and states the payload: each segment's filters plus a live match count. But it never states the verb explicitly ('lists') and gives no hint that the result set can be scoped by object type, which is the tool's only degree of freedom.

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 alternatives such as crm_save_segment (create/update a segment) or crm_search / crm_find_contacts (query records directly). An agent must infer from the name alone that this is the read path for saved segments.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered elsewhere. The description adds real value by stating that results are aggregated counts per entity type (contacts, companies, deals), which the annotations cannot convey. It says nothing about ordering, result size, or whether archived records are counted.

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 front-loaded sentence that states the resource and the payload shape with no filler. The dangling 'Free.' is cryptic — it is unclear whether it means no-cost, unfiltered, or unlimited — so it fails to earn its place.

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

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

For a no-parameter, no-output-schema read tool, the description is sufficient: an agent knows it returns tags plus per-entity usage counts. Missing only secondary details such as ordering or whether the list is 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 schema imposes no semantic burden; baseline 4 applies. The description spends its words on return content instead, which is the right allocation.

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

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

States a specific resource (every tag) and what the payload contains (counts of contacts, companies and deals per tag), so the agent knows it is an enumerate-all-with-usage-stats tool rather than a lookup. It is distinguishable from crm_list_segments and crm_list_fields, though it doesn't explicitly name those siblings. The trailing 'Free.' is opaque and adds no clarity.

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 mention of prerequisites, and no routing to alternatives such as querying tags per record type or listing segments. For a zero-param list tool the name implies the intent, but the description itself provides no 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those annotations: default status is open, results are ordered soonest first, each task includes its associated contact (id, name, email), and the call is free.

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 single dense sentence that front-loads the resource and filters, and every clause except possibly "Free" carries useful information. It is appropriately sized, though the fragment style and unexplained "Free" leave a little ambiguity.

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 list tool with no output schema, the description usefully explains ordering and the embedded contact fields, and annotations cover the safety profile. However, with 0% schema description coverage, it should also document the limit/pagination behavior and the due_before format to be fully complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It mentions status (default open), contact_id, and due_before, but it completely omits the limit parameter, does not enumerate the status values, and gives no format for due_before. It therefore 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 states the resource (tasks), primary filter (status, default open), optional filters (contact or due before a time), ordering (soonest first), and included contact fields. It clearly distinguishes this from mutation siblings like crm_create_task and crm_complete_task, though it does not explicitly differentiate from generic tasks_list or hr_tasks.

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 useful implied usage: default open status, optional contact filter, optional due-before filter. However, it does not explicitly say when to use this tool instead of tasks_list, hr_tasks, or other task-listing siblings, and it does not mention 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?

Goes well beyond the annotations: it discloses what is destroyed ('The merged companies are deleted'), how field conflicts resolve (kept company wins), that empty fields are backfilled and tags/custom fields combined, that people, deals and notes are re-parented, and the $0.01 cost with a no-charge-on-failure policy. This is exactly the context the destructiveHint/idempotentHint annotations cannot 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?

Three tight sentences: the action and scope first, then the merge semantics, then the destructive and cost consequences. No filler or repetition.

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

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

For a two-parameter destructive mutation with no output schema, the definition covers consequences, conflict rules and billing. The only gap is what is returned (e.g. the surviving company record/id), which an agent may need to chain a follow-up call.

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 carries the burden. It does clarify the roles of the two parameters ('the one you keep' vs 'the others') and the conflict-resolution direction, which is more than the bare names, but it never mentions the 1-10 range on merge_ids or the integer ID format.

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

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

States a specific verb and resource (merge companies) plus the target outcome ('into the one you keep'), which is distinguishable from the sibling crm_merge_contacts and from crm_archive_company. An agent can tell what this does without opening the schema.

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

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

The phrase 'Merge duplicate companies' implies the deduplication use case, but it never says when to choose this over alternatives or what precedes it (e.g. crm_find_duplicates to identify candidates, or crm_archive_company as a non-destructive alternative). Usage is implied rather than stated.

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 flag destructiveHint=true, but the description goes well beyond them: it explains field-filling precedence, tag/custom-field combination with the kept contact winning conflicts, migration of notes/tasks/emails/chats/calls/tickets/deals, archiving of merged records, preservation of email lookups, and the $0.01-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?

Four tight sentences, front-loaded with the core action and outcome before the field/record details and cost. Every clause carries actionable information with 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 two-parameter mutation with no output schema, the description covers side effects, data precedence, and billing adequately. Minor gaps remain: no guidance on identifying duplicates first, the 10-record cap, or edge cases like overlapping keep/merge ids.

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%, yet the description only implicitly maps 'the one you keep' to keep_id and 'the others' to merge_ids, without naming them. It adds useful semantics (merged records are archived, max of 10 not mentioned) but does not fully compensate for the undocumented 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?

States a specific verb ('merge') and resource ('duplicate contacts') plus the outcome ('into the one you keep'), which cleanly separates it from crm_merge_companies and the save/update contact tools. 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?

Usage is implied by the name and by 'duplicate contacts', but the description never states when to call this versus crm_find_duplicates (to locate candidates) or crm_archive_contact (to discard a record without merging). No prerequisites or exclusion conditions are given.

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 annotations: closing/reopening effects, history tracking via crm_get_deal, per-call cost, and that failed calls are free. These are meaningful operational details not present in the annotations or schema.

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

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

Front-loads the core action and follows with the most important side effects and cost. Four sentences, no filler, and each sentence adds useful 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?

Covers the operation, side effects, history behavior, and cost well enough for a mutation tool with no output schema. It does not describe the move tool's own return value, but most agent-critical 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 carry parameter meaning. It clarifies stage can be by name or id, pipeline selects another pipeline, and lost_reason is required when losing a deal, though it does not explain every parameter constraint.

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 the specific action (move a deal) and resource (deal) plus the target (stage, optionally another pipeline). It is clearly distinct from siblings like crm_save_deal and crm_get_deal.

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 key usage semantics: moving to a won/lost stage closes the deal, requires lost_reason when lost, and moving to an open stage reopens it. It does not explicitly name alternative tools or when not to use this one, 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?

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description still adds real value by disclosing defaults (this month, today), stating values are reported per currency without conversion, and implying a single aggregated response rather than a paginated record 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?

The core framing 'How a pipeline is doing' is front-loaded and every clause maps to a report section, so little is wasted. It is a long run-on sentence with a stray trailing 'Free.', which slightly hurts scanability but not comprehension.

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 results, and enumerating the report sections effectively does that. What remains unsaid is the shape of the returned data (grouping keys, currency field placement) for a tool with four optional parameters and no return contract.

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 75%; the one undocumented parameter (stale_days) is the one the description explains, defining it as 'open deals that have not moved for stale_days'. since/until/pipeline are covered by the schema, so the description adds meaning only where the schema is silent, which is the right allocation.

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 exact report and enumerates its sections: open deals by stage with weighted value, won/lost in a period with win rate, forecast by expected close month, and stale-deal counts. No sibling CRM tool produces this aggregate view (crm_find_deals/crm_get_deal return records, not analytics), so an agent can distinguish it immediately.

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 when it wants pipeline analytics rather than raw deals. There is no explicit statement about when to prefer this over crm_find_deals or crm_search, and no prerequisites or exclusions are given.

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 non-read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new operational facts not in structured fields: a cost of $0.001 per call and no charge on failure, plus the downstream surfaces affected by a restore. It omits permission/auth requirements and what the response contains.

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

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

Two short sentences, zero filler, with the effect of the operation front-loaded before the pricing note. Every clause carries information an agent would not otherwise have.

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 state-change tool with rich annotations and no output schema, most of what an agent needs is present. However, the description does not say how to identify or obtain the company_id, nor whether restoring is safe to retry across a shared ID, leaving a real gap given the zero-coverage schema.

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% and the single parameter company_id is never mentioned in the description — no guidance on whether it is the archived company's ID or where to obtain it (crm_find_companies / crm_get_company). With only one obvious identifier parameter the gap is mild rather than fatal, so a middling score.

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 (restore) and resource (an archived company) and even enumerates the concrete effects of restoration: lists, searches, duplicates and exports. An agent can distinguish it from crm_archive_company (inverse) and crm_restore_contact (different resource) 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 condition for use is explicit — the company must be archived — which gives clear context. It does not name alternatives or exclusions (e.g. what to do if the company is not archived, or whether merging is preferable to restoring a duplicate), so it stops short of the top band.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context the annotations lack: a per-call cost of $0.001 and the failure-pricing rule ('nothing if it fails'), which is exactly the kind of billing behavior an agent cannot infer from structured fields.

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

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

Two short sentences with zero filler; the core action is front-loaded and the cost caveat follows. Every clause earns its place.

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

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

For a single-parameter, no-output-schema mutation, the description covers the action and the billing consequence. It omits edge behavior (error when the contact is not archived, whether related records/logs resurface), which would complete the picture but is not essential to 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?

There is one parameter and schema description coverage is 0%, so the description carries the burden but says nothing about contact_id. The parameter name is self-explanatory (positive integer id), so the practical gap is small, but no format, source, or lookup guidance is offered.

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 ('Bring an archived contact back'), which is precisely the inverse of the sibling crm_archive_contact and distinct from crm_restore_company. An agent can select it without opening the schema.

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

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

The phrase 'archived contact' implies the precondition that the record must already be archived, but the description never states when to use this versus crm_update_contact or crm_save_contact, nor what happens if the contact is not archived. Usage is implied rather than spelled out.

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 the key operational traits: per-record independent success/failure, that the reply enumerates outcomes, that matching is by name (consistent with idempotentHint=true), and the exact billing model ($0.01 per saved record, nothing if none found). It does not say what the failure reasons look like or whether partial retries are safe, which keeps it off 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.