Groundbase

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety and repeatability are covered structurally. The description adds the result ordering ('newest first') and the composite nature of the feed, but says nothing about pagination behavior, result size caps, latency, or what happens when multiple scope filters are combined.

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 with zero redundancy: the first front-loads what the feed contains and its ordering, the second supplies the scoping constraint. Nothing is repeated from the title or 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?

For a five-parameter read-only list tool with no output schema, the description covers content, ordering, and scoping well enough to call it correctly. The remaining gap is paging guidance (only hinted at inside the schema's limit/offset descriptions) and explicit sibling routing, which would matter given the many per-type list tools nearby.

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

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

Schema coverage is only 40%: dealId, companyId, and contactId have no schema descriptions at all, and the description is what supplies their meaning as scoping filters for exactly one of those entities. The limit and offset parameters are already documented in the schema, so no credit is needed there, but the description carries the undocumented three.

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 (activity feed) with the enumeration of item types (texts, calls, emails, notes, deal stage changes, task completions) and sort order (newest first), which makes it clearly an aggregated cross-type feed rather than a single-type list. It does not explicitly name the sibling per-type lists (calls_list, notes_list, sms_list, tasks_list) it competes with, so differentiation is inferable rather than spelled out.

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 clause 'Optionally scoped to one contact, company or deal' implies a usage pattern (narrow the feed by entity), but there is no explicit statement of when to choose this over a per-type list like calls_list or notes_list. An agent must infer the choice from the word 'activity' alone.

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 non-read-only behavior; the description adds useful behavior beyond them by noting partial-update semantics and a confirmation step before delete. It does not discuss permissions, permanence, or response behavior, so not a 5.

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

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

Three tight sentences, front-loaded with the resource and parent scope, then actions and important operational notes. No redundant restatement 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 12-parameter CRUD tool with rich schema and destructive annotations, the description covers the key invocation context: parent entity, actions, partial updates, delete confirmation, and avoiding redundant list calls. It could be slightly more complete about return behavior or required identifiers, but no output schema exists to carry that.

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 high (92%), so the schema carries most parameter detail. The description still adds meaning by indicating the parent entity is a contact or company via contactId/companyId and by explaining that update omits unchanged fields.

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 (postal addresses on a contact or company) and enumerates the four operations. It is clear enough to distinguish from generic contact/company management, but it does not explicitly name sibling tools or contrast itself with 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?

It supplies concrete usage rules: update leaves omitted fields unchanged, delete requires confirmation, and a contact/company fetched by id already includes addresses, which discourages redundant list calls. It stops short of naming alternative tools or fully spelling out when to choose this over contacts_manage/companies_manage.

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 profile is partly carried structurally. The description adds the useful constraint that save creates only on exactly one of contact/company and that id drives edit vs. delete, but it says nothing about irreversibility of delete, side effects on related invoices, or permission requirements.

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?

Very compact and front-loaded: a one-clause resource definition followed by a per-action breakdown. The telegraphic style ('list (or contactId / companyId for one)') is terse to the point of being clipped, which slightly hurts readability but wastes no 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 destructive, 11-parameter, no-output-schema management tool, the description is only minimally sufficient. It covers action semantics and a few fields, but an agent still lacks guidance on destructive delete consequences and on most of the optional payload fields.

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 55%, and the description only names four of the eleven fields (currency, terms, billing email, tax id) at a high level. Undocumented-or-thinly-documented fields such as notes, taxExempt, and billingAddress receive no clarification in the description, so it neither compensates for the coverage gap nor adds much beyond the schema.

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

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

The description names the resource ('billing details on a contact or company') and enumerates the three operations (list, save, delete) with the fields involved (currency, terms, billing email, tax id). It is clear what the tool does, though it never differentiates itself from nearby siblings like invoice_settings or invoices_manage.

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

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

It gives per-action selection guidance: list (optionally scoped by contactId/companyId for a single profile), save (create on exactly one of contact/company, or edit by id), delete. That resolves the main ambiguity for an action-enum tool, though there are no explicit exclusions or pointers to sibling 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 already declare readOnlyHint, idempotentHint, non-destructive and non-openWorld, so safety behavior is covered. The description adds that a single-call fetch includes recording details and that listings surface transcripts, which is useful content context, but says nothing about ordering, pagination beyond the schema's limit hint, or volume characteristics.

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

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

A single tight sentence with the list mode front-loaded and the alternate mode after it. No filler, nothing repeated from the schema.

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

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

For a read-only list tool with full annotation coverage and no output schema, the description covers both modes and the notable returned content. The one meaningful omission is the `contactId` filter, which an agent would have to infer from the bare parameter name.

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% and the schema already documents `id`, `limit`, and `voicemailOnly`; the description reinforces `id` and voicemail transcript retrieval but adds no syntax or format detail. Critically, `contactId` is undocumented in both schema and description, leaving a real 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?

Names a specific verb and resource ("List call history") and enumerates the fields it returns (direction, duration, voicemail transcripts), plus the dual mode of fetching a single call by id. It is clearly distinguishable from most siblings by resource, though it does not explicitly contrast with adjacent list tools like voicemail_drops_list or activity_list.

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

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

The two modes are stated (list vs. fetch one by `id`), which implies when each applies, but there is no explicit guidance on when to prefer this over sibling listing tools, no prerequisites, and no statement of what happens with no arguments.

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 this as a safe, read-only, idempotent, non-destructive operation. The description adds useful behavioral context by listing the aggregate metrics returned and explaining the alternate per-recipient mode, though it does not mention auth requirements, rate limits, or pagination behavior.

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

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

Two sentences, front-loaded with the primary purpose and followed by the key mode switch. Every sentence earns its place with no redundant or vague language.

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 analytics tool with no output schema, the description sufficiently lists the returned metrics and explains the per-recipient mode. Minor gaps remain, such as not explicitly describing the `id` parameter or the `limit` behavior, but the core information needed to call the tool correctly 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 coverage is 75%, so most parameters are documented in the schema. The description adds meaning beyond the schema by clarifying that `recipients: true` changes the result shape to per-recipient rows and that `status` filters only in that mode, which the individual schema descriptions do not make explicit.

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 that this tool returns analytics for a single campaign and enumerates the metrics (sent, delivered, opens, clicks, bounces, etc.). It does not explicitly name or distinguish itself from the sibling `campaigns_manage` tool, but the read-only analytics scope is evident from the wording and 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?

The description explains a key mode switch: setting `recipients: true` returns per-recipient rows instead of aggregate stats. However, it provides no explicit guidance on when to use this tool versus alternatives like `campaigns_manage`, nor any exclusions or prerequisites.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false. The description adds material context beyond that: send_now/schedule/resume message real people and require confirmation, create is draft-only, and content is refused until the footer has a business name/address with no placeholders.

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?

Given 15 actions and 20 parameters, the description is compact and front-loads the resource and action list. It is dense but every clause carries action or safety information; 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 complex, 20-param, nested mega-tool with no output schema, the description covers all actions and critical behavioral warnings. The detailed input schema handles most parameter meaning, though delete semantics and return values are not described.

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% and the schema itself is richly documented, including nested content, steps, audience_filter, and sending_window. The description adds a few action-specific hints (kind=newsletter, template_id) but does not serve as primary parameter documentation.

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 ('Email/SMS campaigns and newsletters') and enumerates all 15 actions, giving an agent a precise picture of scope. It never names the sibling campaigns_analytics or templates_manage, so sibling differentiation is only implicit through the action list.

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

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

Action-level guidance is present: 'list (kind=newsletter for newsletters)', 'create (draft; template_id starts a newsletter...)', and a confirmation warning for send_now/schedule/resume. It does not explicitly say when to use this tool versus campaigns_analytics or templates_manage, but the context for each action 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, so the safety profile is covered. The description adds valuable behavioral detail beyond that: the id-mode returns the company 'in full' including employees, deals, addresses, and custom fields, which tells the agent what data volume/composition to expect.

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 with zero waste, front-loading the primary search use case and then the id variant. Every clause carries information.

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

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

No output schema exists, and the description compensates by describing what a full fetch contains. Pagination defaults and the exact shape of the list response are left to the schema, which is acceptable, but a note on partial vs. full fields for list mode 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 coverage is 80%, so the baseline is 3; however the description adds meaning beyond the schema's terse 'Returns that one company' by enumerating the nested data included in id-mode fetches. The `search` and `deleted` params are left to the schema, which is fine at this coverage level.

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 (search companies) and explicitly describes the two modes: filtered listing vs. single-company fetch by id. It doesn't mention the companies_manage sibling for write operations, so differentiation is left to the naming convention 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?

Clearly says to pass `id` for a full single record and mentions the `deleted` path for restore scenarios, giving concrete usage contexts. It stops short of naming alternatives such as companies_manage for mutations, so no explicit when-not guidance exists.

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 annotation hints, the description reveals that deletes are soft, that update is partial rather than replacement, and that restore consumes a deletedAt/ids from the list tool. These are meaningful behavioral details an agent needs before invoking a destructiveHint=true tool, and they do not contradict 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?

The description is short and front-loaded, with the action list immediately following the purpose and each action carrying only its critical constraint. There is 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 12-parameter mutation tool with no output schema, the description plus rich schema descriptions and annotations cover the essential action semantics well. It could say more about response behavior or permissions, but the core invocation requirements are present.

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

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

Schema coverage is high at 83%, and the schema already maps each parameter to actions, so a baseline of 3 is appropriate. The description adds semantic value by clarifying create-specific requirements, partial-update semantics, and the source of restore 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 names the resource and enumerates the four actions (create, update, delete, restore), so the operation is unambiguous. It distinguishes itself from the read-only sibling only in the restore sentence, referencing companies_list, so sibling differentiation is partial rather than fully 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?

It gives per-action conditions: create requires name, update leaves omitted fields unchanged, delete is soft and should be confirmed first, and restore uses deleted ids from companies_list. This is strong action-level guidance, though it does not broadly direct agents to companies_list for lookup before update or delete.

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 annotations already declare read-only, idempotent, non-destructive behavior, so the description only needs to add nuance. It usefully explains that `id` returns full details including tags, addresses, custom fields, and recent activity, and that `deleted`/`duplicates` serve restore/merge workflows.

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

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

The description is extremely compact and front-loaded, covering the main search/filter use, the single-contact mode, and the two special result modes in one dense but readable passage. There is no filler.

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

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

For an 11-parameter, read-only listing tool with no output schema, the description covers the important modes and clarifies what `id` returns. It omits pagination defaults and return shape details, but those are largely handled by the schema and 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 91%, so the schema already documents most parameters. The description adds meaning beyond the schema by grouping the filter dimensions and clarifying that `id` returns an enriched contact view and that `deleted` and `duplicates` change the result mode.

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 clear verb and resource: search/filter contacts, with special modes for a single `id`, `deleted`, and `duplicates`. It does not explicitly name or contrast with the sibling `contacts_manage`, but the listing/read scope is clear from the wording.

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 concrete usage conditions: use `id` for one full contact, `deleted` to restore, and `duplicates` to merge. It does not explicitly state when not to use this tool or name an alternative sibling, but the mode guidance is strong.

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 non-idempotency; the description adds real value beyond that by disclosing that delete is a soft delete, that merge folds duplicates in and then deletes the merged ids, and that both require confirmation. That is exactly the behavior context an agent needs before mutating data.

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-loaded with the overall purpose, then action-by-action clauses. No filler; every clause carries a rule or constraint.

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 17-parameter, nested-object dispatcher with no output schema, the description covers the action model and the highest-risk semantics (delete/merge confirmation, soft delete, restore source). It's close to complete; only a note on return format or per-action failure behavior 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 94%, so the schema already documents nearly every parameter. The description mostly restates schema facts (firstName required for create, tags by name, keepId/mergeIds roles, set fields) rather than adding syntax or edge-case meaning, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Change contacts') and then concretely delineates each of the six actions. It references the sibling contacts_list contextually ('ids from contacts_list deleted'), but never draws a clean line between managing versus listing — a small gap against 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?

