Scribe Mail

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description still adds real behavioral value: it discloses that unknown uuids fail with 422 and that the updated selection is returned, which annotations do not convey.

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

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

Three tight sentences, front-loaded with the purpose, then side effect, then error behavior. 'Returns the updated selection' is mildly redundant given an output schema exists, but it costs little.

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 annotations, full schema coverage, and an output schema, the description adds the missing behavioral pieces (recipient side effect, 422 on unknown uuids) and is complete enough to call correctly. Only the sibling-routing guidance 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 description coverage is 100%, and each parameter is documented in the schema (signature_id, integration_entity_ids with source tool, context). The description adds only 'by uuid', which is marginal beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource: targeting a signature at a batched set of directory org units/groups by uuid, with the side effect named ('everyone in them becomes a recipient'). The 'batch of org units/groups (by uuid)' framing implicitly distinguishes it from the individual-recipient sibling add_signature_recipients, but that sibling is never named explicitly.

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

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

No when-to-use or when-not-to-use guidance. The closest sibling, add_signature_recipients, is never mentioned, so the agent must infer from the 'org units / groups' framing when this batch variant is preferable to the individual-recipient one.

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 cover the safety profile (not read-only, open-world, not idempotent). The description adds valuable behavioral context beyond them: the 15MB size limit, and the specific failure modes (non-image, malformed base64, disallowed URL) that return a 422. This meaningfully helps an agent anticipate and handle errors.

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 is front-loaded, then the input-mode rule, then error handling — a logical progression. Every sentence carries information (mode selection, fallback guidance, error conditions), though the final sentence is dense with edge cases.

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?

Return values are covered by the output schema, so the description need not explain them. For an upload tool with multiple input modes and several failure paths, the description supplies exactly the context needed to invoke it correctly: which argument to use when, size/type limits, and fallback behavior.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail. The description reinforces the mutual-exclusivity rule ('exactly one' of file_base64 or source_url) and the filename pairing, but this largely restates what the schema already provides. Baseline 3 is appropriate when the schema carries the load.

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: 'Upload an image to the workspace's asset library.' It is unambiguous what the tool does. However, it does not explicitly contrast its purpose against the create/update/delete_asset siblings — the named alternative (list_assets) is invoked for reuse rather than for purpose differentiation.

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

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

It gives explicit conditions and alternatives: use file_base64 for a chat-uploaded file with no public URL, ask for a hosted URL or reuse from list_assets if raw bytes can't be read, and it warns against guessing. When-to-use and when-not-to-use are both 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 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?

