Scribe Mail

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

Goes well beyond the annotations: discloses additivity, idempotent merge semantics, that manual and condition-based recipients are preserved, that membership is re-resolved after directory sync (future joiners inherit), and that unknown entity uuids fail with 422. The idempotent/read-only hints are merely confirmed rather than relied upon.

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

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

Front-loads the core action and effect, then alternatives, then behavior, then failure mode. Every sentence carries distinct information with no padding.

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

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

With an output schema present, return values need no explanation, and the description still covers mutation semantics, preservation of other recipient types, sync re-resolution, and the 422 failure path. Nothing material to a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description lifts this by explaining that uuids are merged into existing targeting, duplicates/already-targeted entries are effectively no-ops, and unknown uuids produce a 422. It does not restate param syntax, but it adds merge and failure semantics the schema only partially covers.

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 (target a signature) and resource (whole directory org units/groups by uuid), and immediately explains the effect: every teammate in them becomes a recipient. It explicitly distinguishes itself from add_signature_recipients and remove_signature_recipient_entities, so an agent can route correctly without opening either schema.

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

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

Gives explicit when-to-use ('assign by team or department') and names the three alternative tools with the conditions that select each: individual emails, smart-field rules, and undo. This is a complete routing map for the recipient-targeting family.

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 (idempotentHint, destructiveHint, readOnlyHint), the description discloses the additive semantics (org-unit and condition-based recipients preserved), the side effect that Scribe queues installation on recipients' mailboxes immediately, the 404 for unknown signatures, and the required signatures:write scope.

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

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

Dense but front-loaded: the manual-assignment purpose leads, sibling routing and behavioral notes follow. Every clause carries information, though the routing and behavior sentences are somewhat packed together.

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

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

For a mutation tool with an output schema present, the description covers the essentials an agent needs: additive/idempotent behavior, install side effect, error code, scope, and confirmation path via list_signature_recipients. Return format needn't be described since the 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 coverage is 100% and the schema already explains uuid sources, batch-failure (422), and duplicate handling in depth. The description only restates "by email uuid", adding little beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Manually assign a signature to specific email addresses (by email uuid)") and immediately contrasts with add_signature_recipient_entities for org units, so an agent can distinguish it from siblings without opening schemas.

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

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

Explicitly routes: "use add_signature_recipient_entities to target whole org units or groups, set_signature_recipient_rules for smart-field conditions or all future emails, and remove_signature_recipients to undo." The when/when-not and alternatives are all named.

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

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

Annotations already declare it as a non-read-only, non-destructive, non-idempotent, open-world write, so the safety profile is covered. The description adds real behavioral context annotations cannot: the 15MB size ceiling, the 422 failure class (non-image, bad base64, disallowed URL), and the practical advice to fall back to a different input mode when fetching fails. Not a 5 only because retry/duplicate-upload semantics (relevant given idempotentHint=false) are not addressed.

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

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

Four sentences, front-loaded with the action, then the input rule, then the fallback, then the failure modes. Every sentence carries information; the fallback clause ("ask the user for a hosted URL or reuse an existing asset from list_assets instead of guessing") is slightly dense but still 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 an output schema present the description needn't explain returns, and annotations cover safety. What remains — what to upload, how to supply it, which fallback to take, and what causes a 422 — is all covered, so an agent could call this correctly on the first try.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the cross-parameter exclusivity rule and the filename-with-base64 coupling in one readable statement, plus the reassurance that data: URIs, base64url, and line-wrapped base64 are accepted without re-encoding. That last point is a genuine usability detail beyond 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?

States a specific verb and resource ("Upload an image to the workspace's asset library") and scopes it to images only, which separates it from list_assets, update_asset, and delete_asset. An agent knows exactly what operation this performs before opening the schema.

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

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

Explicitly states the mutual-exclusion rule ("Provide EITHER `file_base64` (+ `filename`) OR `source_url` — exactly one") and gives a decision path for the common case: use bytes for chat-uploaded files, and fall back to asking the user for a hosted URL or reusing an existing asset via list_assets rather than guessing. This names both the condition and the alternative tool.

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

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

Annotations already declare non-read-only, open-world, non-destructive behavior; the description adds real value beyond them with the 409 conflict condition, the validation pipeline (format, uniqueness, disposable/deny-list), and the 422 failure mode. It stops short of stating what happens to existing aliases or any rate limits.

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 compact sentences with no filler: purpose first, availability constraint and its failure code second, validation outcome third. Every clause is an actionable 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?

An output schema exists, so return values need no prose. For a 3-parameter creation tool with a non-trivial eligibility gate, the description covers purpose, precondition, and error semantics; nothing an agent needs before calling is missing.

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

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

Schema coverage is 100%, so the 3 (entity, format, and context-string) parameters are baseline-documented. The description goes beyond the schema by characterizing address validation (format, uniqueness, disposable/deny-list) and reinforcing that the alias leaves the primary address unchanged. The mandatory `context` parameter is left entirely to the schema.

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

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

States a specific verb and resource: 'Add an alias email address to a teammate.' The alias framing distinguishes it from create_teammate (which adds a teammate) and update_email (which mutates an existing address), so the agent can route without opening schemas.

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

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

Explicitly states the when-not condition: only usable when the workspace manages its own team list, and that a directory integration (Google, Microsoft, Zoho Mail) yields a 409. It does not name the alternative path (e.g. sync_teammates or list_integrations) for directory-driven workspaces, which is the only gap.

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 write and open-world annotations, it discloses the company lookup from the user's email domain, the data collected, template generation, DRAFT persistence, and the rendered result for review. "Never publishes" and the approval condition clarify that invocation does not make the signature live.

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

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

The purpose is front-loaded, and the following sentences efficiently cover timing and publication safety. The long parenthetical inventory makes the opening sentence dense, but its details are relevant and there is no repetitive 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 two-parameter creation tool with complete input and output schemas, the description supplies the essential operational context: brand-data provenance, draft creation, rendered preview, workflow position, and approval boundary. The existing-signature exception is covered by create_another, and no additional return-value explanation is necessary.

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

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

Schema description coverage is 100%, and both context and create_another are thoroughly documented there, making 3 the appropriate baseline. The description explains the implicit brand-data source but adds no direct guidance about either explicit parameter, including create_another's override-versus-report behavior.

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

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

The opening identifies a specific operation and resource: starting a workspace's first email signature using brand-derived web-onboarding behavior. References to create_scribe_account and publish_signature also place it clearly within the signature workflow rather than leaving it interchangeable with other signature tools.

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

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

It gives explicit invocation points: immediately after create_scribe_account or when a workspace has no signature yet. It also establishes an approval gate and directs publishing to publish_signature, while the schema documents the exceptional create_another case.

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

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

Annotations declare write, non-idempotent, non-destructive, open-world, and the description corroborates and enriches this: it discloses the required folders:write scope, the 422 on a blank name, that duplicate names are permitted (explaining non-idempotency), that nothing is filed by the call itself, and the returned signature_count of 0. This is well beyond what annotations convey.

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

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

The core purpose leads, followed by the routing rule, the alternative, the follow-up action, the side effects, and the failure mode. Every sentence carries distinct operational information with no filler.

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

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