Gives actionable conditions per action: confirm before delete, confirm before merge, restore using ids from contacts_list deleted. It tells the agent how to pick an action but doesn't state any when-not to use, or route to siblings like contacts_list/tags_manage.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: it names the exact fields each entry contains and warns that "unknown tags render empty," flagging a silent-failure mode an agent would otherwise miss.

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 with zero filler. The core listing behavior is front-loaded, and the secondary mergeTags mode is clearly signposted by name so an agent can branch immediately.

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, zero-required, read-only list tool with full schema coverage and no output schema, the description supplies everything needed: what each entry looks like, what the alternate mode returns, and the fallback behavior for unmatched tags.

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 goes further on mergeTags by explaining what merge tags are, giving concrete syntax examples ({{first_name}}, {{cf.<key>}}) and describing the consequence of an unknown tag. entityType is left to the schema's "Omit for all," which is adequate.

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

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

Opens with a specific verb+resource ("List custom field definitions") and enumerates the returned fields (field_key, name, type, options, entity_type), which is more than the title restates. It does not explicitly contrast with the sibling custom_fields_manage, but the read-only "list" framing makes the split reasonably inferable.

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: it describes the two output modes (definitions vs. merge tags) and when mergeTags applies ("usable in texts, emails and workflows"), but there is no explicit statement of when to choose this tool over custom_fields_manage or any other list tool. The agent must infer the read-only listing role.

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 readOnlyHint=false, but the description adds the crucial detail that deleting a field also destroys its stored values, plus an explicit confirmation instruction. The {{cf.<key>}} template syntax on create is genuinely non-obvious context. It stops short of covering permissions or idempotency of set_value, so not 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 with parentheticals per action — no filler, and the entity scope is front-loaded. It is compact enough that the parenthetical caveats are the only slight readability cost.

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

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

For a 10-parameter mutation tool with no output schema, the description covers the destructive path and the create template semantics, while required-parameter mapping per action is fully handled by the schema. It does not describe what set_value returns or whether updates to type affect existing values, which would be the remaining gap.

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

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