Annotations already declare the write semantics (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description contributes one genuinely useful behavioral fact beyond the annotations — a blank name yields a 422 — but says nothing about permissions, duplicates, or nesting 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 short sentences, front-loaded with the action and purpose, with the validation caveat second. No filler.

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

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

An output schema exists so return values need not be explained, and annotations cover safety. The description covers what it does plus one failure mode; only sibling routing and permission requirements are 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 description coverage is 100%, including a detailed 'context' parameter, so the schema carries the burden and the baseline is 3. The description's note that a blank name returns 422 adds a validation constraint, a small increment over the schema.

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

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

States a specific verb and resource ('Create a signature folder') and adds the organizing purpose, so it is distinguishable from update_folder and delete_folder. It stops short of explicitly naming siblings, so it lands at 4 rather than 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 statement of when to create a folder versus updating one or using list_folders, and no prerequisites or exclusions are given. The agent must infer usage entirely from the name.

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

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

Annotations cover the write/idempotency profile, and the description goes well beyond them: it discloses the draft lifecycle, the 422 failure mode for missing required fields, server-side strict validation of content, and the lowercase-uuid requirement with a concrete format hint. These are behavioral facts an agent cannot infer from annotations or schema.

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

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

Front-loaded with the action and state, then the activation sibling, then content and targeting semantics. Dense but every clause carries load; only the parenthetical detail about block-tree shape edges toward surplus given it also defers to get_content_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 an 11-parameter creation tool with an output schema, the description covers the riskiest areas (required-field failures, content format, targeting, lifecycle). It leaves behaviour, filter_kind, send_email, and the mandatory `context` argument unmentioned, but the schema documents those adequately.

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

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

With 91% schema coverage the baseline is 3, but the description adds real meaning: it names the required fields (albeit omitting the required `context`), explains that content is a strict-validated block tree rooted at `stack`, and clarifies the targeting role of smart_fields_conditions and signature_template_ids. It does not touch behaviour, filter_kind, or send_email, which remain schema-only.

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 marketing campaign') and immediately differentiates the resulting state from the activation path: 'The campaign is created as a draft — use schedule_marketing_campaign to activate it.' An agent can distinguish this from schedule_marketing_campaign, update_marketing_campaign, and delete_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 routes the agent to the sibling that activates the campaign once created, and points to get_content_schema for the content format. It stops short of saying when NOT to use it (e.g. versus update_marketing_campaign for existing campaigns), but the create-vs-activate split is clearly drawn.

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 safety profile (not read-only, not destructive, not idempotent, open-world). The description adds real behavioral context: draft-vs-published state semantics, strict server-side validation, the shape of the 422 error payload, and the return value. It does not discuss rate limits or permissions, but the uncovered traits it does disclose are substantial.

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

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

Front-loads the core action and the 'call get_content_schema FIRST' directive in the opening lines, and every sentence carries information. It is dense and somewhat long, with the UUID/pixel warnings partially duplicating the schema's own notes, which is the only reason it is not 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 mutation tool with nested block-tree input, the description covers the state model, validation behavior, error contract, prerequisite lookup call, and return value. With an output schema present, return details need not be elaborated, and nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond it by flagging the high-risk gotchas an agent would otherwise miss: the stack-root block tree shape, the lowercase-UUID requirement, and pixel (not CSS multiplier) sizing for lineHeight. It adds genuine semantic guidance rather than 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 and resource ('Create a signature template') and immediately scopes what the call actually writes (draft_content, not content), which cleanly separates it from poster/updater siblings like update_signature and publish_signature. An agent can identify the tool and its effect 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 explicit sequencing guidance ('Call get_content_schema FIRST') with a stated rationale, plus the when-to-use relationship to publish_signature ('content stays empty until you publish_signature'). It also predicts the failure mode (422 on invalid tree) and what that error returns, which is far beyond generic when-to-use text.

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

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

Annotations only declare the generic safety profile (write, non-destructive, non-idempotent). The description adds high-value behavior: manual fields start empty and are set via update_teammate, bound fields draw values from the integration and disable update_teammate, url fields cannot be integration-filled, nothing changes in any signature until a template references the field, and the required smart_fields:write scope plus the 422 failure modes (taken label, invalid kind, unsuitable integration).

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 first, then alternatives, then the manual/integration branch, then edge cases and errors. Nearly every sentence carries distinct information, though the single-block paragraph format makes it harder to scan than a short enumerated structure would.

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

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

An output schema exists, so return values need not be restated, and the description still notes "writes one field and returns it." With permissions, error conditions, and the manual/bound behavioral split all covered, an agent has everything needed to invoke this 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 baseline is 3. The description goes beyond the schema by explaining the semantic interaction of integration_id + integration_attribute (values then come from the integration, update_teammate stops working) and the constraint that url fields must stay manual, which the schema alone does not convey.

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 scopes what a smart field is ("a merge field signature templates and campaign conditions can use"). It also names the sibling it is not (update_smart_field for rename/retype/rebind) and the pre-check tool (list_smart_fields), so it is unmistakable among the many create_* 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?

Explicit when-to-use (check list_smart_fields first because labels are unique) and when-not (use update_smart_field to rename, retype or rebind an existing field). It also distinguishes manual vs integration-bound creation, which is the key branch an agent must choose between.

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 safety profile is covered. The description adds real value beyond that: the environment-dependent 409 conflict condition and the fact that email must be new. It does not mention side effects such as whether the teammate is immediately active or what the response contains, but with annotations and an output schema present that gap is modest.

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, zero filler. The core action is front-loaded and the precondition is stated before the exclusionary alias note, so the most decision-relevant information comes first.

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 create tool with annotations covering idempotency and side-effect profile, a full schema, and an output schema, the description covers the remaining decision-critical unknown — the directory-integration conflict — and clearly separates alias management. Nothing needed 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 email, context and smart_fields are fully documented in the schema itself (including smart-field failure semantics and null clearing). The description restates the email + smart-field composition without adding syntax or constraints beyond what the schema already provides, so the baseline of 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 ("Create a new teammate") and immediately scopes the input shape ("from a primary email plus optional smart-field values"), which separates it from list_teammates, update_teammate and delete_teammate at a glance.

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 with a concrete failure mode: create is only usable when the workspace manages its own team list, and a directory integration (Google, Microsoft, Zoho Mail) yields a 409 conflict. It also excludes a related concern — email aliases are handled elsewhere — so the agent knows this tool is not the route for aliases.

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?

Annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true); the description adds substantial behavior beyond that: the copy inherits the source's design (draft published as its content) and reply/internal variants, is assigned to no one, has installation off, and carries no smart-field rules. It also discloses error semantics (404 for unknown signature, 422 for unknown folder).

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 and the copy's state are front-loaded, then the alternative and follow-up workflow, then error codes and return. It is dense and information-rich with little waste, though the single long sentence carries several clauses that could be split for readability.

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

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