For a two-parameter write tool with annotations and an output schema, the description covers prerequisites, side effects, error behavior, and cross-tool usage. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: that the name need not be unique (so list_folders should be checked first), that blank returns 422, and how the returned id flows into other tools. It does not add format or length constraints 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?

States a specific verb and resource ('Create a new, empty signature folder') plus a scope qualifier ('top-level, not nested') that separates it from anything else in the sibling list. It explicitly names list_folders and update_folder as the alternatives, so an agent can route without opening schemas.

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

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

Gives an explicit precondition ('use it only when no suitable folder exists: call list_folders first to reuse one') and an explicit alternative with rationale ('use update_folder to rename ... since duplicate names are allowed'). It also notes the follow-up action (pass the returned id as folder_id to create_signature or update_signature), which is when-next guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's added value is what it contributes beyond that: the resulting resource state (draft, not live), the 422 error on missing required fields, and server-side strict validation of the content tree. It does not cover permissions, rate limits, or whether create is safe to retry, so it is strong but not exhaustive.

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

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

Three sentences, front-loaded with the required-field contract and lifecycle note before the content-format detail. Dense and nearly waste-free, though the clause about content block-tree shape partially duplicates the schema's own long description.

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

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

With an output schema present, annotations covering safety, and 91% schema coverage, the description needs only to add lifecycle and validation context, which it does (draft state, 422 behavior, strict server-side validation, get_content_schema pointer via the schema). Minor gaps remain around whether send_email or behaviour change the creation semantics, but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 91% and the schema already explains content, smart_fields_conditions, signature_template_ids, and required fields in detail, so the baseline is 3. The description's only genuinely new parameter information is the cross-reference that content uses the same format as signature draft_content; the rest restates required fields and targeting parameters already documented.

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 ("Create a marketing campaign") and immediately disambiguates from the sibling that activates campaigns by naming schedule_marketing_campaign. An agent can tell this apart from update_marketing_campaign, preview_marketing_campaign, and schedule_marketing_campaign without inspecting schemas.

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

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

Explicitly states the lifecycle position: the campaign is created as a draft and schedule_marketing_campaign must be used to activate it, which is the key routing decision for this tool family. It does not mention preview_marketing_campaign or when to prefer update_marketing_campaign instead, so it stops short of full when/when-not coverage.

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

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

Annotations only declare the generic safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the description carries the real burden and does: it discloses the 14-day free trial workspace creation, the company-address constraint on the sign-in email, and the concrete failure consequence of getting it wrong — 'a second, empty workspace'. That is exactly the risk context an agent needs before a non-idempotent write.

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

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

Front-loads the action and scope, then presents the preconditions as a numbered list, so the length is justified by genuine consent requirements. The parenthetical '(other Scribe tools say so)' is slightly oblique and the block could be lightly trimmed, keeping it off a 5.

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

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

For a non-idempotent, open-world account-creation write with an output schema already covering return values, the description covers purpose, consent prerequisites, side-effect risk, and eligibility constraints. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by tying accept_terms to the consent evidence ('Pass accept_terms: true only then'), which tells the agent the gating semantics rather than just the type. It says nothing extra about time_zone or context beyond the schema, so it stops short of a 5.

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

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

States a specific verb and resource ('Create the Scribe account of the person signed in to this connector') plus the scope condition ('when they have none yet'), which distinguishes it from every other create_* sibling. An agent knows exactly what this tool produces without opening the schema.

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

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

Gives an explicit three-part precondition list (user denies having an account, terms and privacy policy were shown, explicit agreement) and names the alternative path for users who already have an account ('reconnect with their Scribe email instead'). Both when-to-use and when-not-to-use are covered.

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=false, and destructiveHint=false, so the write/non-idempotent profile is structured. The description nevertheless adds real value beyond that: strict server-side validation returning 422 with offending fields and allowed enum values, and the lowercase-UUID/pixel-units constraints. These are useful but framed as parameter rules rather than additional behavioral traits like permissions or side effects.

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

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

Front-loads the create action and the draft-vs-published distinction, then builds prerequisites. It is dense and slightly run-on with em-dash nesting, but nearly every clause carries actionable information (state effect, schema-first pointer, 422 behavior, id/unit rules).

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

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

Given 6 parameters, nested block-tree complexity, and annotations plus an output schema, the description supplies the workflow ordering, validation behavior, unit/id constraints, and return note. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3, and the description still adds meaning: `name` required, `draft_content` is a strict-validated block tree, `folder_id` is a folder UUID. It goes further with unit semantics (pixels not multipliers, lineHeight example) and lowercase-UUID id stability, exceeding what the schema alone conveys.

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 ('Create a signature template') and immediately clarifies the state effect: sets `draft_content` while `content` stays empty until publish_signature. This cleanly distinguishes it from create_first_signature, update_signature, and publish_signature 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?

Explicitly instructs to 'Call `get_content_schema` FIRST' and explains why (full schema, enum values, worked example), plus names publish_signature as the follow-on action. The when-to-use and prerequisite ordering is fully 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 it is a non-destructive, non-idempotent write, but the description adds substantially more: required smart_fields:write scope, the exact 422 failure modes (taken label, invalid kind, unknown or unsuitable integration), the fact that creation has no effect on any signature until a template references it, and that it writes exactly one field and returns it.

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

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

Purpose and the list_smart_fields/update_smart_field routing are front-loaded, followed by the manual-vs-bound behavior split and then side effects and errors. Every sentence carries distinct operational information; there is no filler or repetition of 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 6-parameter mutation tool with an output schema, this covers purpose, prerequisites, alternatives, behavioral branching (manual vs. integration-bound), authorization scope, and error conditions. Return values are handled by the output schema, so nothing an agent needs is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds design-level semantics the schema only hints at: manual vs. integration-bound fields, the coupling of integration_id with integration_attribute, and the caveat that integrations do not fill url fields so they must stay manual. It does not cover the required/default behavior of kind or required, though the schema does.

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 ("Define a new custom smart field") and immediately explains what the resource is — a merge field usable by signature templates and campaign conditions. An agent can distinguish it from update_smart_field, delete_smart_field, and list_smart_fields without opening a schema.

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

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

Gives explicit when-to-use (check list_smart_fields first because labels are unique), explicit when-not ("to rename, retype or rebind an existing field use update_smart_field instead"), and names the concrete alternative. It also routes follow-up work to update_teammate for setting values.

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 the write/non-destructive/non-idempotent profile, and the description adds real behavioral detail beyond that: the 409 conflict for directory-driven workspaces, that integration-synced and image fields are silently ignored, and that an unknown smart_field_id or type-invalid value fails the entire create atomically. These are exactly the failure-mode facts an agent cannot get from the annotations.

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

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

Three tight sentences, front-loaded with the create action and inputs, then the precondition, then the alias caveat. No restatement of the tool name or 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 an output schema present and 100% schema coverage, the description's remaining job is preconditions and failure behavior, and it covers both (409 on directory-driven workspaces, atomic failure on bad smart-field input). Nothing material an agent needs before calling is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by clarifying that 'email' is the primary address (aliases handled elsewhere) and that smart_fields is an optional initial-value set whose bad entries abort the whole call. It does not add syntax detail beyond the schema, so 4 rather than 5.

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

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