Schema coverage is 60%; the schema itself labels id, name, fieldKey, options, entityType and position as to which actions need them. The description adds meaning only for fieldKey (becomes {{cf.<key>}}) and value (one record's value). Parameters like type, entityId and value have no description text in either place, so it adds marginal value over 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?

Names the resource (custom fields on contacts, companies, deals) and enumerates the four operations (create, update, delete, set_value), which cleanly separates it from the sibling read tool custom_fields_list. The lead is a noun phrase rather than a verb, so it is slightly less crisp than an ideal verb+resource statement, but the action list removes ambiguity.

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

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

Gives per-action guidance: delete says 'confirm first', create explains the field_key placeholder, and set_value is scoped to 'one record's value'. It never states the inverse (use custom_fields_list to read fields), but the action enumeration makes the split with the list sibling inferable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine value not present in structured fields by disclosing the computed payload (counts, deal totals, message counts, 30-day series) for a tool with no output schema. It omits account scoping and whether the 30-day window is configurable or relative to now.

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 'KPI summary' label so the agent sees the tool's nature immediately. The telegraphic, comma-spliced style and the unspecified '30-day series' cost a point but nothing is padded.

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

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

For a one-parameter, read-only tool with rich annotations and no output schema, the description does the main remaining job: telling the agent what numbers come back. Gaps are minor but real—what the 30-day series measures, and whether results are scoped to the whole account or a workspace/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 description coverage is 100%, so the single `pipeline` parameter is already documented as 'Per-stage open deals instead.'. The description adds only a mild clarification that per-stage results include both count and value. That is a small increment over the schema, consistent with the baseline 3 for full schema coverage.

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 KPI dashboard summary) and enumerates the exact metrics returned: contact count, open/won deals with totals, messages sent/received, and a 30-day series. That is specific enough to separate it from the *_list siblings, which return records rather than aggregates. It stops short of explicitly contrasting itself with a sibling such as deals_list.

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

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

There is no statement of when to call this versus the many list tools (contacts_list, deals_list, sms_list) that could supply the same underlying data in raw form. The only conditional guidance is the 'pipeline: true' note, which describes a mode switch rather than tool selection. An agent must infer from 'summary' that this is the overview/aggregation entry point.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds one real behavioral fact beyond that — that id-mode expands the payload to include notes and tasks — but says nothing about pagination limits, default page size, or ordering.

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 front-loaded sentence with two clauses, each carrying distinct information (list mode vs. id mode). No filler, no restatement 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 9-parameter read tool with no output schema, the description covers the mode switch but not result shape, pagination behavior, or whether filters combine conjunctively. Adequate to call it, not complete enough to predict what comes back.

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 needs to carry weight. It clarifies the most consequential parameter (`id` switches from list to detail mode with nested notes/tasks) and hints at stage/contact/company filtering, but leaves limit, offset, pipelineId, companyId, contactId and deleted 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 (list) and resource (deals), and importantly discloses a second mode: passing `id` returns a single deal with notes and tasks. That dual-mode description lets an agent distinguish the read path from deals_manage, though it never names the sibling 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?

It gives one concrete routing rule ('pass `id` to fetch one deal'), which is genuinely useful. But there is no guidance on when to use this versus deals_manage, or how to combine filters, so usage is only partially 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?

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds real substance beyond them: delete is a soft delete, update leaves omitted fields unchanged, stageId assignment moves the deal between stages, and restore via deletedAt undoes an entire prior delete. Remaining gaps are permissions requirements and pagination/return behavior for create.

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 organized by action, with the highest-risk operation (delete) flagged inline rather than buried. No filler, and the action list is front-loaded right after the verb.

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

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

For a 12-parameter destructive mutation tool with no output schema, the description covers action selection and the delete/restore lifecycle well but omits what create returns (the new id), whether delete accepts only a single id, and never mentions lostReason or valueCents semantics. Adequate, not 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 83%, so the schema already documents most parameters including their action applicability. The description adds only marginal semantics ('stageId moves it', 'ids from deals_list deleted') and says nothing about lostReason or the currency implication of valueCents.

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

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

Opens with a broad verb ('Change deals') but immediately enumerates the four supported operations (create/update/delete/restore), which pins the resource down. It also distinguishes itself from siblings by naming deal_stages_list as the source of stageId and deals_list as the source of restore ids, so the agent knows this is the write counterpart to those readers.

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

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

Each action carries a short usage cue: create needs title and stageId from deal_stages_list, restore takes ids from deals_list deleted, delete is soft and should be confirmed first. That is clear per-action context, though there is no explicit 'do not use this for X, use sibling Y instead' exclusion.

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 safety is covered. The description adds the useful behavioral fact that the returned data includes the pipeline_id linkage on stages and that this is a prerequisite call before deal creation or movement — real context beyond 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?

Two short sentences, zero filler, and the content description is front-loaded ahead of the call-to-action guidance. 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?

With no output schema, the description usefully enumerates what comes back (pipelines, stages, contact statuses) and when to call it, which is enough to invoke correctly. A brief note on response shape or ordering would push it higher, but nothing essential is missing for a zero-parameter read tool.

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

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

The tool takes no parameters, so the schema-coverage baseline of 4 applies; there is nothing for the description to disambiguate. The parenthetical '(stage pipeline_id)' hints at the structural relationship in the payload but is not a parameter concern.

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 enumerates the resources returned: pipelines, their stages, and contact statuses. It is clear what the tool returns, though the parenthetical '(stage pipeline_id)' is terse and it does not explicitly differentiate itself from the sibling deal_stages_manage or deals_list.

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

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

'Call before creating or moving a deal' gives a concrete triggering condition that an agent can act on without inference. It stops short of naming the alternative tool (deal_stages_manage) or stating when not to call it, so it is clear context rather than full routing guidance.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description reinforces this with real operational constraints beyond them: delete cannot remove the last stage, deals in a deleted stage must be reassigned via reassignTo, and the caller should confirm first. It stops short of saying whether reordering via `order` rewrites every stage at once or what permissions are required.

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

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

Three action clauses in one sentence, front-loaded with the resource and no filler. The telegraphic fragments ('never the last stage; confirm first') trade a little readability for density but every clause carries an operational fact.

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

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

For an 11-parameter destructive mutation tool with no output schema, the description covers the risky paths (delete constraints, reassignment) well but omits how `pipelineId` scopes the operation and how `order` interacts with `position`. An agent could still pick the wrong reordering parameter without opening the 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 coverage is 64%, and the description does add meaning the schema lacks for isWon/isLost ('mark the end stages') and clarifies that `order` takes every stage id left to right. However, it leaves the relationship among `order`, `position`, and `pipelineId` unexplained, and parameters like `probability` and `color` are covered only by 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?

The opening 'Pipeline stages' plus the create/update/delete action list states a specific resource and verb set, so an agent knows this mutates stage configuration rather than reading it. It never names the sibling deal_stages_list, so the read-vs-manage distinction is only implied by the 'manage' suffix.

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

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

Each action carries a condition: create uses isWon/isLost to mark end stages, update goes 'by id, or `order`: every stage id left to right', and delete requires reassignTo and 'confirm first'. That is concrete when-to-do-what guidance, though it never points to deal_stages_list for read-only lookups or deals_manage for the deals being reassigned.

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 destructive=true, openWorld=true, idempotent=false, and readOnly=false. The description adds valuable behavioral context: send emails each signer, remind emails whoever is due, void cancels for good, and send/remind require confirmation first. It does not discuss permissions or rate limits, but it meaningfully extends the annotation profile.

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

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

The description is compact and front-loaded, opening with the resource scope and then packing each action into a short parenthetical. No sentence is wasted, and the action list remains scannable.

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

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

For a six-action, eleven-parameter tool, the description covers all actions and important status semantics. It is somewhat thinner on return values and pagination, but it gives enough context for correct invocation given the schema's high 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 already 91%, and the description adds action-parameter mapping plus status meanings such as sent=waiting and completed=signed by all. It reinforces which parameters belong to which action, though it does not add syntax details beyond the already rich schema.

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

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

The description identifies the resource precisely as documents sent for signing and enumerates every action (list, get, templates, send, remind, void). This gives an agent a clear verb-plus-resource picture and the action vocabulary needed to select the 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?