An output schema exists, so return values need only be summarized ('Returns the copy.'), which it does. Combined with the inheritance behavior, the assignment/installation state, the workflow routing, and the 404/422 errors, 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 description coverage is 100%, so the schema already documents id, name, context, and folder_id, making 3 the baseline. The description clarifies defaults (name falls back to '<name> (Copy)', folder defaults to the source's) but adds no syntax or format detail beyond the schema, so it does not rise above baseline.

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 differentiates from siblings by saying to use it 'instead of reading the design and create_signature'. An agent can distinguish it from create_signature, update_signature, and preview_signature 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 gives the when ('a safe copy to try a change on ... without touching the original or anyone's signature') and the alternative it replaces (reading the design + create_signature). It also routes the follow-up workflow to update_signature and preview_signature, and explains how to bring a tried change back to the original.

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 safety is covered. The description adds genuine behavioral context beyond them: UTC bucketing, the fact that group_by switches the entire response mode, and that breakdown rows bundle views, clicks and clickthrough rate in one call. No permission/rate-limit disclosure, but that is minor given rich annotations.

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

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

Front-loaded with the core purpose and mode contrast, and every sentence carries information. The response-shape fragments are somewhat redundant since an output schema already exists, but they serve to make the timeseries-vs-breakdown distinction concrete rather than being pure 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 rich annotations (4 hints) and an output schema, the description is not required to explain returns or safety, yet it covers the critical mode-switching behavior an agent must understand before calling. The only real gap is the missing 'anchor' group_by value, which could lead an agent to believe that breakdown dimension is unsupported.

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 it by explaining what group_by actually does to the result shape and which filters combine with the range. It does, however, list group_by options as 'signature_template | marketing_campaign | teammate | country' and omits the 'anchor' enum value present in the schema, a small inconsistency.

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 — 'Signature-click counts over a date range' — which is clearly distinct from the views/events analytics siblings by virtue of naming clicks. However, it never names or contrasts with the closest alternative (get_analytics_views), so sibling differentiation is left implicit rather than explicit.

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

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

Explains the two operating modes and when each applies: default timeseries bucketed by granularity vs. setting group_by for a ranked breakdown, plus a motivating use case ('which signature/teammate drives the most engagement'). No explicit when-not guidance or named alternative tools, but the mode-selection context is clear.

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

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

Annotations already declare readOnly/idempotent/destructive=false, so the description's job is to add nuance, which it does: the multi-currency warning ('value is summed across currencies, so pass currency or group_by=currency for a clean total') and the rule that granularity is ignored when group_by is set are genuine behavioural disclosures beyond the annotations. It stops short of permissions, rate limits, or data-freshness notes.

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

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

Three dense sentences, but front-loaded with the default behaviour and output shape before the optional breakdown path, and every clause carries information (output shapes, currency caveat, use cases). Slightly long, yet nothing is padding.

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

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

For a 16-parameter tool with an output schema and rich annotations, the description covers the two operating modes, the shape returned by each, the key caveat, and representative questions it answers. Nothing an agent needs in order to call it correctly appears to be 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, and the description exceeds it by explaining relationships the schema states only locally: granularity's default of day and its being ignored under group_by, the default ranking metric for order_by, and how currency interacts with the summed value. It adds cross-parameter meaning rather than repeating field definitions.

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 ('Aggregated conversion/revenue numbers from recorded events') and immediately distinguishes its output shape from the sibling list_analytics_events / get_analytics_clicks / get_analytics_views by declaring both the default timeseries and the group_by breakdown modes. An agent can tell what this returns 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 'Answers total revenue, revenue by campaign/template/teammate/country, conversions per day, top customers' clause gives strong positive usage cues, and it explains the mode switch (default vs group_by) that selects behaviour. It does not, however, name or exclude the adjacent analytics siblings, so the routing is implied rather than explicit.

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

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

Annotations already carry readOnly/idempotent/non-destructive, so the safety burden is covered. The description adds real behavioral context: the default mode and shape, UTC bucketing, the hour-granularity 31-day cap, and that breakdown rows include clicks and CTR. It could note rate limits or large-range behavior, but this is strong added value beyond annotations.

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

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

Front-loaded with purpose and default behavior, then the alternative mode, then filters. It is dense and somewhat long, but nearly every clause carries invocation-relevant meaning; the return-shape sketches are arguably redundant given the output schema exists.

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, it covers mode selection, defaults, filters, bucketing constraints, and the response shapes of both modes, leaving no gap an agent would need to guess at before calling.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond it by explaining the semantic split (group_by switches the response shape entirely, page/limit apply only to breakdown) and by enumerating group_by dimensions and filter semantics, which materially aids correct invocation.

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 ('Signature-view counts') with explicit scope (date range), and differentiates itself from siblings like get_analytics_clicks and list_analytics_events by naming the entity counted. An agent can distinguish 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?

Clearly explains the two modes and when each applies: default timeseries, or set `group_by` for a ranked breakdown. It even gives a motivating question ('which signature/teammate drives the most engagement'). It stops short of naming competing analytics siblings explicitly, so no exclusion guidance, but context is clear.

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

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

Annotations already declare 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 carry readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered elsewhere. The description goes beyond them by flagging that PII lives in `traits` and by naming the returned surfaces (first/last_seen_at, first_touch attribution, lifetime `stats`), which is meaningful sensitivity context for a read 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?

A single dense sentence, but front-loaded with the core action and keyed alternates. It is longer than most definitions, yet each clause (not-a-member, id-not-distinct_id, return contents) carries distinct routing or data-sensitivity 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 return values need not be enumerated here. The description nonetheless covers identity disambiguation, the sibling alternative, and PII location — everything an agent needs before calling — leaving only minor gaps such as error behavior for a missing id.

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. The description's note that `id` is the Scribe uuid from list_visitors restates what the schema already documents, and it adds no format or constraint detail beyond that.

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 (fetch one) and resource (identified visitor), and immediately delimits what it is NOT — the customer's `identify` subject rather than a Scribe member. It also says what identity key is required (Scribe `id` uuid, not `distinct_id`), which no sibling needs spelled out.

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

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

Explicitly names the alternative path: to look up by `distinct_id`, use list_visitors rather than this tool. Combined with the id-vs-distinct_id routing, an agent knows exactly which tool to reach for given the identifier it holds.

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

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

Annotations already declare this a safe, idempotent, open-world read, so the safety profile is covered. The description adds genuine behavioral context by defining how the ranking is computed (the first signature click that drove the first visit) and sketching the return shape, which 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?

A single front-loaded sentence with no filler. The trailing inline return-shape sketch is mildly redundant given an output schema exists, but it is brief and does not bloat the definition.

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

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

For a read-only analytics tool with an output schema, this covers purpose, metric definition, and dimension adequately; nothing about return values needs restating. What is missing is the time window the ranking spans, which is meaningful context an agent cannot get from any structured field.

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, context, and the group_by enum are already documented in the schema. The description restates the group_by dimension as 'first-touch dimension' but adds no syntax, defaults, or format details beyond that.

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 plus resource: ranks acquisition of identified visitors by signature template or teammate. The parenthetical defines 'first-touch' so the agent can distinguish this from click/view analytics siblings such as get_analytics_clicks and get_analytics_views.

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 analytics framing and the definition of the first-touch metric, but there is no explicit when-to-use or when-not-to-use guidance and no sibling is named. An agent must infer that this is the attribution-ranking tool rather than being told.

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, so the safety bar is lower; the description still adds real value by explaining why it is read-only ('plan and seats are managed in the dashboard / by the billing system, never via the API') and clarifying the no-identifier scoping. It does not cover rate limits or freshness of the snapshot, which would be the remaining gap.

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 payload's contents before the usage hint, and each sentence carries information (returned fields, setup workflow, scoping, read-only rationale). Slightly dense with parenthetical field lists, but no filler.

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

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

With an output schema present, return-value explanation is optional; the description nonetheless names the key fields, covers the no-id scoping, and supplies the conversion-tracking workflow. Nothing an agent needs to invoke 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% for the single `context` parameter, so the baseline is 3. The description adds only the meta-point that the tool takes no workspace identifier, which is useful but not a per-parameter specification.

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 exactly what is returned (plan, seat_count, event_tracking). This clearly separates it from the analytics/visitor/signature siblings, which cover different data domains.

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 task trigger ('when helping a user set up conversion tracking, read the ID here and search_docs for...') and names the companion tool, plus a scoping exclusion ('there is no id — it is always the API key's own workspace'). It stops short of stating when *not* to reach for this tool for plan/seat questions beyond noting they are dashboard-managed.

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 destructiveHint=true, idempotentHint=false, openWorldHint=true, but add no detail. The description supplies the crucial 'without publishing' distinction, the specific 403/409 failure modes, the fact that errors carry a dashboard link, and the agent-facing instruction to relay it since OAuth can't run via API. That is substantive context well beyond the annotation flags.

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

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

Front-loaded with purpose, then the sibling alternative, then error semantics — a logical order with no filler. It is somewhat dense and compresses the failure handling into em-dash clauses, but every clause carries usable 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 return values need not be explained. Given that, the description covers purpose, scope, the sibling boundary, and both failure paths with the required agent behavior — nothing an agent needs to invoke 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%, so the `id` and `context` parameters are already fully documented in the schema; baseline 3 applies. The description adds only an indirect hint about `id` (it points at 'the signature's current content') and nothing about the analytics `context` field beyond what 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?

States a specific verb ('Trigger installation') plus the exact resource and scope ('a signature template's current `content` to connected mail clients... on every email it is assigned to'). It also explicitly distinguishes itself from the sibling install_signature_for_email by scope, 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 the when-to-use condition and names the alternative plus the condition that selects it ('for one email alone, use install_signature_for_email'). It also tells the agent what to do on failure (relay the dashboard link to the user because the API can't run OAuth).

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

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

Goes well beyond the annotations: it discloses that execution is asynchronous ('runs in the background', result lists what was queued), how to observe completion, and the full error surface (409 installed_by_client, 409 no_signature_to_install, 422 not_a_recipient, 403 plan limitation, 409 installation_unavailable), including the prescribed agent response for each. The annotations only flag it as a non-idempotent, destructive 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-loaded with the action and its scope, then layers usage examples, then error handling — a logical order. It is dense and clause-heavy but nearly every sentence carries operational content; only the parenthetical integration list (Google Workspace, Zoho Mail, Front) is arguably expendable.

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, asynchronous, multi-error-path tool it covers what is needed: scope vs the sibling, async behavior and polling, and every documented failure with the expected relay message. An output schema exists, so the description is right not to explain return values.

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 email_id and signature_id semantics are already documented, and the description largely restates them ('or only `signature_id`', installed/activated vs published assignments). It adds the useful nuance that the scope is 'the installed (activated) and published signatures assigned to the email', but not enough beyond the schema to raise the baseline.

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) and immediately bounds the scope: 'in its mailbox alone, without reinstalling the signature for everyone else (install_signature)'. An agent can distinguish it from the sibling install_signature and from the recipient-management tools without opening a schema.

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

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

Gives concrete when-to-use scenarios (a send-as alias needing a signature, one person whose title changed) and names the higher-scope alternative install_signature as the thing you should not reach for. It also spells out the operational follow-up (list_signature_installations with the email_id) and the conditions that produce each failure mode.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description confirms 'Read-only' consistently while adding information the annotations cannot carry: asynchronous ingestion lag, the required analytics:read scope plus plan gating with a 403 outcome, and pagination semantics including the truncated flag. That is substantive context beyond the structured safety hints.

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 load-bearing: what is returned, when to use it and what to use instead, the freshness caveat, and the auth/pagination contract. Information is front-loaded with the resource and result shape before the caveats.

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

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

For a 13-parameter, high-complexity list tool with an output schema and full annotation coverage, the description supplies everything else an agent needs: routing, async staleness, permission/plan failure mode, and page limits. Return-value detail is correctly left to the output schema.

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

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

Schema description coverage is 100% and all 13 parameters are documented in the schema, so the baseline is 3. The description restates the pagination behavior (auto_paginate up to max_pages, truncated meaning more remain) and one filter usage (distinct_id for a visitor's history), but adds little that the schema fields do not already say.

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 sentence gives a specific verb+resource+scope: raw conversion events for the workspace, sourced from the website SDK and server-to-server calls, most recent first, one row per event. It also names the sibling alternatives (get_analytics_events_summary, get_analytics_views/clicks, list_visitors), so an agent can distinguish it 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 cases are given (verify conversion tracking, read one visitor's history via distinct_id, export rows) and explicit when-not-to-use routing is provided for three sibling families. This is a complete routing guide, not an implied one.

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/destructive annotations, the description discloses the required assets:read scope, that deleted assets are excluded, that delete_asset only soft-deletes an asset in use, the sort order (newest first), and pagination behavior including the truncated flag. This is substantial behavioral context the annotations alone don't 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?

The description is relatively long but front-loaded with the core purpose, then layers usage and pagination details, and every sentence earns its place. It is dense but not padded, with only minor over-packing of sibling-related details.

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 explanation is not required, and the description still covers scope, filtering limits, sort order, pagination, and sibling routing. Nothing an agent needs to call the 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 coverage is 100%, so the schema already documents the parameters, but the description adds real meaning: it ties auto_paginate to max_pages ('fetch up to max_pages') and states the default/max page size (50/100). This clarifies how the pagination parameters interact, going beyond the per-field descriptions.

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

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

The description gives a precise verb+resource ('List the workspace's asset library') and enumerates the resource types (logos, banners, profile pictures) and returned fields. It clearly separates this from create_asset, update_asset, and delete_asset, which are named as distinct operations.

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 guidance: reuse an image by putting the asset's id in an image block's assetUuid rather than uploading a duplicate with create_asset, and use it to find the id for update_asset/delete_asset. It also names the condition to check in_use first, and discloses the no-filter-by-role constraint with the workaround (page and match role or name).

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

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

Annotations already 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?

Annotations already declare readOnly, idempotent, non-destructive, open-world. The description adds real behavioral context beyond them: results are filtered to documents that have a downloadable PDF, the response shape (file/receipt), and that documents are issued by the billing system and cannot be created via the API. This meaningfully reduces caller uncertainty.

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 included/excluded content, followed by response shape and read-only note. It is dense but every sentence carries information; the inline shape of `file` overlaps with the output schema, which is slightly redundant but not wasteful.

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

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

Safety is covered by annotations and the output schema exists, so return-value detail is technically optional. The description is nonetheless complete for correct invocation: scope, filter constraint, ordering, pagination, and read-only nature are all present.

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

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

Schema coverage is 100% – page, limit, context, max_pages, and auto_paginate are all documented in the schema. The description adds only the 'newest first' ordering and a nod to pagination (page/limit), leaving auto_paginate/max_pages entirely to the schema. Baseline 3 is appropriate given 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?

States a specific verb and resource with scope and content: 'List the workspace's financial documents (invoices and credit notes), newest first.' It clarifies exactly what is included, and no sibling tool covers invoicing/billing, so differentiation is unambiguous.

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

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

It implies usage by stating how to consume results ('Use the `file.url` to fetch/download the document') and that filtering is limited to docs with downloadable PDFs. However, it offers no explicit when-to-use/when-not guidance or routing to any alternative for related needs.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that entities originate from an external teammates integration and that results are paginated, but says nothing about what happens if the integration is not connected or how an empty/unavailable directory is signaled.

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 scope and immediately followed by the downstream rationale. 'Paginated (page/limit)' is mildly redundant with the schema but not wasteful enough to hurt readability.

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

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

For a paginated read tool with a full schema and an output schema, the description covers purpose, consuming tool, and pagination behavior. It is nearly complete, missing only edge-case behavior around unavailable integrations or empty results.

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 five parameters are documented there, including defaults for page and limit. The description only echoes 'Paginated (page/limit)' and adds no syntax or usage nuance 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 ('List the workspace's directory org units / groups') and narrows the source ('from a teammates integration'), which distinguishes it from siblings like list_integrations and list_teammates. An agent can identify 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?

Explicitly ties the output to the downstream action: 'Their uuids are what you pass to add_signature_recipient_entities to target a signature at a whole org unit.' That is clear when-to-use context, though it offers no exclusions or mention of remove_signature_recipient_entities as the inverse path.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds substantial context beyond them: the status/error_message/error_since fields, the dashboard_url relay instruction, the fact that the API cannot run OAuth, and the SUPER ADMIN prerequisite for connecting third-party apps. This is a rich behavioral profile not derivable from structured data.

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

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

Purpose is front-loaded and every clause is substantive, but the single dense paragraph stacks field descriptions, OAuth limits, admin prerequisites, and sibling routing together. Slightly long, though it avoids pure 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?

With an output schema present, return values needn't be restated, yet the description still gives enough about status/error fields to interpret results. It covers the mutation-free read profile, the pagination model, and the correct alternative path for per-email issues.

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 all five parameters documented, so the baseline is 3. The description only notes 'Paginated (page/limit)' without adding defaults, caps, or auto_paginate semantics beyond what the schema already 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?

States a specific verb and resource (list the workspace's active/set-up integrations) and immediately scopes it: workspace-level health, including failing ones. It distinguishes itself from list_signature_installations and list_integration_entities, so an agent can route correctly 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 names the alternative for a related-but-different need ('for per-email install state/errors use list_signature_installations') and routes setup questions to search_docs with example queries. It also states when NOT to act directly (connect via dashboard, not API, needs SUPER ADMIN), which is exactly the guidance an agent needs.

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 without help. The description adds the paginated nature of the call and notes the retrieved shape includes targeting and a content block tree, but with an output schema present that return detail is partly redundant, and nothing is said about rate limits, auth, or result size 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?

A single well-formed sentence that front-loads the resource and appends the payload/pagination detail without filler. It is compact and every clause adds information, though the inline backticked field names make it denser than it needs to be for a list tool.

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

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

For a read-only, fully schema-documented list tool with an output schema, the description supplies the scope (workspace-wide), the returned content shape, and the pagination model — enough for correct invocation. The only real gap is the absence of guidance on when to choose it over sibling list tools or campaign-specific operations.

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 every parameter (page, limit, max_pages, auto_paginate, context) is already documented at the schema level. The description only restates the page/limit pair without adding format or interaction semantics (e.g., how auto_paginate interacts with max_pages), 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 (List) and resource (the workspace's marketing campaigns), and even enumerates the per-item payload (status, targeting, content block tree), which cleanly separates it from preview/pause/resume/schedule_campaign siblings. It does not explicitly contrast itself with other list_* siblings, so a 4 rather than a 5.

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

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

Usage is only implied by the verb — an agent can infer this is the read path for campaigns versus create/update/delete/preview, but the description never states when to prefer it, when not to, or what condition would route the agent elsewhere. Pagination mechanics are mentioned but that is a parameter concern, not selection guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further by disclosing the status enumeration and, notably, the semantics of error_code (user_not_found = the recipient has no account on that integration) — a field not present in the input schema, so this is genuine added context. It stops short of describing pagination behavior, which schema defaults cover anyway.

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 what the tool returns before the routing guidance, and the parenthetical explanation of failure states is worth its length. It is dense — three distinct ideas packed into a few clauses — but no sentence is filler.

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

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

An output schema exists, so return-value explanation isn't strictly required, yet the description adds the row shape and failure codes helpfully. Filters are enumerated and the sibling boundary is clear; only minor operational details (auto_paginate interaction with max_pages) are left entirely to 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 description coverage is 100%, so every filter (page, limit, status, email_id, email_address, integration_id, signature_template_id) is already documented with type, enum, and bounds. The description only enumerates the filterable fields without adding format or syntax 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+resource ('where each signature actually IS (or failed to be) installed, per email') and defines the row granularity (email × signature × integration/email client) plus the status field. It explicitly distinguishes itself from the nearby sibling list_integrations, which only reports workspace-level connection health.

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 questions ('is X's signature installed on <integration>?', 'which installs failed and why?') and names the alternative tool plus the condition that rules it out. An agent can route correctly without opening any schema.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety and repeatability are covered. The description adds genuinely useful behavior not in the annotations: `data` is paginated while `selection` is returned as the full rule config, and it discloses that a sibling add/set call exists for the write side. It says nothing about auth scope, rate limits, or ordering, so it stays modest rather than rich.

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 blocking requirement is front-loaded in the first words, which is exactly right for a tool that fails without signature_id. The rest is dense but each clause carries information (what sources mean, what selection contains, pagination vs. full-config behavior). Slightly long for a read-only list endpoint, but not padded.

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

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

For a read-only, idempotent list tool with a full annotation profile, an output schema, and 100% schema coverage, the definition covers the only real failure mode (missing signature_id) and how to recover from it. It even previews the shape of the returned rule config, so 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 page, limit, context, max_pages, signature_id and auto_paginate are all already documented, which sets the baseline at 3. The description's signature_id note (a signature template UUID from list_signatures) largely restates the schema, and it never discusses auto_paginate/max_pages interaction; its extra detail (sources values, selection contents) explains the return payload rather than the inputs.

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

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

States a specific verb and resource (list the emails a signature is assigned to) and then details the payload shape (sources explanations plus the selection rule config). That scope is clearly distinct from list_signatures, which it names, and from the sibling mutators add/remove/set_signature_recipient*. An agent can pick this tool 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 the prerequisite explicitly (REQUIRES signature_id, a template UUID), rules out the wrong assumption ("there is no workspace-wide form of this tool"), and routes the agent to the alternative that produces the needed id (list_signatures, pass an `id` from it). That is explicit when-to-use and how-to-unblock guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds real behavior: content trees are omitted by default to save tokens and has_content/has_draft_content signals remain. It discloses the pagination model as well. It stops short of describing return shape, but that is minor given the annotation coverage.

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, then definition, then scope, then the content toggle. The definitional sentence earns its place because 'signature' is overloaded in this sibling set, though the description runs slightly long for a simple list tool.

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

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

An output schema exists, so return values need not be explained, and the description covers purpose, scope, pagination, and the content-omission tradeoff. It is essentially complete for an agent to call the tool correctly, with only a missing explicit sibling-routing rule as a 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%, so the schema already documents page, limit, include_content, auto_paginate, and max_pages in full. The description's mention of pagination and the include_content flag largely restates what the schema already says, so baseline 3 is appropriate.

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

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

States a specific verb and resource ("List the workspace's email-signature templates") and disambiguates the domain term by defining what a Scribe 'signature' is. The scope note ("v1 returns the workspace's primary templates") separates it from siblings like list_signature_variants 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?

Gives clear context for when to call it and one concrete routing decision (pass include_content:true to fetch the block trees). It never names an explicit alternative or a when-not condition, but the scope clarification effectively frames its place among the many signature-related siblings.

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

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

Annotations already establish the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description adds real behavioral value beyond that: it always returns both entries, enumerates the reported states, explains the `supported` flag, and discloses the 409 variants_unavailable behavior and the M365 integration dependency. It stops short of describing pagination or ordering, if any.

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 tightly focused sentences, front-loaded with the core action and backed by the variant definition and the `supported` caveat. Every sentence earns its place, though the variant definition is slightly expansive for a list tool.

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

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

With an output schema present, return fields needn't be re-explained, yet the description still clarifies `supported` and the 409 edge case. Combined with 100% param coverage and full annotations, an agent has everything needed to call it correctly; only explicit sibling routing 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 description coverage is 100%, so both parameters (signature_id and the analytics-only context field) are already fully documented. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb (List) and a precisely scoped resource (a signature's reply and internal variants), then defines what a 'variant' is and its two sub-types. The resource is specific enough that an agent can distinguish it from siblings like list_signatures or get_signature_html 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?

It provides a useful prerequisite (variants require an active Microsoft 365 signatures integration) and the failure condition (writes return 409 variants_unavailable when unsupported), which is implied usage context. However, it never explicitly says when to call this versus update_signature_variant, delete_signature_variant, or preview_signature, leaving routing 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 the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description adds real value beyond them: the computed Email field is deliberately not exposed, results are paginated, and returned fields carry kind/default/integration_id semantics.

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

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

Three sentences, no waste, front-loaded with the verb and resource before the caveats (Email field excluded) and the pagination note. Every sentence 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?

An output schema exists, so return values need not be spelled out, and a full 100% schema coverage plus read-only annotations mean the description only needs to add scope and exclusions. It does both, leaving nothing an agent needs to call this 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%, including page/limit/auto_paginate/max_pages/context, so the schema carries parameter meaning. The description only restates pagination ('page/limit') and adds no format or default details beyond the schema; baseline 3 applies.

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

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

States a specific verb (List) and resource (smart-field definitions) and immediately clarifies what those are: the merge fields available to signature templates. The scope ('the workspace's') plus the examples (first name, job position, custom fields) distinguish it from sibling list_* tools and from create/update/delete_smart_field.

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

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

Usage is implied rather than stated: an agent can infer you call this to discover available merge fields for signature templates, and the exclusion of the computed Email field is a useful boundary. But there is no explicit when-to-use/when-not or pointer to an alternative sibling, so it stays at minimum-viable.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine value on top: it discloses the payload contents (email addresses plus smart-field values merged into templates) and the paginated nature of the result. It stops short of describing auto-pagination behavior, which lives only in 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?

Three tight sentences, front-loaded with the action and scope, then the domain definition, then pagination. Every sentence earns its place, though the trailing "(page/limit)" is mildly redundant given the schema and could be dropped.

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-shape explanation is not required, and the description still volunteers what a teammate record contains. Combined with full annotation coverage and a 100%-documented schema, the definition gives an agent enough to call it correctly; only the distinction from sibling list tools is left implicit.

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

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

Schema description coverage is 100% and all five parameters are documented there, so the schema carries the load. The description's parenthetical "(page/limit)" merely echoes two schema fields and says nothing about auto_paginate or max_pages, so it adds no meaning beyond the structured data. 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 goes further by defining what a teammate is — a managed person whose signature Scribe deploys, carrying email addresses and smart-field values. That definition distinguishes it from near-neighbors like list_signature_recipients and list_signature_installations without the agent having to open 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?

Usage is implied by the resource definition (listing teammates rather than recipients or installations), but the description never states when to reach for this tool versus list_signature_recipients, or how it relates to sync_teammates. It is adequate but leaves the routing inference entirely to the caller.

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), so the description only needs to add context. It does: default sort order ('Newest first'), pagination, and the important disclosure that PII lives in the traits column. It omits how auto_paginate/max_pages interact, but the added context is genuinely useful.

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

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

Four tightly packed sentences, front-loaded with what the rows are and who they are not before moving to filters. Nothing is wasted, though the middle sentence carries a heavy comma list that borders on density.

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

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

For an 11-parameter list tool with a full output schema and complete annotation coverage, the description covers identity, contents, filters, ordering, and pagination. The pagination-control parameters are left to the schema, which is acceptable given 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%, so every parameter is already documented, and the baseline is 3. The description reinforces a few semantics ('distinct_id (exact)', trait_key+trait_value with a plan=enterprise example, first-seen date range) but adds little beyond the schema's own examples. 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 description states a specific verb+resource ('list the workspace's identified visitors') and immediately disambiguates the domain boundary: 'the customer's own end-users ... NOT Scribe members/teammates.' That single contrast separates it from list_teammates and get_visitor 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?

It gives clear context for use (listing identified end-users, with the exact filters available) and explicitly excludes teammates. It never names when to prefer the sibling get_visitor or get_visitor_breakdown instead, so the routing guidance is clear but not 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?

Goes beyond the annotations by disclosing the state precondition and the specific failure mode (409 on a non-active campaign), plus reversibility via resume. Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false); the description usefully adds the operational constraint they do not 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?

Two compact sentences with no filler; the effect is front-loaded and the constraint plus escape hatch follow in the right order. Every clause carries information.

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

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

With an output schema present, return values need no explanation, and the description covers the precondition, error behavior, and reversal path. What is missing is minor: whether pausing preserves configuration for re-activation is implied but not stated.

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 `id` and `context` parameters are already fully documented in the schema, including the cross-reference to list_marketing_campaigns. The description adds no parameter-level detail beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb (pause) and resource (marketing campaign) plus the concrete effect: 'it stops applying to signatures.' This distinguishes it immediately from delete_marketing_campaign and update_marketing_campaign in the sibling list.

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

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

Gives a clear precondition ('Only an active campaign can be paused') and routes the agent to the follow-up action (resume_marketing_campaign). It stops short of naming the adjacent alternatives an agent might confuse this with, such as delete or schedule, so it is strong but not fully comparative.

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, but the description adds non-obvious behavior: values are placeholders, the render is recipient-less and tracking-free, and an empty `html` means the campaign has no content yet. The empty-result signal is exactly the kind of behavioral detail annotations cannot convey.

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

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

Three dense sentences, front-loaded with the core action, then the workflow, then the edge case. No filler, and the most decision-relevant information (what it renders, when to call it) comes first.

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 shape need not be explained, yet the description still flags the one field that matters for interpretation (`html`) and what an empty value means. Nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100%, so both `id` and `context` are already documented in the schema; the description adds no syntax or sourcing detail beyond what the schema states. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

Specific verb and resource: 'Render a marketing campaign's `content` block tree to HTML with PLACEHOLDER values'. It also explicitly anchors itself against a sibling ('the same recipient-less, tracking-free render preview_signature does'), so an agent can distinguish it from preview_signature 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 workflow position: use it to VERIFY layout after create/update_marketing_campaign and BEFORE schedule_marketing_campaign. It also states the follow-up action (read `html`, fix content if wrong), leaving no ambiguity about when this tool is the right call.

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