States a specific verb and resource ('Create a new teammate') plus the input shape ('from a primary email plus optional smart-field values'), which cleanly separates it from list_teammates, update_teammate, delete_teammate and sync_teammates in the sibling set. The availability precondition is stated in the same breath, so the agent knows this is the manual-creation path rather than the directory-sync path.

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

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

Gives an explicit when-not condition: if a directory integration (Google, Microsoft, Zoho Mail) drives teammates, this returns 409, so the agent should not call it in that workspace. It also flags that email aliases are managed separately, steering the agent away from expecting alias behavior here. It stops short of naming the alternative tool (e.g. sync_teammates) by name, which keeps it at 4 rather than 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 declare the safety profile (destructiveHint=true, idempotentHint=true), but the description adds genuinely new context: it explains the conditional soft-delete vs permanent-removal logic, why references preserve the asset ('so those keep rendering'), and that the asset vanishes from list_assets either way. This is exactly the kind of consequence detail an agent needs before calling 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?

Two sentences, zero filler, and the payload (what happens on delete) is front-loaded right after the verb. Every clause carries distinct information.

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

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

With an output schema present, return values need not be described, and the annotations already cover idempotency and destructiveness. The description closes the remaining gap by explaining the soft/hard delete outcome, making the definition complete for a destructive tool.

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

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

Schema coverage is 100% and the schema already documents the `id` parameter as the UUID returned by list_assets, plus the full `context` contract. The description's 'by UUID' repeats what the schema provides without adding syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete an asset by UUID'), immediately distinguishing it from the many other delete_* siblings. The behavior it describes is uniquely scoped to assets, so an agent can select it without 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?

Usage is implied by the tool's nature (delete a specific asset) and it points to list_assets as the source of the UUID, but there is no explicit when-to-use/when-not guidance or mention of alternatives such as update_asset when the goal is modification rather than removal.

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/idempotent/openWorld, but the description adds substantive behavior the annotations cannot express: the delete is soft rather than permanent, teammate primary emails are rejected with 422, and managed-directory workspaces conflict with 409. These are exactly the side effects and auth/ownership constraints 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?

Three short sentences, front-loaded with the action and its soft-delete nature, followed by two error-condition clauses. No filler, no restatement of the title, and each sentence carries distinct operational information.

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

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

For a destructive two-parameter tool with an output schema and rich annotations, this covers action, semantics, and the two most likely failure modes. It omits whether the soft-deleted alias can be restored or what happens to signature installations referencing it, which is the only meaningful 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 description coverage is 100% — the `id` parameter is already documented as "the UUID returned by list_emails" and `context` is fully specified. The description's "by UUID" adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a precise verb+resource ("Delete an alias email by UUID") and immediately narrows scope with "(soft delete)", which separates it from sibling delete_* tools operating on assets, folders, signatures, smart fields, and teammates. The qualifier "alias email" also distinguishes it from delete_teammate and update_email.

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 and failure conditions: primary emails return 422, and workspaces using a directory integration return 409. That tells the agent when the call is invalid, but it never names the alternative action for those cases (e.g., remove/update the address instead of deleting), so it stops just short of explicit 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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond the annotations: the 409 error condition and the empty-folder requirement, which the agent cannot infer from the schema.

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

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

Two sentences, no filler, with the core action and the blocking precondition front-loaded. Every clause carries operational value.

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 tool with full annotation coverage, a 100% documented schema, and an output schema handling return values, the description supplies the one missing piece an agent needs: the precondition that would cause the call to fail.

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 both parameters are already documented, including the requirement that id is 'the id returned by list_folders'. The description only restates 'by UUID' and says nothing extra about the analytics-only context parameter, 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?

States a specific verb and resource ('Delete a signature folder by UUID'), which cleanly separates it from update_folder, list_folders, and the other delete_* siblings that target different resources. An agent can identify the operation without opening the schema.

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

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

Gives a clear precondition and failure mode: a folder containing signatures cannot be deleted (409), and the agent is told to move or delete the signatures first. It stops short of naming the sibling tools to perform that remediation, so it is clear context rather than full when/when-not 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 declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds real value beyond that by disclosing the cascade: an active campaign is stopped first, ceases applying to signatures, and is then removed. It stops short of stating irreversibility or any required permissions/scope.

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

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

Two short sentences with zero filler, and the identifying detail (UUID) plus the lifecycle behavior are front-loaded. Nothing could be cut without losing information.

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

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

For a destructive two-parameter tool with an output schema, the safety hints, the parameter documentation, and the cascade behavior are all covered. The only meaningful omission is an explicit statement about irreversibility or recovery, which matters for a delete.

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 both `id` and `context` are already fully documented, including the pointer to list_marketing_campaigns for obtaining the UUID. The description's "by UUID" restates the schema rather than extending it, so the baseline 3 applies.

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

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

States a specific verb and resource ("Delete a marketing campaign") and pins the identifier form ("by UUID"), which separates it cleanly from sibling mutations like update_marketing_campaign, pause_marketing_campaign, and resume_marketing_campaign. An agent can select it without opening the schema.

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

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

The description implies the destructive use case but never states when to choose this over pause_marketing_campaign or update_marketing_campaign, nor does it warn that the operation is permanent. Usage is inferable from the verb alone, which is the minimum-viable bar.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it enumerates the cascade (recipient assignment, marketing-campaign targeting, installation records), clarifies what does NOT happen ('Scribe does not push an uninstall to mailboxes it was already installed in'), states the required scope, and predicts the 404 on an unknown id.

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 most consequential fact (permanent, no undo or trash) is front-loaded in the first clause, followed by cascade details and then routing alternatives. Every sentence carries distinct information with no filler, appropriate length for a destructive cascade operation.

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 an output schema present, return values need not be explained; the description still covers the operation's permanence, side effects, scope requirement, failure mode, and tool-selection boundaries. Nothing an agent needs to invoke this 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?

Schema description coverage is 100% and both parameters are fully documented in the schema, including the 'only primary templates can be deleted' caveat and the context-writing rules. The description's 'by UUID' and 404 note largely restate the schema, so it adds marginal value here — baseline 3.

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

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

States a specific verb and resource ('Permanently delete a signature template by UUID') and immediately distinguishes itself from sibling deletion tools like delete_signature_variant. An agent can identify exactly what this deletes and how it differs from remove_signature_recipients without opening any schema.

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

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

Explicitly conditions use: 'Use it only when the template itself should go', then routes to the correct alternatives with their own conditions — remove_signature_recipients/remove_signature_recipient_entities for narrowing reach, delete_signature_variant for resetting a single variant. When-not guidance and named alternatives are both present.

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 (destructiveHint=true, idempotentHint=true), the description discloses the actual side effects an agent cannot infer: the variant is deactivated rather than removed, the primary's content is restored, the variant record is retained, and a 409 variants_unavailable error is returned when the workspace lacks the M365 integration. This is exactly the extra behavioral context annotations cannot carry.

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

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

Two sentences, front-loaded with the core action and its most important semantic distinction ('reset to primary, not a hard delete'), followed by the failure condition. No filler sentences.

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

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