Each action is paired with its operational purpose: list by status/contactId, get signers and history, templates for saved forms, send to email signers, remind due signers, and void a waiting document. It does not explicitly compare against sibling tools such as templates_manage or state when not to use this tool, so it stops short of full guidance.

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

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

Annotations already cover readOnly, idempotent, and non-destructive, so the bar is lower. The description still adds a genuinely useful trait beyond them: 'Reading does not mark anything read,' which tells the agent there is no read-status side effect. It stops short of describing result shape or pagination behavior.

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

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

Terse and front-loaded: the core verb leads and the three action clauses follow in a single compact span with no filler. The dense parenthetical phrasing is slightly cryptic on first read but every clause carries information.

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

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

With 8 parameters, no output schema, and one required field, the description covers what each action does and the key non-side-effect trait. Because there is no output schema, the return shape (thread list fields, pagination cursor `next_before`) is only partially conveyed through the schema's `before` description, leaving a small gap.

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

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

Schema coverage is 88%, so baseline is 3, but the description earns more by mapping each enum value of `action` to a distinct meaning and clarifying that `messageId` returns one full body versus `threadKey` returning the thread's messages. The action values themselves carry no per-value description in the schema, so this is real added value.

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 verb (read) and resource (email), then enumerates the three concrete actions with their scopes: threads = inbox list, thread = a thread's messages or one full body, accounts = mailboxes and send-as addresses. This lets an agent distinguish the tool from email_send and email_thread_update without opening the schema. It does not explicitly name a competing sibling for read-like operations, which keeps it just below a 5.

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

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

The description implies when each action is appropriate (threads for listing, thread for a conversation, accounts for send-as addresses) and the schema adds 'only when the snippet is not enough' for messageId. However, there are no explicit when-not rules or named alternatives among the read siblings, so usage must be inferred from the action enumeration.

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: this sends a real external message, defaults to the oldest connected mailbox, has a hard 50-recipient ceiling, and one-to-one mail bypasses the campaign suppression list — a behavior an agent would otherwise get wrong. The instruction to confirm with the user before sending is exactly the safety context the annotations (destructiveHint=false) do not supply.

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?

Five short sentences, each carrying a distinct constraint (mailbox default, body pairing, contactId effect, recipient cap, suppression bypass, confirmation). The most consequential facts — real send and user confirmation — are not 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 12-parameter outbound-send tool with no output schema, the description covers the decisions that matter: which mailbox, how to supply the body, recipient limits, and confirmation. It does not say what is returned (message id) or how scheduling interacts with the confirmation requirement, a minor gap given the tool's complexity.

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 schema coverage at 42%, the description compensates by explaining that bodyHtml and bodyText are alternatives, that contactId drives merge-tag resolution and threading, and that to/cc/bcc share a 50-address budget. It leaves fromName and the cc/bcc/subject fields undocumented beyond their names, so the compensation 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?

States a specific verb and resource ('Send a real email') plus the sending context ('from the user's connected mailbox, default: the oldest one'), which an agent could not infer from the name. The line 'a list is a campaign' draws the boundary against campaign-style sending in the sibling 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?

Gives concrete preconditions: supply bodyHtml and/or bodyText, pass contactId for merge tags and threading, stay within 50 recipients, and confirm with the user first. It signals that a recipient list becomes a campaign rather than naming campaigns_manage as the alternative, so routing is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful behavioral detail that this is a state toggle/refile rather than a content edit, but it omits what happens when both fields are supplied, whether a move is reversible, and what a successful response looks like.

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

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

A single tight sentence with no filler, and the two capabilities are front-loaded. It is slightly compressed in that the two modes ('mark' vs 'move') are fused into one clause rather than separated.

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

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

For a three-parameter mutation with full schema coverage and no output schema, the description covers the essential behavior. It still leaves gaps an agent would want: behavior when no optional field is provided, and confirmation of what the tool returns after the update.

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 every parameter already carries its own description including the enum meanings and the 'inbox also un-archives' note. The description mirrors those concepts at a high level but contributes no syntax, defaults, or interaction rules beyond the schema, which is the baseline-3 case.

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

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

The description names a specific resource (an email thread/conversation) and two concrete operations (mark read/unread, move to a folder), so the agent knows exactly what state changes are possible. It does not, however, contrast itself with the nearby email_read sibling, so sibling differentiation is left to the name.

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 by the operation list: an agent can infer 'call this to flip read state or refile a thread.' There is no explicit when-not guidance, no statement that it acts on an existing thread identified by threadKey, and no pointer to email_read for retrieving content instead.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is partly pre-supplied. The description still adds genuine value beyond them: forms are publicly linked, submissions write to contacts, delete breaks the public link and requires confirmation, and submissions returns only the latest 200 — a real behavioral constraint not encoded anywhere else. It doesn't say what 'update' does to unspecified fields or what permissions are needed.

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 one-liner plus a compact action grammar with zero filler; every clause carries information. The terse 'create (name?, templateId?)' / 'update (id + changes)' notation is efficient but slightly ambiguous about which of the 13 fields 'changes' covers.

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, no-output-schema, destructive tool, the description covers action routing, the write side effect on contacts, the delete consequence and the submissions cap. Remaining gaps (return shapes for list/get, required field structure, pagination) are modest but present given no output schema exists to cover them.

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?

Description maps parameters to actions (id for get/delete/submissions, name+templateId for create, id+changes for update), which the schema does not do on its own. At 54% schema coverage, several params (tags, fields, style, createTask, redirectUrl) rely on schema text, and the description gives no additional meaning for them, so it stops at a solid 4.

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 resource (lead-capture forms), the key mechanism (public link) and the side effect (each submission creates or updates a contact), then enumerates every action verb. An agent can immediately tell this apart from siblings like campaigns_manage or contacts_manage.

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 action grammar doubles as usage guidance: 'templates' is implicitly the source of templateId, 'get' vs 'submissions' vs 'list' are distinguished by argument, and delete carries an explicit warning ('the link stops working; confirm'). It doesn't name alternatives or state exclusions, so it stops 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?

The annotations declare destructiveHint=true, but the description adds critical behavioral facts an agent could not infer: create returns the full URL with token exactly ONCE and it cannot be shown again, and delete takes effect immediately. These are exactly the kind of consequences an agent needs before calling.

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

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

It's dense and front-loaded: definition first, then the action list, then the two highest-stakes behavioral warnings. No sentence is filler and the warning that the URL can't be shown again is placed prominently.

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 spends words on what create returns and what delete does. It's slightly thin on what get/list return, but for a 9-parameter tool with a rich schema, an agent has enough 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 78%, near the high-coverage baseline, and the schema itself documents id, name, isActive, ipAllowlist, mappingJson and signingSecret in detail. The description only paraphrases the action enum and does not add meaning about ipAllowlist, mappingMode, or signingSecret beyond the schema, 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?

The description states a specific resource and mechanism—'URLs other services POST to so Groundbase creates contacts, deals, tasks'—which immediately distinguishes it from the sibling outbound_webhooks_manage. An agent knows exactly what this tool manages without inspecting the schema.

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

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

It enumerates the action verbs and gives a clear conditional instruction for destructive use ('delete stops the URL accepting posts immediately; confirm first'). What's missing is an explicit pointer to outbound_webhooks_manage for the opposite direction, so it's clear context but not full alternative routing.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=false, so the bar is lower; the description still adds real context by stating that deleting an item does not remove lines already on invoices, and that save without id creates versus with id edits. It does not say whether edits are reversible, what happens to items referenced by templates, or anything about permissions.

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 leads with the resource then breaks each action into a parenthetical clause — front-loaded and essentially waste-free. The telegraphic compression makes it dense to parse on first read, which keeps it just under 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?

For a 9-parameter, nested-object mutation tool with no output schema, the description covers the action semantics and delete side effects but omits what list returns (item shape, currency interpolation), how defaults like baseCurrency apply across actions, and the non-idempotency implication of save. Adequate to invoke, incomplete for confident use.

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 78%, so the schema already documents id, name, prices, unitPrice, baseCurrency and defaultTaxRate. The description only restates that prices are decimal strings and that save needs an id to edit, adding little beyond the structured fields; it says nothing about the nested prices object's conversion semantics or the relationship between unitPrice and prices.

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 ("saved invoice items (services / products)") and enumerates the three supported actions with their effect, which lets an agent separate it from invoices_manage or invoice_payments_manage. It stops short of explicitly stating the boundary against those 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?

Each action carries its use condition: list returns prices per currency, save is create-or-edit-by-id, delete removes the item but leaves existing invoice lines intact. No exclusions or named alternatives (e.g., editing a line on an existing invoice via invoices_manage) are given, which keeps it a step below 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 destructiveHint=true and openWorldHint=true; the description adds the important unwritten detail that 'record' sends an outbound receipt email (external side effect requiring confirmation) and that 'reverse' undoes a recorded payment, effectively pinpointing which action is destructive. It does not say whether reversal is reversible or what happens to the receipt already sent.

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 compact sentence with the two actions front-loaded and the exclusion trailing; nothing is wasted. The parenthetical density is high enough that it reads as shorthand, but every clause carries information.

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

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

For a 10-parameter mutation tool with no output schema, the description should say which inputs each action requires (e.g. record needing invoiceId and amount). It covers side effects and the reverse path but leaves the record path's required inputs and any response/return behavior unstated.

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

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

Schema coverage is 50%: amount, sendVia, reference, receivedAt, and sendReceipt are described in the schema, while notes, method, invoiceId, paymentId, and action are not. The description compensates for paymentId ('paymentId; undoes a recorded payment') and the action enum, but leaves invoiceId, amount, and method unaddressed for the record path.

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 two specific verbs with their resources and parenthetical semantics: 'record (a payment taken outside Stripe...)' and 'reverse (paymentId; undoes a recorded payment)'. It also scopes out card refunds ('done in the app'), which distinguishes it from invoices_manage and refund-adjacent siblings.

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

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

Gives the condition selecting each action and an explicit exclusion boundary ('Card refunds are done in the app'), plus a caution to 'confirm first' before the receipt email fires. It doesn't name a sibling tool as the alternative, but the app-boundary exclusion is a clear when-not signal.

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower, and the description still adds two non-obvious behaviors: set is a partial merge where omitted fields are preserved, and nextNumber is monotonic ('only moves forward'). What it omits is any statement about what 'get' returns or how numbering interacts with existing invoices.

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 compact sentences: the resource scope first, then the action model and the two behavioral rules in parentheses. No filler, and the most decision-relevant constraints are packed into the trailing 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 14 parameters, no output schema, and thin schema descriptions, an agent still cannot tell what 'get' returns or how most fields behave (required formats, currency codes, whether empty string clears a field). The mutation semantics are well covered; the read-side and per-field details are not.

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 21% across 14 parameters, so the description carries a real burden. It partially compensates by grouping the parameters into business details, payment instructions, and numbering, and by explaining the semantics of nextNumber and omitted fields — but the majority of parameters (currency, terms, address, prefix/padding) get no additional meaning beyond their names.

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 resource (invoice settings) and enumerates the content domains it governs — business details on invoices/receipts, payment instructions, numbering — plus the two supported actions (get/set). It reads clearly as a settings singleton, distinct from invoices_manage and invoices_list, although it never names those siblings explicitly.

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

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

The get/set pair is stated and the partial-update rule ('omitted fields unchanged') tells the agent how to call a set, but there is no guidance on when to reach for this versus invoices_manage or sending_settings. Usage is implied by the action enum rather than explained.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine beyond-schema behavior: list mode returns outstanding totals per currency; `id` mode returns lines, charges and amount paid; sub-resource flags (payments/creditNotes/recurring) are only meaningful when `id` is supplied. That is real depth the annotations do not 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?

Compact with no filler, but the fragmentary, semicolon-and-parenthetical style ('With id: payments (ledger), creditNotes, or recurring.') makes a three-mode tool harder to parse than a short bulleted breakdown would. Front-loaded, yet the compression 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 14-parameter, three-mode, no-output-schema tool, the description explains the modes and key return payloads but omits how to choose among the several filter parameters, pagination semantics, and what each report actually returns. Adequate as a map, insufficient as a manual.

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

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

At 57% schema coverage, the description compensates partially: it clarifies that `id` returns lines/charges/amount paid, that payments/creditNotes/recurring are 'with id' modifiers, and that `from`/`to` take YYYY-MM-DD in report mode — detail absent from the schema. But `companyId`, `contactId`, `limit`, `offset` and the exact `q` vs customer-filter distinction remain undocumented in prose.

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 (invoices) and enumerates three distinct modes: filtered list, single-invoice-by-id, and reports. A reader can distinguish it from invoices_manage, but the telegraphic phrasing ('or `id` for one with lines, charges and amount paid') blurs the boundary between 'list' and 'fetch one' rather than stating it cleanly.

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 implicitly signals mode selection (use `id` for a single invoice, `report` for aging/revenue/tax, otherwise list with filters), but never states when to prefer this over invoices_manage or invoice_payments_manage, nor any prerequisites. Usage is inferable but not 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?

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is present. The description adds meaningful behavioral context: issue and credit_note are final, send emails the invoice, recurring auto-sends email copies, public_link can be revoked, and final or sent actions require confirmation. It does not explain void's downstream effects or return behavior, but the added confirmation/finality guidance 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 description is extremely compact, front-loads the resource, and then lists each action with only the essential distinguishing note. Every phrase earns its place, even with nine actions and 27 parameters behind it.

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 complex, destructive, nine-action tool, the description covers the full action surface and calls out confirmation for final or sent operations. The detailed param schema and annotations fill most remaining gaps, though the description does not explain return values or some void/send side effects. It is complete enough to call correctly, with minor room for richer context.

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 high at 81%, so the schema already carries most parameter meaning. The description consolidates action-to-parameter mappings such as credit_note using amount and reason, send_credit_note using creditNoteId, and recurring using frequency and nextRunDate, but those mappings are largely repeated from the parameter descriptions rather than adding new semantics. Baseline 3 is appropriate.

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

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

The description names the resource and enumerates every action with a short verb-level gloss: save_draft creates or edits, issue finalizes, send emails, void, public_link, credit_note, recurring, and stop. This makes the tool's purpose unambiguous even without opening the schema. It does not explicitly distinguish itself from invoices_list, but the action set clearly signals mutation rather than listing.

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 parentheticals give clear action-selection context, such as save_draft for create/edit, issue for final numbering, send for emailing, revoke for public_link, and stop for recurring. The closing instruction 'Confirm anything final or sent' is an explicit operational guideline. It does not name sibling alternatives or say when not to use the tool, so it stops 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 past the annotations by disclosing the external side effect (an email confirmation is sent, SMS if configured) and the failure shape (a clash returns booked:false + conflicts). It also flags the user-confirmation requirement and the constrained retry path, which an agent could not infer from readOnly:false / destructive:false 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?

Eleven parameters are covered in five dense sentences with the primary action front-loaded and the mode prefixes ("slots:", "book:") making it scannable. No sentence is filler; the telegraphic style costs a little readability but maximizes information density.

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

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

For an 11-param, non-idempotent, open-world write tool with no output schema, the description covers side effects, conflict handling, and consent requirements. The remaining gap is the success return shape (what a confirmed booking yields) and the exact semantics of newContact, which neither description nor schema fully pins down.

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 73%, so the schema does most of the work, but the description adds genuinely new semantics: the contactId OR name+email/phone alternative path for identifying the contact, and the from/to date format scoping for slots. It stops short of explaining newContact or the allowOverlap/conflicts interaction in detail.

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?

"Book a contact into a meeting type" is a specific verb+resource, and the description immediately separates the two modes of operation (slots vs book) so an agent knows this tool both reads availability and writes a booking. It does not name the related sibling meeting_types_list/meeting_types_manage, so differentiation from those is left to the schema's "From meeting_types_list" hint.

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?

Offers real conditional guidance: prefer an open slot, any future time only if the user asks, allowOverlap only with user agreement, and confirm with the user before proceeding. These are clear when-to/when-not rules for the internal modes, though no alternative tool is named for cases where the booking should not happen here.

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 this as read-only, idempotent, non-destructive, and closed-world, so the bar is lower. The description still adds useful context by naming the returned fields and explaining that Google Calendar connection status is included because busy times are kept 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?

Two sentences, front-loaded with the core action and resource. The parenthetical gloss and the Google Calendar explanation both earn their place by clarifying what the tool returns.

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

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

For a zero-parameter, read-only list tool with no output schema, the description provides enough detail about the returned content to call it correctly. It could be slightly more complete by noting whether all meeting types are returned or by explicitly contrasting with meeting_types_manage.

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 itself is trivial and the baseline is 4. The description does not need to explain parameter behavior and appropriately does not attempt to.

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 tool lists booking meeting types, with a helpful gloss ('the public links people book through') and the key fields returned. It does not explicitly distinguish itself from the sibling meeting_types_manage tool, so it falls short of full sibling differentiation.

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 verb 'List' and the read-only nature of the operation, but there is no explicit guidance on when to use this versus meeting_types_manage or meetings_book. No prerequisites or exclusions are 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 and non-idempotent, and the description adds real consequences the annotations can't convey: slug changes break shared links, deletion kills the public link but leaves bookings intact, and confirmation is required first. This is exactly the blast-radius context an agent needs before mutating.

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 dense sentence with the resource front-loaded and each action's consequence attached inline; no filler and no restatement of the schema. Telegraphic style is a deliberate fit for a three-action manage tool.

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 15 params, a nested object, and no output schema, the description covers the destructive semantics well enough to call safely. The remaining gap is update semantics (full replace vs partial) and the shape of the availability/intakeQuestions objects, which neither schema nor description resolves.

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 93%, so per-field meaning (bufferMin, maxAdvanceDays, isActive) is already documented in structured data. The description adds one useful structural note — create accepts name, slug, and any field update takes — but adds nothing on the nested availability or intakeQuestions payloads. Baseline 3 is appropriate.

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

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

States the resource precisely ('Booking meeting types (the public links)') and enumerates the three operations (create/update/delete), which an agent can readily separate from meeting_types_list or meetings_book. It stops short of naming the sibling list/book tools explicitly, so differentiation is by inference 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?

Per-action guidance is concrete: update warns that changing slug breaks already-shared links, delete notes the link stops working while bookings persist and instructs to confirm first. It doesn't say when to prefer this over meetings_book or meeting_types_list, but the action-level conditions are 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds the entity-scoping constraint but says nothing about pagination behavior or the shape/cost of the result set, which would be useful for a list endpoint.

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 with the resource first and the critical selection rule immediately after, in parentheses. Nothing is redundant and nothing needs reordering.

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 agent has no structured signal about what a note object looks like or whether results are paginated; the description does not fill that gap. The core calling contract is complete, but return-value and pagination behavior remain undocumented.

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, and it does for the most important part: it explains that the three ID parameters are mutually exclusive and that exactly one must be supplied — a constraint the schema cannot express (no required fields, no oneOf). It leaves limit/offset entirely to the schema, where only limit has a partial note.

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 ('List') and resource ('notes') plus the exact scope: notes attached to a contact, company, or deal. The parenthetical constraint makes it unambiguous and clearly separates it from the mutating sibling notes_manage.

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 gives a hard invocation rule — pass exactly one of contactId / companyId / dealId — which tells the agent precisely how to call it. It does not explicitly name an alternative (e.g., notes_manage for creating/updating), so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and 'confirm first' on delete is consistent with that rather than a contradiction. The description does not say whether deletes are permanent, whether update replaces or merges fields, or what gets returned, so it adds only modest context beyond 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?

Two short sentences, front-loaded with the resource and then the actions; nothing is padded. The terseness borders on under-specification but no sentence is wasted.

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

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

This is a destructive multi-action mutation tool with six parameters, a third of them undocumented, and no output schema. Missing are the parent-id exclusivity rule, the permanence of delete, and update semantics — all of which the agent must know 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 only 33%, and the description partially compensates by tying body and the three parent ids to create. It never explains whether one or multiple parent ids may be supplied, nor that id is needed for update/delete (that only appears in the schema text).

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

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

The description names the resource (notes) plus the entities they attach to (contact, company, deal) and enumerates the three actions create/update/delete. That is enough to place it against notes_list, though it never explicitly says 'this is the write counterpart to notes_list'.

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

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

'delete (confirm first)' gives one concrete procedural cue, and the create parenthetical implies you supply a parent id alongside body. There is no stated boundary against notes_list, and no guidance on when to use update versus delete-and-recreate or on choosing among contactId/companyId/dealId.

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 openWorldHint=true, and the description adds real context beyond them: the secret is returned ONCE, CRM data (names, emails, phones) is transmitted to the URL, the owner is emailed, and delete stops deliveries and abandons retries.

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 what a webhook is, then the action set, then per-action constraints. Dense and telegraphic but essentially every clause carries a decision the agent needs; the compression makes it slightly harder to parse than prose.

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?

Seven parameters, no output schema, destructive multi-action tool — yet the description covers lifecycle, prerequisites, side effects, and confirmation requirements. Nothing an agent needs to invoke it safely 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?

At 71% schema coverage the schema already documents id, url, name, events, and isActive. The description reinforces which fields create requires (name, url, events) and adds payload-format nuance (Slack/Discord get readable messages, others signed JSON) that the schema also mentions but the summary elevates.

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 (outbound webhooks) and mechanism (Groundbase POSTs to a URL on subscribed events), then enumerates the five actions. It is clearly distinct from inbound_webhooks_manage by the 'outbound' framing plus the POST-to-URL explanation, though it never names the sibling 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?

Gives explicit operating rules: confirm the URL with the user before create or a URL change, confirm before delete, and tell the user the signing secret because it is returned only once. These are concrete when/when-not directives rather than inferred guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: it enumerates the returned fields and gives a presentation directive ('quote it; do not judge it') for the balance, which tells the agent not to editorialize a figure it cannot verify.

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 with the resource front-loaded and the field list in a compact parenthetical. Every clause carries information; there is no filler or redundancy.

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 at the field level (id, number, label, default-for-texts-and-calls) plus the balance. It stops short of stating the shape of the balance object or whether numbers include unverified/inactive entries, which is a minor remaining gap 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?

The tool takes zero parameters, so the baseline is 4. Nothing about inputs needs explaining, and the description correctly spends its words on the return payload instead.

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 resource returned: the user's phone numbers with their fields (id, number, label, default flag) plus the Twilio balance. An agent can tell immediately what data this yields. It lacks an explicit verb and doesn't reference any sibling, but no sibling in the list covers phone numbers or balance, so confusion risk is low.

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-to-use guidance and no named alternative. Usage is implied by the read-only resource name and the zero-parameter schema, which makes invocation self-evident, but the description itself does nothing to route the agent.

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 this as read-only, idempotent, non-destructive, and closed-world. The description adds valuable behavioral context about what the list returns (counts per status and open value per currency) and what the single-quote mode includes (lines, totals, deposit, acceptance details).

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 front-loaded sentence with no wasted language. The list mode and the `id`-based detail mode are both stated compactly.

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?

Because there is no output schema, the description usefully explains what both modes return. It is nearly complete for a read-only list/retrieve tool, though it leaves some filter and pagination parameters unexplained.

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

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

Schema description coverage is only 50%, so the description should compensate for undocumented parameters. It clarifies `id` behavior, but it does not explain `offset`, `companyId`, or `contactId`, nor does it describe filtering or pagination behavior beyond what the schema provides.

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

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

States a specific verb and resource and distinguishes two modes: listing quotes versus passing `id` to retrieve one quote. It does not explicitly distinguish itself from `quotes_manage`, but the read-only purpose is clear.

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

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

The description tells the agent when to pass `id` for the single-quote mode versus using the list mode. It provides clear context for mode selection but does not explicitly state exclusions or point to `quotes_manage` for writes.

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 important behavior: send emails the quote externally with an accept link and requires confirmation, convert creates a draft invoice, and public_link can be revoked. This aligns with the destructive/open-world annotations, though it does not cover permission requirements, rate limits, or return behavior.

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

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

The description is a single dense sentence that front-loads the resource and then lists every action with a compact effect. There is essentially 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 23-parameter action multiplexer with no output schema, it covers the most important selection context: every action and its key side effect. The schema carries parameter details and annotations carry the safety profile, but return values and some per-action prerequisites remain implicit.

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 high at 78%, so the schema already documents most parameters. The description adds material meaning for the central action parameter by explaining what each enum value does, which the schema enum alone does not provide. It does not add much for the other 22 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 resource and enumerates all seven lifecycle actions with specific effects: save_draft creates/edits, issue numbers, send emails, record_outcome records acceptance/decline, convert makes a draft invoice, void, and public_link manages the accept link. It is clear enough to distinguish this from a read-only quotes tool, though it never explicitly names quotes_list as the sibling for listing.

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

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

It gives clear action-level context: record_outcome is for use after a conversation, convert applies to accepted quotes and produces a draft invoice, send includes a confirmation, and public_link can be revoked. It does not explicitly state when to use this tool versus quotes_list or invoices_manage, so it is clear but lacks exclusions/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?

The description states the connection is 'read-only', while annotations declare readOnlyHint=false and idempotentHint=false. That is a direct contradiction of the safety profile an agent relies on, even though the enumerated actions are in fact reads. The otherwise useful disclosure of where the remaining operations live cannot offset a conflicting safety claim.

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 with no filler, front-loaded with what the connection is before the action list and the off-tool routing note. Slightly dense parenthetical packing, but 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 one-parameter, no-output-schema tool this covers the main decision points: available actions, the domains prerequisite, and where the excluded operations live. It still leaves the shape of each response (what status returns, what a domains entry contains) entirely unspecified, which matters since no output schema exists.

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 the single action enum. It does: 'domains (verification state; check before choosing from_email)' explains both what the value returns and when to pick it, and 'status' is at least recognizable in context. Minor gap: it never spells out what status reports.

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 specific resource (the BYO Resend connection used for email campaigns) and enumerates the two supported actions, status and domains. An agent can distinguish it from siblings like sending_settings or email_send because the description explicitly says connecting, disconnecting, test sends and tracking happen elsewhere.

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 condition — call domains and check verification state before choosing a from_email — and explicitly redirects the other related operations to the app under Settings > Email. It lacks a 'do not use this for X' exclusion, but the routing guidance 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description's real contribution is the domain gloss on what a saved view represents, which is genuinely useful context; it says nothing about ordering, pagination, or whether a default set is returned.

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 verb and resource, with the parenthetical earning its place by defining an ambiguous domain term. 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 zero-required-parameter read list with rich annotations and no output schema, the description covers what the tool is and what the optional filter does. Only minor gaps remain (result ordering, empty-list behavior, relationship to saved_views_manage) that an agent could 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% and the single parameter is documented as 'Only views for this record type' with a four-value enum. The parenthetical in the description lists the same four record types, slightly reinforcing the filter semantics but adding no syntax or default behavior beyond the schema.

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

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

The description states a specific verb and resource ('List saved views') and adds a clarifying gloss ('named filters over contacts, companies, deals or tasks') that tells an agent what a saved view actually is. The list-vs-manage split with the sibling saved_views_manage is clear from the verb and read-only annotations, though the description never names the sibling 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?

Usage is implied rather than stated: an agent can infer this is the read path and saved_views_manage is the write path. There is no explicit when-to-use guidance, no mention of whether views must be created first, and no exclusion statements.

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 this as non-read-only and destructive. The description importantly clarifies that delete removes the saved view but 'the records stay,' which prevents a serious misinterpretation of destructiveHint. It does not discuss idempotency or permissions, but with annotations covering the safety profile this is solid added context.

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

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

The description is extremely compact and front-loads the resource definition before breaking down each action. Every phrase carries useful information, including the key deletion clarification.

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 five-parameter manage tool with no output schema, the description covers the action set, filterJson creation guidance, and delete semantics adequately. It omits any explanation of entityType, which is the main remaining contextual gap.

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

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

Schema coverage is 60%, and the description helps with filterJson by telling the agent to copy its shape from saved_views_list. It does not explain entityType, and id/name requirements are left to the schema. Baseline 3 is appropriate given partial schema coverage and only marginal extra parameter guidance.

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 as saved views (named filters) and enumerates the managed actions create, update, and delete. It also references saved_views_list for filter shape, but it does not explicitly draw the full boundary between managing views and listing 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?

It gives action-specific hints such as 'rename or change the filter' for update and 'copy filterJson's shape from saved_views_list' for create. However, it does not explicitly state when to choose this tool over saved_views_list or explain prerequisites for each action, leaving usage mostly implied by the action enum.

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 the effect of null (none) and 0 (stop today), account-wide versus per-domain scoping, and that over-cap recipients wait for later days. It does not discuss permissions or idempotency nuances, but the key behavioral consequences are covered.

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 core constraint and then packs get/set semantics into a compact line. Every clause carries useful 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?

With no output schema, the description still explains what get returns and what set affects, including domain-level behavior. It is nearly complete for a small dual-action settings tool, with only minor auth/permission context 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 67%, and the description compensates well by explaining action outcomes, domain scoping, and the null/0 semantics for daily_email_send_cap. It adds meaningful interpretation beyond the structured fields.

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 resource (daily cap on campaign EMAILS) and operation (get/set), explicitly excluding SMS. It also names the exact fields returned by get and the value written by set, so an agent can distinguish it from siblings like sms_manage or email_send.

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 case (warming a new domain at roughly 20/day) and explains get versus set behavior. It does not enumerate alternatives beyond excluding SMS, but the context is strong enough to guide selection.

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 behavior. The description adds useful behavioral context: oldest-first ordering, both directions, a matched:false marker when none exist, and scheduled queue semantics.

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, front-loaded sentence with no wasted text. It packs modes, ordering, and the no-match indicator into a compact structure.

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 provides key return context such as ordering and matched:false. It does not describe the response fields or limit behavior, though the schema covers the limit parameter and annotations cover safety.

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 schema already documents phone, contactId, scheduled, and limit. The description reinforces the phone/contactId alternative and scheduled mode but adds little syntax or constraint detail beyond the schema.

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

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

The description uses a specific verb and resource: 'Read the text conversation,' with clear modes for phone/contactId versus scheduled texts. It implicitly distinguishes listing from sending or managing, but does not explicitly name or differentiate from siblings like sms_send or sms_manage.

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 explains how to use the tool for conversation history versus scheduled texts. It provides context for both modes but does not mention alternatives or explicit when-not 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 destructiveHint=true and readOnlyHint=false, and the description adds important behavioral detail: delete_thread removes a whole conversation, nothing is sent, and confirmation is required first. It does not explicitly state irreversibility or permission requirements, but it meaningfully supplements 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?

The description is a single compact sentence fragment with no wasted words, front-loading the two action names and their key semantics. The telegraphic style is efficient despite being terse.

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, multi-action tool with no output schema and 0% schema description coverage, the description covers the core action mapping but omits permanence of thread deletion, permission requirements, error behavior, and any sense of what the tool returns or confirms. It is minimally adequate but leaves meaningful 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 must carry parameter meaning. It usefully maps id to cancel_scheduled and phone/contactId to delete_thread, but it does not define expected formats, clarify the required action selector, or explain when phone versus contactId should be used.

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 both supported actions and their resources: cancel_scheduled for a queued text, delete_thread for a whole conversation. It distinguishes itself from sms_list by explaining where the id comes from, though it lacks a top-level statement of the tool's overall purpose beyond 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 gives clear usage context: use cancel_scheduled with an id from sms_list scheduled, and use delete_thread with a phone or contactId and confirm first. It does not explicitly exclude sending or point to sms_send as an alternative, so it stops short of full when/when-not 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses the two facts an agent most needs before firing: this sends a real message and it is billed per segment on the user's own Twilio account, plus a confirm-first requirement. That is meaningful side-effect and cost transparency the annotations cannot encode.

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 tight sentences with no filler; the primary action is front-loaded and the safety/billing caveat follows immediately. 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 5-parameter, no-output-schema mutation tool, the description covers the essential risk profile (real send, billed, confirm first). The only gap is what a successful call returns (e.g., message identifier or scheduling confirmation), which matters when scheduledAt is used.

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 80%, and the parameter descriptions already cover E.164 formats, contactId threading, fromNumber defaulting, and scheduledAt semantics. The description only echoes the scheduledAt behavior ('omit to send now') rather than adding syntax, constraints, or edge cases, 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?

The description opens with a specific verb+resource ('Send a text') and immediately qualifies the timing variant (now vs. scheduledAt). This is clearly distinguishable from sms_list and sms_manage, the adjacent SMS siblings, without needing to open 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?

It states an explicit precondition ('confirm with the user first') and clarifies the scheduling fork ('or later with scheduledAt'). It does not name alternative tools (e.g., email_send) or exclusion criteria, so it falls short of a 5, but the operational 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 flag destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds real context beyond that: removing a suppression re-consents the contact for messaging, that permission is required, and adds/removes should be user-confirmed. It does not disclose whether adds are deduplicated, what list returns, or pagination behavior, keeping it out of the top band.

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 clauses in one dense line, front-loaded with the scope ('Who must not be messaged') before the mechanics and the confirmation rule last. Every clause carries information. The semicolon-chained fragments read as terse shorthand and cost a little 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 destructive mutation tool with no output schema, the description covers the selection logic, the mutation semantics, and the human-approval requirement. The remaining gap is the list mode's return shape and paging expectations, which the schema hints at (limit 1-500, default 100) but does not fully substitute for an absent output 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?

With 67% schema coverage, the schema already documents limit, search, source, phone, emails, and phones. The description adds the channel×action matrix — which container parameter applies to which action — which is genuinely useful. However, the singular 'email' parameter is undocumented in both schema and description, leaving its role (single add? list filter?) ambiguous, so the description does not fully compensate.

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

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

Opens with a crisp scope statement ('Who must not be messaged') followed by the two channels and their real-world meaning (unsubscribed/bounced addresses, numbers that texted STOP), then enumerates the three actions. An agent immediately knows this is the suppression-list management tool and no sibling overlaps. It loses a point only for the telegraphic, fragment-style phrasing rather than a clean verb+resource sentence.

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 maps each action to its input shape (add via emails[]/phones[], remove via phone) and adds an operational rule: removals re-consent the contact and require their permission, and both adds and removes must be confirmed with the user. There is no alternative sibling to route to, so the absence of exclusions is not a gap. Usage guidance is clear, though nothing covers when to prefer list over search or how to page results.

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 openWorldHint=false, so the safety profile is covered. The description adds only that ids are included in the result, which is genuinely useful given there is no output schema, but says nothing about ordering, pagination, or volume.

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 short sentence with no filler, and the key information (tags plus their ids) 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?

For a zero-argument list tool, the description covers scope (the user's tags) and the shape of the payload (tags with ids), which partly compensates for the missing output schema. It would be complete with a note on ordering or whether results are bounded.

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 no parameter semantics to explain; baseline is 4. The description correctly signals that no filtering arguments exist.

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

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

Specific verb+resource ("List the user's tags") with the extra detail that ids are returned. It doesn't name tags_manage as the mutation counterpart, but the naming convention makes the split fairly obvious.

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: the agent can infer this is the read path versus tags_manage as the write path, but the description never states when to prefer this tool or what it excludes (e.g. no filtering, no search).

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?

Although annotations already flag destructive, non-idempotent, and open-world behavior, the description adds critical context beyond them: delete removes the tag from everyone and should be confirmed first, and applying a tag can start workflows listening for it. This is exactly the kind of side-effect and safety context an agent needs before invoking a destructive tool.

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

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

The description is compact and front-loaded: it opens with the resource and immediately lists the actions with the most important qualifiers. There is no filler, and each phrase carries operational meaning.

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

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

For a 7-parameter destructive management tool with no output schema, the description covers the dangerous action, confirmation guidance, apply semantics, and workflow side effects. It lacks explicit return-value or result information and does not route listing to tags_list, but the schema fills in most parameter details.

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 57%, and the description compensates by explaining that apply maps tagId to contactIds and remove:true removes the tag, and that update can rename or recolour. It leaves some details to the schema, but adds meaningful semantics for the most complex action.

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 the four specific actions (create, update, delete, apply) on tags, making the verb and resource clear. It does not explicitly distinguish itself from the sibling tags_list tool for read-only listing.

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 action-level usage context, such as confirming before delete and using remove:true to detach a tag, but it never states when to use this tool versus tags_list or other alternatives. The usage guidance is implied through action descriptions rather than explicit routing.

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