An output schema exists, so return values need no explanation, and the description still covers the mutation's semantics, the retention of the variant record, and the error case. For a 3-parameter mutation tool this is complete enough to invoke 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 description coverage is 100% and all three required parameters are documented there. The description restates the variant kinds ('reply/internal') but adds no syntax, format, or edge-case detail beyond the schema; the baseline 3 applies when structured fields do the heavy lifting.

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 precise verb and resource (reset a signature's reply/internal variant to the primary) and immediately clarifies the operation's nature versus what the name implies — explicitly 'not a hard delete'. This lets an agent distinguish it from delete_signature, update_signature_variant, and publish_signature_variant without opening any schema.

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

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

Gives clear context for when to call it (the 'reset to primary' action) and names the error condition that blocks it (409 / variants_unavailable without a Microsoft 365 signatures integration). It does not, however, explicitly name the alternative tools (update_signature_variant, delete_signature) or state when-not to use it, so the routing guidance is contextual rather than exhaustive.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds materially more: deletion cascades to remove the field's value on every teammate, plus three concrete failure modes with HTTP codes. That is exactly the 'what gets destroyed and when it won't work' context the annotation cannot carry.

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

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

A single dense sentence with the verb and destruction scope front-loaded, followed by the failure cases. No filler, no restatement of the title, and every clause carries operational information.

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

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

For a destructive mutation with an output schema present and full annotation coverage, the description supplies the cascade semantics, addressing requirements, and complete error preamble. Nothing an agent needs before invoking it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond the schema's 'id returned by list_smart_fields' by constraining which IDs are valid targets (custom fields only, not default or computed fields). It does not add anything further about the analytics-only context parameter, which is already fully documented.

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 ('Delete a custom smart field') with the addressing key (UUID) and immediately distinguishes it from sibling operations by noting it is a custom field. It also names what makes a field non-custom, so an agent knows update_smart_field/list_smart_fields are not substitutes.

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 enumerates the when-not conditions with status codes: default fields (422), computed Email field (404), fields in use by a signature template or campaign (409). These effectively tell an agent when the call will fail, though no alternative tool (e.g., update_smart_field) is named as a fallback.

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

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

Adds substantial context beyond annotations: it discloses the soft-delete semantics (not a hard delete), the cascade effect on signature deployment, and the 409 conflict condition tied to directory integrations. Annotations only give generic destructive/idempotent hints; the description supplies the domain-specific 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 core action and then the critical precondition. No filler; every clause carries operational weight.

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

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

Covers action, scope constraint, side effects, and failure mode. With an output schema present, return values need not be explained, and the description is fully sufficient for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by tying 'UUID' to the id returned by list_teammates, reinforcing correct sourcing of the 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 a specific verb+resource ('Delete a teammate by UUID') and immediately clarifies it is a soft delete with a specific side effect (emails removed from signature deployment), distinguishing it from update_teammate and delete_* 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?

Explicitly states the precondition for use ('Only available when the workspace manages its own team list') and the failure mode with an alternative-driving integration (directory integration → 409 conflict). This tells the agent both when to use it and when it will fail.

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?

With annotations only flagging it as a non-read-only, non-destructive, non-idempotent open-world write, the description goes well beyond: it discloses what the copy inherits (design drafted into content, reply/internal variants) and what it explicitly does not (no assignee, installation off, no smart-field rules). It also documents failure modes (404 unknown signature, 422 unknown folder) and that it returns the copy.

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

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

Front-loads the core action, then behavior, then workflow guidance — each sentence carries distinct information with no repetition. Dense 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 copy/mutation tool with an output schema present and annotations covering safety, the description supplies everything else an agent needs: inheritance semantics, rollback path, and error codes. Nothing material is missing.

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

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

Schema coverage is 100%, so id, name, folder_id, and context are already documented in the schema. The description's mention of 'assigned to no one' and inherited content is behavioral rather than parameter-level, and it adds no enum, format, or default detail beyond the schema's own '<name> (Copy)' and folder-inheritance defaults. Baseline 3 fits when the schema carries parameter semantics.

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

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

States a specific verb and resource ('Copy a signature into a new one') and immediately anchors the mental model to the dashboard's Duplicate, distinguishing it from create_signature. An agent can tell exactly what operation this is without further reading.

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

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

Explicitly says to use this 'instead of reading the design and create_signature', then lays out the follow-on workflow (edit with update_signature, verify with preview_signature, and roll back by updating the original with the copy's draft_content). This gives when-to-use and named alternatives, not just implied context.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description adds real context on defaults (2 months ago → today, UTC), the mutually exclusive timeseries vs. breakdown behavior, and that breakdown rows carry views, clicks, and CTR together. That last point (one call answers the engagement question) is genuine behavioral insight not implied by annotations, though some response-shape detail duplicates the output schema.

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

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

Well front-loaded: default behavior first, alternative mode second, filters last. It is dense with inline JSON response sketches that make sentences long, but every sentence carries routing or format information rather than 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 analytics tool with an output schema, the description covers both modes, defaults, the UTC basis, and the filter set, which is enough for correct invocation. Minor gaps remain: no mention of pagination behavior in the timeseries mode or the anchor breakdown dimension, both of which are discoverable only from 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 100%, so the baseline is 3. The description explains the semantic interplay of `granularity` vs. `group_by` and the available filters, but it largely restates schema content — and its group_by list ('signature_template | marketing_campaign | teammate | country') silently omits 'anchor', which is in the enum.

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

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

The description states a specific verb+resource ('signature-click counts over a date range') and immediately clarifies the two shapes the result can take, so an agent knows exactly what data comes back. It does not name or differentiate itself from the nearest analytics siblings (get_analytics_views, get_analytics_events_summary), relying on the word 'clicks' to do that work implicitly.

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 in-tool routing: default timeseries vs. `group_by` ranked breakdown, and even frames the breakdown as answering 'which signature/teammate drives the most engagement'. It stops short of saying when to reach for this tool over get_analytics_views or list_analytics_events, so the cross-tool selection guidance is only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety needs no restating. The description adds real behavioral context: the DEFAULT is a timeseries, the shape changes when group_by is set, and value is summed across currencies unless currency is supplied, which is a genuine correctness trap 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?

Front-loaded with the core definition, then response shapes, then the mode switch, then use cases — a sensible ordering with little waste. It is dense and sentence-long, but nearly every clause carries information an agent needs to pick the right mode.

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 16 parameters this could easily be under-specified, but the description covers the two operating modes, defaults, ranking, and the currency pitfall, and an output schema plus full schema descriptions cover return details and the required context parameter. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% with 16 well-described parameters including four enums, so the schema does the heavy lifting; baseline is 3. The description restates group_by/order_by/granularity behavior and the currency summing rule, but mostly mirrors what the schema already says rather than adding new syntax or edge-case 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?

"Aggregated conversion/revenue numbers from recorded events" states a specific verb-equivalent and resource, and the mention of timeseries vs ranked breakdown makes the output contract clear. It does not explicitly name the sibling tools it is not (get_analytics_clicks, get_analytics_views, list_analytics_events), so an agent must infer the boundary from the word "events" alone.

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 closing sentence enumerates concrete use cases — total revenue, revenue by campaign/template/teammate/country, conversions per day, top customers — which gives a strong positive signal for when to call it. There is no explicit exclusion or named alternative for the cases where this is the wrong tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real operational context: default bucketing, hour granularity capped at 31 days, and the shape of both response modes including pagination on breakdowns. One gap: it lists group_by as 'signature_template | marketing_campaign | teammate | country' while the schema also allows 'anchor', an omission that could mislead an agent.

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

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

Front-loaded with the core purpose, then the default behavior, then the alternative. Every clause carries information — response shape, mode switch, filters — with no filler, despite being longer than typical.

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 analytics tool with full schema coverage and an output schema, this description supplies the mode-selection logic, defaults, and the payoff of each mode. The single shortfall, the missing 'anchor' enum value in the group_by list, is corrected by the schema itself.

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 by explaining the causal relationship between group_by and the output shape and by enumerating the three ID filters together. It synthesizes how parameters interact ('granularity ignored when group_by is set') rather than merely restating field docs.

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+scope: 'Signature-view counts over a date range', with the two operating modes (timeseries vs. group_by breakdown) made explicit. It never names the adjacent analytics siblings (get_analytics_clicks, get_analytics_events_summary, list_analytics_events), so the boundary with those tools is left to inference.

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

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

Clear routing between the default timeseries and the group_by breakdown, plus the concrete question the breakdown answers ('which signature/teammate drives the most engagement') and the available filters. It gives context for when each mode applies but offers no exclusions against competing analytics 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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds non-annotation behavior: the prerequisite ordering, that everything arrives in ONE call, and that it removes the need to brute-force enum spellings. It does not mention auth or rate limits, but for a schema-fetch tool that is minor.

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

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

Front-loaded with the imperative 'Call this FIRST', which is exactly what an agent needs to see first. It is dense but the parenthetical icon enumerations (linkedin -> linkedin-in, etc.) are repetitive; a couple of examples would have carried the same signal with less bulk.

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?

An output schema exists, so return-value structure need not be re-explained, and the description still gives the shape of what comes back (schema + enums + example + guidance). Together with annotations this is fully sufficient for an agent to call the tool correctly and know why.

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

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

There is a single parameter (context) with 100% schema description coverage, so the schema already explains its purpose and constraints. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

The description names a specific verb+resource (returns the content schema needed to build a valid block tree) and enumerates exactly what is returned: strict JSON Schema, enums lookup, social_icons map, worked example, and guidance. It is unmistakably distinct from siblings like get_signature_html or preview_signature.

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 call-order rule ('Call this FIRST before authoring or editing') and names the exact downstream tools it enables: create_signature / update_signature drafts and marketing-campaign content. When-to-use is spelled out rather than inferred.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral context such as what 'check' entails, whether it makes a network call, or what side effects (if any) occur 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?

The description is a single, front-loaded sentence with no wasted words. It quickly communicates the action and the conditions for use, making it efficient and easy to parse, though it could be slightly more structured with a separate usage note.

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

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

The description gives clear usage guidance but does not explain what the tool returns or what happens after 'checking' for tools. With no output schema present, the description carries the burden of explaining the result, which it fails to do. For a simple one-parameter tool, this is a notable gap, though not severe.

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 'context' is already documented with a clear description in the schema. The tool description adds no additional semantic meaning beyond what the schema provides, which aligns with the baseline of 3.

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

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

The description clearly states the tool's function: checking for additional tools when a task could benefit from specialized capabilities. It distinguishes itself from the sibling clipform_* tools by being a meta-tool for tool discovery rather than a domain-specific operation, though it does not explicitly name this distinction.

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

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

The description provides explicit usage guidance: use this tool whenever specialized capabilities might help, even if existing tools could work as a fallback. This gives the agent a clear decision rule, though it does not mention when not to use it or list alternative 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior beyond them: it returns empty HTML for unpublished signatures, and returns 404 (no such email) versus 422 (not a recipient) for ineligible recipients. These failure modes and lifecycle constraints are exactly the kind of context annotations cannot express.

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

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

Front-loaded with the core action before the caveats, and every sentence carries distinct information (non-preview, publish prerequisite, empty-HTML case, error codes, alternative tool). The heavy ALL-CAPS emphasis and stacked parenthetical references make it denser than it needs to be, but 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?

An output schema exists, so return-value documentation is not the description's job, and the description still covers prerequisites, eligibility, error behavior and the alternative tool. For a 3-parameter read tool with full schema coverage and annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, and the schema already documents id, email_id and context. The description adds meaning by tying email_id to a recipient-membership requirement and its error consequences, which goes beyond the schema's 'UUID of a recipient email'. It does not add format or syntax detail beyond that, so a 4 rather than a 5.

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

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

States a specific verb and resource ('get the REAL final installed HTML of a signature for a SPECIFIC recipient') and immediately scopes it as live published content rendered with the teammate's real values. It explicitly distinguishes itself from the nearest sibling by declaring 'This is NOT a preview' and naming preview_signature. An agent can differentiate it from preview_signature and list_signature_installations without opening a schema.

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

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

Gives an explicit prerequisite (publish_signature must run first), an eligibility constraint (the email must be a recipient — see list_signature_recipients), and a named alternative with the condition that selects it ('For a tracking-free placeholder layout check of a draft before publishing, use preview_signature instead'). When-to-use, when-not-to-use and the alternative are all covered.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations by noting that traits contain PII and by explaining first_touch attribution and lifetime engagement stats. It does not discuss auth needs or rate limits, but for a read-only lookup the added disclosure is meaningful.

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

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

The key purpose is front-loaded, and the description is compact overall. It is a single dense sentence with nested parentheticals, and some return-field detail overlaps with the output schema, but every clause still provides useful orientation rather than 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 two-parameter read-only lookup with full schema coverage, annotations, and an output schema, the description covers the necessary conceptual context: what is fetched, what identifier to use, what identifier not to use, and the main returned data categories. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, and the schema already documents both `id` and `context` in detail. The description reinforces the critical `id` versus `distinct_id` distinction, but largely repeats what the schema says and does not add further meaning for `context`. With full schema coverage, the baseline of 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 states a specific verb and resource: fetch one identified visitor by its Scribe `id`. It immediately distinguishes this from a Scribe member and from a distinct_id lookup, and it names `list_visitors` as the source of the id. An agent can tell exactly what this tool returns and how it differs from related list/breakdown tools.

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

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

It explicitly says to use this tool for a single identified visitor by Scribe `id`, and explicitly redirects distinct_id lookups to `list_visitors` instead. The `id` source is also stated as coming from `list_visitors`, leaving little inference required.

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/openWorld, so the safety profile is covered. The description adds the attribution semantics and sketches the return payload, but says nothing about the aggregation time window, which is the main behavioral unknown an agent would have for an analytics call.

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

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

A single front-loaded sentence that leads with the ranking verb and the acquisition metric. The trailing {data:[...], pagination} sketch is mildly redundant given an output schema exists, but it is compact and not a distraction.

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 a full output schema and fully described parameters, the description only needs to supply the metric definition, which it does. The one meaningful omission is the time period the breakdown covers – an agent cannot tell whether it is all-time or a default window.

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 page/limit/context/group_by are all documented in the schema, so parameter semantics are largely handled there. The description only restates the group_by dimension ('signature template or teammate') without adding format or default 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?

Names a specific verb (rank) and resource (identified visitors acquired by signature template or teammate) and defines the attribution rule behind it. An agent can distinguish it from list_visitors or get_analytics_views, though it never explicitly points at 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?

The definition of first-touch ('first signature click that drove their first visit') implies the intended question – which template or teammate drives acquisition – but there is no explicit when-to-use, exclusion, or named alternative among get_analytics_clicks, get_analytics_views, or list_visitors.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description reinforces with 'Read-only' plus the valuable constraint that plan and seats cannot be mutated through the API at all. It also notes events-tracking tells whether events 'would be ingested,' a behavioral nuance not in annotations, though it does not discuss cost, rate limits, or staleness of the snapshot.

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

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

Front-loaded with the resource and its components, then the workflow hint, then the scope/read-only caveats. The parenthetical enumeration of plan fields partially duplicates the output schema, which is mild redundancy but keeps the description skimmable.

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?

Given an output schema already defines return values, the description adds the missing pieces an agent needs: scope (API key's own workspace), mutation limits, and the conversion-tracking follow-up path via search_docs. Nothing required to call it correctly is absent.

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 single 'context' parameter is already documented and the description needn't repeat it. It does add meaning by clarifying that no identifier parameter exists — the workspace is implied by the API key — which prevents an agent from searching the schema for an id field.

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

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

States a specific verb+resource ('snapshot of the current workspace's commercial state') and enumerates the three returned components (plan, seat_count, event_tracking). It also disambiguates scope explicitly: 'There is no id — it is always the API key's own workspace,' which no sibling tool claims.

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

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

Gives an explicit when-to-use trigger ('When helping a user set up conversion tracking, read the ID here and search_docs for conversion tracking') and names the follow-on sibling tool. It also states a when-not: plan and seats are managed in the dashboard / billing system, never via the API.

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 that installation targets connected mail clients, does not publish the signature, applies to every assigned email, and can fail with 403 or 409 when plan or integration requirements are missing. It also explains that error responses include a dashboard link and must be relayed to the user because the API cannot run OAuth.

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 main action and its scope are front-loaded, followed by the alternative tool and then necessary error-handling guidance. The description is dense and every sentence contributes operationally useful information.

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

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

The tool mutates external mail-client state, so the description appropriately covers scope, non-publishing behavior, and common failure modes. An output schema exists, annotations cover safety traits, and the description adds the contextual details an agent needs to invoke and handle errors 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 100%, and both parameters are fully documented in the input schema. The description does not add parameter-specific semantics beyond the schema, so the baseline score of 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 states a specific verb and resource: triggering installation of a signature template's current content to connected mail clients. It clearly scopes the operation to every assigned email and distinguishes it from install_signature_for_email for single-email installation.

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

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

It explicitly names the alternative for installing on one email alone and describes the conditions under which this all-email installation applies. The 403/409 error guidance further clarifies operational prerequisites.

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

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

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true) by disclosing asynchronous execution ('runs in the background', result lists what was queued), the polling path via list_signature_installations, and the full error contract: 403 plan limitation, 409 installed_by_client, 409 no_signature_to_install, 409 installation_unavailable, 422 not_a_recipient. It also tells the agent what to say to the user in the installed_by_client case, which is behavior no structured field conveys.

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

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

Dense and front-loaded, with the scope constraint and the sibling contrast in the first clause. The parenthetical example list and the long error-code enumeration make it a single run-on sentence that is heavier than it needs to be, though almost every clause carries actionable content.

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

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

For a mutation tool with an output schema, an agent has everything it needs: scope, async model, follow-up polling tool, tier/setup prerequisites, and every documented failure mode with the required user-facing response. Nothing material is left unspecified.

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 email_id and signature_id are already fully documented in the schema, including the 'without it, every installed signature' default. The description restates 'or only signature_id' without adding format, validation, or sourcing detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('install one email's signatures') plus the crucial scope constraint: 'in its mailbox alone, without reinstalling the signature for everyone else'. It explicitly names the sibling install_signature as the contrasting tool, so an agent can route between them without opening either schema.

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

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

Gives concrete triggering scenarios ('a send-as alias that needs its signature, one person whose details changed') and explicitly distinguishes this from install_signature (workspace-wide). The alternative and the condition that selects it are both stated, not inferred.

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

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

Annotations already declare readOnly/destructive/idempotent, but the description adds material context beyond them: async ingestion means recent events may be missing, it requires the analytics:read scope and an event-tracking plan (403 otherwise), and it documents pagination behavior including auto_paginate/max_pages and the `truncated: true` overflow signal.

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

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

Dense but front-loaded: purpose and return shape first, then use cases, then sibling routing, then caveats (async, auth/plan, pagination). Every sentence carries distinct information; nothing is redundant padding despite the length.

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

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

Covers everything an agent needs: what is returned, ordering, ingestion lag, permission/plan failure mode, and pagination semantics including the truncation signal. With an output schema present, return-value details need not be repeated, and the description still tells the agent enough to call and interpret results 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 100%, so the schema already documents every parameter and baseline is 3. The description adds value by explaining the interaction of the pagination params (one page default 50/max 100; auto_paginate fetches up to max_pages) and by framing distinct_id in terms of the list_visitors workflow, which is more than the schema states.

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?

Starts with a specific verb and resource ('List the raw conversion events recorded for the workspace') and immediately states scope and ordering ('most recent first, one row per event'). It also names the data sources (website SDK, server-to-server) which disambiguates it from the summary/view/click 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 three concrete use cases (verify tracking, read one visitor's history via distinct_id, export rows) and then explicitly routes alternative needs: get_analytics_events_summary for counts/revenue/rankings, get_analytics_views/clicks for signature views and clicks, list_visitors for profiles. Explicit when-to-use and when-to-use-something-else.

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

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

Beyond the readOnlyHint/idempotentHint annotations it discloses deleted assets are excluded, there is no role filter so you must page and match manually, a required `assets:read` scope, paging defaults and caps, and that `truncated: true` means more remain. It also explains why `in_use` matters: delete_asset only soft-deletes an asset in use.

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

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

Front-loaded with the resource and ordering, then usage, then pagination mechanics; no filler sentences. It is dense and slightly long, but each clause carries operational information an agent would otherwise have to guess.

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

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

Covers what an agent needs to call and interpret it: return fields (id, file, role, in_use, signature_template_count), exclusions, auth scope, and pagination behavior, even though an output schema exists. Nothing material about invoking it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the practical consequence of paginating without a role filter, the default 50/max 100 page size, auto_paginate driving max_pages, and the `truncated` signal. It does not explain `context`, but that parameter is fully self-documenting in the schema.

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

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

States a specific verb and resource ('List the workspace's asset library') plus scope (logos, banners, profile pictures, newest first), which lets an agent separate it from create_asset/update_asset/delete_asset without opening any schema.

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

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

Explicit when-to-use clauses: reuse an image by putting `id` in an image block's `assetUuid` instead of 'uploading a duplicate with create_asset', and find the `id` for update_asset or delete_asset. It also names a concrete alternative path (get_content_schema) and a pre-check ('check `in_use` first'), leaving little to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds beyond them: the required emails:read scope, exclusion of deleted emails and teammates, page-size defaults (50/100), the auto_paginate+max_pages behavior, and the meaning of `truncated: true`.

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

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

Dense but every sentence earns its place: scope/return shape first, then consumer tools, then the alternative, then the no-search constraint, then pagination. 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?

Covers the identity of the resource, filtering limits, pagination semantics, scope/auth, and sibling routing; with an output schema present it correctly avoids re-explaining the raw return payload. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3; the description adds meaning by explaining that filtering is by `teammate_id` only, that paging plus matching `address` is the search substitute, and what `truncated` signals. It stops short of documenting every parameter, so a 4 rather than 5.

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

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

States a specific verb+resource ('List the workspace's teammate email addresses, primary and aliases') and enumerates the returned fields (`id`, `address`, `primary`, `teammate_id`). It explicitly distinguishes itself from the sibling list_teammates and names the downstream tools that consume the returned `id`.

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

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

Provides explicit when-to-use (get the email `id` for add/remove_signature_recipients, update_email, delete_email, etc.), a named alternative with its selection condition (list_teammates when smart-field values are also needed), and a negative constraint ('There is no address search') with a workaround.

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 readOnly/idempotent annotations, it discloses a non-obvious filtering rule (only documents with a downloadable PDF are returned), the exact response shape for `file` and optional `receipt`, and that pagination applies. These details materially change how an agent interprets an empty or partial result set.

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

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

Four tight sentences, front-loaded with scope and ordering, then result shape, then the download instruction. Minor redundancy: 'whose `url` downloads the document' and 'Use the `file.url` to fetch/download the document' say overlapping things.

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 paginated list tool with full schema coverage and an output schema, this covers everything an agent needs: scope, filter behavior, ordering, result shape, and pagination. Nothing material is missing.

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

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

Schema coverage is 100%, so page/limit/auto_paginate/max_pages/context are already documented inline. The description's '(page/limit)' adds nothing beyond the schema and is silent on the auto_paginate/max_pages interaction and the mandatory `context` parameter, 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?

States a specific verb and resource ('List the workspace's financial documents'), narrows the domain to invoices and credit notes, and specifies ordering ('newest first'). No sibling tool covers financial documents, so an agent can route here without 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?

The description tells the agent how to consume results ('Use the `file.url` to fetch/download the document') and closes off a wrong assumption by noting documents are issued by the billing system, not created via the API. It stops short of naming an alternative sibling for related needs, but no such alternative exists in the sibling list.

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 readOnly/idempotent annotations, it discloses the required folders:read scope, the 409 behavior when deleting a folder whose signature_count is above 0, and pagination semantics (default 50, max 100, truncated: true means more remain). These are substantive operational facts the annotations do not cover.

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

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

Dense but front-loaded: purpose and returned fields come first, then usage routing, then exclusions and pagination. Every clause carries actionable information with 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?

An output schema exists, so return-value documentation is not required, and the description still covers scope, exclusions, pagination, failure mode (409), and sibling routing. Nothing needed to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning about the pagination parameters' interplay (auto_paginate up to max_pages, truncated signalling remaining pages) and clarifies what signature_count counts (directly contained templates only). It does not explain the required context parameter, but that is a platform-level field.

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

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

States a specific verb+resource (list the workspace's signature folders), the ordering (newest first), and the exact fields returned (id, name, signature_count). It explicitly distinguishes itself from list_signatures and notes that asset folders are excluded, so an agent can separate it from both neighbors without opening a schema.

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

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

Gives explicit when-to-use routing: find a folder id for update_folder/delete_folder, obtain the folder_id for create_signature/update_signature, and check existence before create_folder. It also states the when-not condition (it does not list signatures inside a folder) and names list_signatures as the alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds that results are paginated and originate from a teammates integration, but says nothing about auto_paginate behavior or result volume beyond what the schema already documents.

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

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

Three short sentences, zero filler, with the core purpose and the downstream handoff front-loaded. Every sentence carries a distinct piece of 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 an output schema and rich annotations present, the description only needs to cover purpose and routing, which it does. The one gap is auto-pagination behavior, which the schema covers but the description never acknowledges.

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 page, limit, max_pages, auto_paginate, and context are fully documented in the schema. The description only repeats '(page/limit)' and adds no semantics for the auto-pagination parameters, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the workspace's directory org units / groups') and identifies the data source ('from a teammates integration'). It also distinguishes itself from siblings that read signatures or integrations by explaining what the returned uuids are for.

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 directs the agent to use the returned uuids with add_signature_recipient_entities to target a whole org unit, which is a clear when-to-use signal. It does not contrast with nearby list tools such as list_teammates or list_integrations, so the routing guidance stops short of full 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?

Beyond the readOnly/idempotent annotations, the description discloses the critical constraint that the API cannot run OAuth, that connection requires a SUPER ADMIN of the third-party app (Admin suffices in Zoho Mail), that only set-up integrations are returned, and that pagination applies. This is material context the annotations cannot convey.

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

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

Front-loaded with purpose and returned fields, then action guidance and routing. It is dense and runs long across several clauses, but each sentence (status/error fields, dashboard_url relay, admin requirement, sibling routing) carries real operational value with little 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?

Although an output schema exists, the description explains the useful return fields (status, error_message, error_since, dashboard_url) and what to do with them, covers the auth/setup constraint, and routes to the correct sibling. Nothing an agent needs to call or act on this correctly is missing.

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

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

Schema description coverage is 100% and already documents page, limit, max_pages, auto_paginate, and the context field. The description's mention of 'paginated (page/limit)' only restates the schema, adding no new semantics — baseline 3 is correct.

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

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

The first sentence states a specific verb and resource with scope: list the workspace's active integrations, including failing ones. It explicitly contrasts with list_signature_installations (per-email install state) and is clearly distinct from list_integration_entities and the many signature/folder 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?

It gives explicit when-to-use guidance plus exclusions: use list_signature_installations for per-email install errors. It also pre-empts the wrong behavior — don't try to connect integrations via the API, guide the user with search_docs and the dashboard_url instead.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds non-obvious behavior: no server-side filtering means the agent must page and scan client-side, one page is returned by default, auto_paginate respects max_pages, and `truncated: true` signals more pages remain. Those are exactly the facts needed to drive a correct loop.

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

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

Three sentences, front-loaded with what is returned, then when to use it, then how pagination behaves. No filler; every clause carries decision-relevant 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 5-parameter read tool with a full output schema, the description supplies the missing pieces — the absence of filters, the pagination contract, and the sibling routing. Nothing an agent needs to invoke it correctly is left 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 100%, so the baseline is 3; the description earns above that by explaining the interaction between `auto_paginate`, `max_pages` and the `truncated` response flag, which the schema does not connect. It stops short of documenting `limit` or `context`, but those are adequately covered 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?

States a specific verb and resource ("List the workspace's marketing campaigns") and immediately disambiguates the term by equating campaigns with signature banners, then enumerates what each record contains (status, schedule, targeting, content block tree). An agent can distinguish it from list_signatures or preview_marketing_campaign without opening any schema.

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

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

Explicitly names the downstream calls that require an id (update_, schedule_, pause_, resume_, delete_, preview_) and states the constraint that forces this tool: "there is no single-campaign get and no server-side filter." It also routes the agent to the alternative when the goal is a rendered banner rather than a block tree.

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 bar is lower, but the description adds real value: it discloses the row shape, the status enum semantics, and the meaning of `error_code` (user_not_found = recipient has no account). It omits pagination behavior, but the schema covers that.

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 the tool returns before the usage guidance, which is the right order. The trailing filter enumeration is somewhat redundant with the schema and could be trimmed, but the rest of the text is dense and waste-free.

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?

Output schema exists and annotations cover safety, so the description needn't explain return values — yet it still describes the row shape and error semantics, which is exactly the extra needed to use the tool correctly. Nothing material is missing.

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

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

Schema coverage is 100%, so all ten parameters are already documented; the description only restates the filterable fields at the end and adds no syntax or behavioral detail beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb and resource ('where each signature actually IS... installed') and nails the result granularity: one row per email × signature × integration, with `status` and `error_code`. This is clearly distinguished from list_integrations by the sibling-scoping 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?

Gives concrete example questions it answers ('is X's signature installed on <integration>?', 'which installs failed and why?') and explicitly contrasts with the alternative: list_integrations only reports workspace-level connection health. The filter list further clarifies the intended query patterns.

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 bar is lower, yet the description still adds useful behavior: `data` is paginated while `selection` returns the complete rule config unpaginated, and it enumerates the `sources` values (manual, smart_field, org unit). It stops short of explaining default page size or the auto_paginate interaction, which the schema covers.

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

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

Front-loads the blocking requirement in the first clause, then describes the return shape, with no filler sentences. Dense em-dash construction makes it slightly harder to scan 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?

An output schema exists, so the description need not explain return values, yet it usefully summarizes them. With annotations covering the safety profile and the schema covering pagination knobs, the only minor omission is edge behavior (e.g. a signature with zero recipients).

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 baseline is 3, but the description earns a bump by clarifying the pagination scoping: page/limit apply to `data` only, not to the `selection` object. It also restates the origin of `signature_id`, which duplicates the schema rather than extending it.

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 ('list the emails a signature is assigned to') and names exactly what the response contains (emails with `sources`, plus `selection` rule config). It also forecloses confusion with a sibling by declaring there is no workspace-wide variant, so an agent can tell it apart from list_signatures and list_signature_installations.

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 states the prerequisite (`signature_id`) and gives a concrete fallback: call list_signatures first and pass an `id` from it. That is real routing guidance, but it does not address closely related write operations (add/remove_signature_recipients, set_signature_recipient_rules) that an agent might confuse this read with.

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 free. The description adds genuinely useful non-annotation behavior: large content trees are stripped by default to save tokens and has_content/has_draft_content still report existence. It also flags the v1 scope limit, but says nothing about the openWorld/workspace-scoping implication of 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?

Four sentences, each doing distinct work: definition, domain disambiguation, pagination scope, and the token-saving default. The most decision-relevant constraint (content omitted by default) is stated before the call and nothing is repeated from the schema verbatim.

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 an output schema present, return values need no prose, and the description covers scope, pagination, and the content-omission default. The remaining gap is routing among the many neighbor list_* tools (variants, recipients, installations) and the required context parameter, both of which an agent must reason about unaided.

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, and the description earns an extra point by explaining the tradeoff behind include_content (token cost vs. full block trees) and by surfacing page/limit pagination semantics. auto_paginate and max_pages are left entirely to the schema, and the required context parameter is unmentioned.

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 ("List the workspace's email-signature templates") and disambiguates the overloaded term "signature" as a reusable deployment template, which distinguishes it from email/asset concepts. It does not explicitly name the near siblings (list_signature_variants, get_signature_html), so an agent still has to infer which signature-* list to pick.

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 conditional: content blocks are omitted by default, and you should pass include_content:true to fetch them, with has_content flags left as a cheap alternative. Pagination behavior is also stated. It stops short of naming alternatives for scenario-based routing (e.g. variants vs primary templates), so it is clear context rather than 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds real value beyond that: the guaranteed presence of both variant entries, the per-entry state fields (exists / activated / hidden / show_marketing_campaigns), and the `supported` flag with the 409 variants_unavailable error that downstream writes will hit.

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

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

Three sentences, each carrying distinct information: what is listed, what a variant is, and what each entry plus the `supported` gate reports. Scope constraint is front-loaded and there is no restatement of the tool name.

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 an output schema present and full annotation coverage, the description only needs to cover behavior the structured fields can't express — and it does, via the guaranteed dual entries and the `supported`/409 gating. Minor gap: it doesn't relate itself explicitly to update_signature_variant or publish_signature_variant, which are the obvious next calls when `supported` is true.

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%, with signature_id documented as the primary signature's UUID from list_signatures and context documented as an analytics-only field. The description adds no additional parameter meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource (list a signature's reply and internal variants) and immediately defines what a 'variant' is in this product's terms. It also clarifies scope ('always both entries'), which distinguishes it from list_signatures and from the get/preview siblings without requiring the schema to be opened.

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 final sentence gives actionable gating guidance: variants require an active Microsoft 365 signatures integration and the returned `supported` flag determines whether write operations are viable. It does not explicitly name the alternative read tools (list_signatures, preview_signature) or state when not to call it, so it falls short of full when/when-not 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds substantive context beyond that: each item carries `kind`, a `default` flag, and an `integration_id` when synced, plus the notable exclusion that the computed Email field is not exposed — exactly the kind of scope caveat an agent cannot infer from annotations.

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

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

Two tight sentences, front-loaded with the identity of the resource, followed by the useful exclusions. The trailing "Paginated (page/limit)" is redundant with a 100%-covered schema, a minor wasted 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 an output schema present and full schema coverage, the description only needs to frame scope and semantics, which it does well (what a smart field is, what fields come back, what is excluded). It stops short of noting auto_paginate's role or any ordering of results, but nothing critical to a correct call is missing.

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

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

Schema description coverage is 100%, so page, limit, auto_paginate and max_pages are already fully documented, and the description's "Paginated (page/limit)" merely repeats that. No added meaning about parameter behavior is provided, so the baseline 3 applies.

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

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

States a specific verb and resource ("List the workspace's smart-field definitions") and immediately glosses the concept as "the merge fields available to signature templates," which an agent can act on without opening the schema. It is clearly distinguishable from the create/update/delete_smart_field 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?

Usage is implied — an agent would call this to discover available merge fields before creating or previewing a signature — but the description never states when to use this versus alternatives such as create_smart_field or the integration listing tools. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds useful domain context about what a teammate carries (email addresses, smart-field values) and notes pagination, but says nothing about auto_paginate behavior or result ordering beyond what the schema states.

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

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

Three short sentences, front-loaded with the action, and the teammate definition earns its place by disambiguating the domain object. The trailing 'Paginated (page/limit)' slightly duplicates the schema but is brief.

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?

Safe for a read-only list tool: the output schema covers return shape, annotations cover safety, the schema documents all parameters, and the description supplies the one thing neither does – the meaning of 'teammate'. An agent has everything needed 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 100%, so page, limit, auto_paginate, max_pages and context are fully documented in the schema. The description only echoes 'Paginated (page/limit)' without adding format or behavior detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the workspace's teammates') and then defines what a teammate is, distinguishing it from signature recipients or smart fields that appear among the siblings. It does not explicitly name a sibling it differs from, so it falls just short of a 5.

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

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

There is no guidance on when to use this instead of sibling list tools (list_signature_recipients, list_smart_fields) or sync_teammates for refreshing the roster. Usage is only implied by the tool name.

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