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

Goes well beyond the annotations: it discloses that the call returns DKIM/SPF records the caller must place in DNS, and — critically — that using an API key bypasses the dashboard's admin-role check, granting authority a non-admin member lacks. The annotations only assert write/non-idempotent/open-world; this privilege-escalation caveat is exactly the kind of extra context the description should carry, and nothing contradicts the 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?

Bold section labels front-load purpose, exclusion, return value, and caveat, so an agent can scan to the needed fact. No redundant sentences; every line 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?

For a write tool with no output schema, the description covers the return content, the routing to the verify sibling, and an auth caveat. The only real gap is the undocumented projectId parameter, which neither description nor schema explains.

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?

Two required parameters with only 50% schema coverage (projectId carries no schema description), yet the description says nothing about either parameter — not even which project the domain attaches to. The domain field's bare-name rule is documented in the schema, but the description adds no meaning over the structured fields.

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

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

States a specific verb+resource ("Register a new sending domain") and immediately disambiguates from the nearest sibling by name: "Not for: Re-checking a domain already added — that is plunk_verify_domain." An agent can differentiate add vs. verify vs. list/delete 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 "Use when" condition ("Setting up a new from address on a domain Plunk does not yet know about") plus an explicit "Not for" exclusion routing to plunk_verify_domain. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety/mutation profile is covered. The description adds genuinely useful behavior beyond that: the 500-email-per-call limit and the createMissing flag governing whether unknown addresses become new contacts. The 'Returns' line is vague, which keeps this from a 5.

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

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

Front-loaded with a labeled Purpose/Not-for/Use-when structure that scans quickly and wastes little space. The 'Returns' sentence ('The result of the membership change') is empty filler that slightly dilutes it.

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

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

No output schema exists, but the description scopes the operation, limits, and the createMissing behavior well. The one gap is the undescribed `subscribed` flag, which could affect whether added contacts receive email, so it is not fully complete.

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

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

Schema coverage is 75% and the description reinforces key semantics (max 500 emails, createMissing meaning). It adds context beyond the schema for createMissing and the email cap, but says nothing about the undocumented `subscribed` parameter, so it doesn't fully compensate.

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

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

States a specific verb+resource ('Add contacts to a STATIC segment by email address') and immediately distinguishes the scope from plunk_update_segment for dynamic segments. An agent can tell what this does and how it differs from siblings 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?

Explicitly provides when to use ('hand-curating an audience, or importing a list') and when NOT to use ('Not for: a DYNAMIC segment... use plunk_update_segment instead'). Names the concrete alternative tool, leaving nothing 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 declare the safety profile (not read-only, not idempotent, open-world, non-destructive), so the description needn't repeat that. It adds genuinely useful behavior: a step added here is orphaned until plunk_add_workflow_transition wires it in, DELAY is capped at 365 days, and WEBHOOK templating requires v0.12+.

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?

Bold-labeled sections (Purpose, Not for, Returns, Use when, Note) front-load the highest-value routing information with no filler. It is on the longer side, but each section carries distinct content.

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

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

For a mutation tool with no output schema, it states the return value ('the created step including its id, needed for transitions'), which is exactly what the next call requires, and flags the orphan-until-transition caveat. Nested-object config depth is largely delegated to the schema, which covers it 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?

Schema coverage is 71% and the enum/config shapes are well documented in the schema, but the description adds constraints not in the schema, notably the 365-day DELAY cap, the v0.12+ interpolation requirement, and that UPDATE_CONTACT accepts subscriptionAction. It does not cover the autoConnect or position semantics.

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

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

The description opens with a specific verb+resource ('Add a step to a workflow') and enumerates the step kinds (email, wait, branch, webhook, update contact). It also explicitly distinguishes itself from plunk_insert_workflow_step, so an agent can separate the two 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?

It names a 'Not for' alternative with the exact condition that selects it (inserting between already-connected steps) and states 'Use when' for building out an automation incrementally. Exclusions and alternatives are both explicit.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false and openWorld=true, so the mutation and novelty profile is covered. The description adds value beyond that with a prerequisite (both steps must exist) and a return statement ('the created transition including its id'), which matters since there is no output schema. It stops short of noting that non-idempotent repeated calls can create duplicate transitions or any permission requirements.

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

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

Four bolded, clearly labeled sections with purpose front-loaded and zero filler; every clause carries distinct information (purpose, exclusion, prerequisite, return value, trigger conditions). Well suited to fast agent scanning.

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?

Good for routing and prerequisites, and the absent output schema is partially compensated by the Returns line. But a tool with a free-form nested 'condition' object, an undocumented 'priority' ordering parameter, and 20% schema coverage leaves the agent guessing on how to actually express a branch condition — the most important detail for this tool.

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

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

Schema description coverage is only 20% — just 'id' (and only as 'Workflow UUID'). The description never explains fromStepId, toStepId, priority (no doc at all), or the shape of the nested 'condition' object, even though conditional branching is the headline use case. With four of five parameters undocumented in both places, the description does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Connect one step to another') and immediately defines the semantic content of the edge ('what happens next and under which condition'). It explicitly names the sibling it is not (plunk_add_workflow_step), so an agent can disambiguate 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?

Has an explicit 'Not for' clause naming the alternative tool and a prerequisite ('Both ends must exist first'), plus a 'Use when' clause covering both the linear-wiring and conditional-branching cases. When-to-use, when-not-to-use, and the alternative are all 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?

Goes well beyond the annotations: states history is preserved, action is fully reversible via plunk_unarchive_campaign, requires Plunk v0.15+, and that scheduled/sending campaigns cannot be archived. These are real behavioral constraints not encoded in the structured fields.

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

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

Bold-labeled sections (Purpose / Not for / Returns / Use when / Note) make it skimmable and front-loaded, with the key distinction from delete stated early. No wasted 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?

No output schema, but the description names the return value ('the archived campaign'), covers preconditions, reversibility, and version requirement. An agent has everything needed to invoke 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?

Single 'id' parameter with 100% schema description coverage ('Campaign UUID'). The description adds no syntax or format detail beyond the schema, so baseline 3 is appropriate for a fully-documented lone parameter.

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

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

States a specific verb+resource (archive a campaign) and immediately scopes it against the destructive alternative plunk_delete_campaign. An agent can distinguish it from delete/unarchive/bulk-archive 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 'Use when' (tidying unfinished/abandoned campaigns) and 'Not for' (permanent removal, routing to plunk_delete_campaign), plus reversibility pointer to plunk_unarchive_campaign. When-to-use and when-not-to-use are both stated.

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

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

Annotations already declare destructiveHint=false and idempotentHint=true, so the safety profile is partly covered; the description adds genuinely new context by naming the version floor (Plunk v0.15+), stating the operation is reversible via archived:false, and explaining that no confirmation prompt appears because nothing is lost. It still says nothing about permissions/scopes or batch failure semantics (partial success vs all-or-nothing), which is the main remaining gap for a bulk mutation.

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

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

Five labeled lines, each carrying a distinct piece of information (purpose, exclusion, return, usage trigger, caveats), with the core action front-loaded. No filler or redundancy.

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

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

For a two-parameter bulk mutation with a fully covered schema, the description covers purpose, routing, reversibility, and version requirements; the only soft spot is 'Returns: The outcome of the batch,' which is vague. Since no output schema exists, slightly more detail on the result (e.g., per-ID success/failure) would help, but the definition is otherwise 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%: both 'ids' (UUIDs, up to 1000) and 'archived' (true archives, false restores) are fully documented in the schema, and the description's mentions of 'up to 1000' and 'pass archived false to restore' largely restate them. No syntax, ordering, or error-handling detail is added 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 pair (archive or restore) plus the resource (campaigns) and the batch scope (up to 1000 in one call). It explicitly names the sibling it is not (plunk_bulk_delete_campaigns), so an agent can distinguish it from the other bulk campaign 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 explicit when-to-use ('clearing a backlog of finished campaigns out of the way'), explicit when-not ('Not for: Deleting them, which is plunk_bulk_delete_campaigns and cannot be undone'), and the alternative tool by name. Nothing about tool selection is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description earns credit for genuinely new behavioral facts: the operation is atomic, is restricted to draft campaigns only, requires Plunk v0.12+, and prompts for confirmation before running. The confirmation and version gates are not expressible in the annotation set. It stops short of describing partial-failure or error behavior for a large batch.

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 bolded label structure is scannable and front-loads purpose and exclusions before caveats. The 'Returns: The outcome of the batch' line is near-tautological filler, but every other line 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?

For a one-parameter destructive bulk operation with no output schema and rich annotations, the definition supplies the restriction, atomicity, version gate, and confirmation behavior an agent needs before invoking. The only real gap is not indicating what a batch result contains on partial failure, which matters when up to 1000 IDs are submitted.

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 there is only one parameter, with the UUID format, maxItems 1000, and draft-only constraint already documented in the schema. The description adds no format, ordering, or error-handling detail beyond what the schema states, 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 with exact scope: 'Permanently delete up to 1000 draft campaigns in one atomic call.' The atomicity and draft-only qualifiers make it distinguishable from every other campaign sibling 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?

Explicitly names the two nearest alternatives — plunk_delete_campaign for a single campaign and plunk_cancel_campaign for stopping a send — and the 'Use when: Clearing out accumulated drafts' line states the positive trigger. Both the when and the when-not are covered.

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

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

Beyond annotations (which already signal destructiveHint/idempotentHint), the description adds the cascade effect on event histories, the loss of the opt-out record, an interactive confirmation step, and a return value (job id to poll) pointing to plunk_get_bulk_job_status. This is exactly the extra context structured fields 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?

Bold-labeled sections put purpose first and then route usage, return, and confirmation; every sentence carries distinct information with no repetition of the name or title.

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

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

For a destructive bulk mutation with no output schema, the definition covers purpose, the alternative, the async follow-up tool, and the confirmation gate, and the annotations cover the safety profile. 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?

Coverage is 0% and there is one parameter, contactIds, whose meaning is only inferable from its name plus the schema's uuid format/pattern and maxItems. The description echoes the 1000 cap but adds no field-level guidance (e.g., where ids come from, behavior on unknown/duplicate ids), so it neither compensates for the coverage gap nor does poorly.

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 ("Permanently delete up to 1000 contacts and their event histories") that mirrors the schema's maxItems constraint, and directly contrasts with the doing-nothing-else alternative. An agent can place it against plunk_bulk_unsubscribe_contacts and plunk_delete_contact 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?

Contains an explicit "Not for" clause naming the sibling tool (plunk_bulk_unsubscribe_contacts) plus the consequence that selects against it (loses opt-out record), and a "Use when" clause for the positive case. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real behavior: all-or-nothing atomicity (none deleted if any template is referenced), a version prerequisite (Plunk v0.12+), the 1000-item cap, and a confirmation prompt. These are exactly the traits an agent needs before invoking a destructive batch operation and are not derivable from the annotations.

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

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

The labeled sections (Purpose / Not for / Returns / Use when / Note) front-load the critical routing and safety information, and every line is short. 'Returns: The outcome of the batch' is thin filler, but it costs almost nothing.

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

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

For a single-parameter, non-nested tool with no output schema, the description covers purpose, alternative, preconditions, destructive semantics, and failure mode. 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% and there is a single 'ids' parameter, so the schema already documents the UUID format, maxItems 1000, and the referenced-template failure condition. The description restates the cap and the failure mode but 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 specific verb (permanently delete), resource (templates), and scope (up to 1000 in one atomic call). It also explicitly names the sibling it is not for (plunk_delete_template), so an agent can route between the two 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?

Provides explicit when-to-use ('clearing out many templates at once, typically after an audit') and an explicit when-not-to-use with the alternative named ('Not for: A single template — plunk_delete_template is clearer'). Nothing is left to inference.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is partly structured. The description adds real value beyond them by disclosing that execution histories are destroyed with the workflows, the Plunk v0.12+ prerequisite, and that it asks for confirmation before running.

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 tightly grouped under labeled sections, each sentence carrying distinct information (scope, alternative, return, trigger, prerequisites). The label-heavy formatting is slightly verbose but wastes no content.

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

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

For a one-parameter destructive tool with no output schema, the description covers scope, alternative, prerequisites, confirmation behavior, and what gets destroyed. The 'Returns: The outcome of the batch' line is vague, but return detail is not strictly required here.

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

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

Schema description coverage is 100% and the single ids parameter is fully documented in the schema (UUIDs, max 1000). The description's 'up to 1000' mirrors the schema's maxItems rather than adding new semantics, 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 (delete), resource (workflows), and scope (up to 1000, including their execution histories). It explicitly names the sibling it is not (plunk_delete_workflow) so an agent can distinguish the bulk case from the single case 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?

Provides an explicit 'Not for' exclusion naming the alternative tool and a 'Use when' condition ('clearing out abandoned automations'). When-to-use and when-not-to-use are both covered, leaving nothing 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 cover the safety profile (not read-only, idempotent, non-destructive). The description adds meaningful behavioral context beyond them: the consent requirement, the 1000-contact ceiling, and that it returns a job id to poll asynchronously via plunk_get_bulk_job_status.

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?

Bolded labels (Purpose, Not for, Returns, Use when) front-load the key facts. Every sentence earns its place; no filler.

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

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

For a single-param async bulk mutation with no output schema, the description supplies the async follow-up (poll job status), consent constraint, and limit. Nothing essential 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?

Only one parameter with 0% schema description coverage, so the description must compensate. It indicates the parameter is a list of existing contacts with a 1000-item limit, but adds nothing about UUID format or behavior on invalid/ineligible ids.

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

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

States a specific verb (subscribe), resource (contacts), scope (bulk, up to 1000 existing contacts), and effect (opt back in to marketing email). Clearly distinguishes from the sibling plunk_bulk_unsubscribe_contacts and plunk_subscribe_contact.

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?

Has explicit 'Use when' (correcting mistaken mass unsubscribe, migrating consent) and 'Not for' (reversing self-chosen unsubscribes) guidance, giving both positive and negative selection criteria.

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-readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds genuinely non-obvious traits: it returns a job id for polling via plunk_get_bulk_job_status, and it prompts for confirmation before running. It stops short of stating whether an unsubscribe is reversible or how partial failures are handled.

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?

Labeled sections (Purpose / Not for / Returns / Use when / Note) with the key routing information front-loaded. No sentence is redundant and each block earns its place.

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

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

With no output schema, the description correctly covers the return contract (job id + the polling tool) and the confirmation behavior, and annotations cover the mutation profile. An agent has everything needed 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?

The single parameter has 0% schema description coverage, so the description must carry the load. It restates the 1000-item cap that already lives in the schema's maxItems, but adds nothing about the required contactIds format (UUIDs), ordering, or behavior for unknown/nonexistent ids. Partial compensation 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 ('opt up to 1000 contacts out of marketing email') with the scale bound included, and explicitly names the operation it is not ('Deleting them, which is plunk_bulk_delete_contacts'). An agent can distinguish this from plunk_bulk_delete_contacts and plunk_unsubscribe_contact 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 an explicit exclusion ('Not for: deleting') with the alternative tool named, plus concrete when-to-use scenarios ('honouring a batch of opt-out requests, or suppressing a cohort'). Nothing about tool selection is left to inference.

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

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

Annotations already declare destructive=true and idempotent=true, but the description goes further, disclosing exactly what stops (contacts halt mid-flow, scheduled steps do not run) and that confirmation is requested. This is the kind of side-effect detail 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?

Bold-labeled, front-loaded sections let an agent scan purpose, exclusions, return, and side effects in order. Each line earns its place with no redundancy or filler.

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

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

Despite having no output schema, the description discloses the return value ('number of executions cancelled') and covers destruction semantics, prerequisites, and pre-execution confirmation. 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% for the single 'id' parameter (Workflow UUID), so the schema already carries the parameter meaning. The description adds no format or constraint detail beyond it, which makes the baseline 3 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 with explicit scope ('Stop every in-flight run of a workflow at once'), making the bulk nature of the operation unmistakable versus the singular plunk_cancel_workflow_execution sibling. It also names the sibling it is not by routing agents to plunk_update_workflow for the adjacent concern.

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 'Use when' and 'Not for' conditions, and names the concrete alternative (plunk_update_workflow) with the reason to prefer it ('contacts will keep entering after this'). An agent has a complete decision rule without 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 declare destructiveHint=true and idempotentHint=true, but the description adds behavior they cannot express: cancellation is partial (only unreached recipients stop, delivered mail cannot be recalled) and on v0.15+ the campaign reverts to an editable draft that can be fixed and resent. That post-state information and the v0.15+ version caveat are exactly the extra context that annotations omit.

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?

Bold-labelled sections are front-loaded and easy to scan, and every section is relevant. Minor redundancy: the recall limitation appears twice, once in Purpose ('Mail already delivered cannot be recalled') and again in Note ('delivered mail cannot be recalled'), which is a small but real duplication in a short description.

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

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

For a single-parameter mutation with no output schema, the description covers purpose, exclusion, expected return (confirmation of cancellation), triggering conditions, and the important partial-effect and draft-reversion behaviors. An agent has everything needed to decide and call correctly.

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

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

There is a single parameter (id) with 100% schema description coverage ('Campaign UUID'), so the schema already carries the semantics. The description adds no format, sourcing, or lookup guidance beyond what the schema provides, which is the baseline-3 case 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?

States a specific verb+resource ('Stop a scheduled or in-flight campaign') and immediately bounds the scope with 'Mail already delivered cannot be recalled.' It also explicitly distinguishes itself from the sibling that removes a campaign entirely (plunk_delete_campaign), so an agent can route without inspecting either schema.

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

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

The 'Not for' line names the alternative tool (plunk_delete_campaign) and the 'Use when' line gives two concrete triggering conditions (send started in error, scheduled send should no longer happen). Both when-to-use and when-not-to-use are present, leaving nothing 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 destructiveHint=true and idempotentHint=true, but the description adds a genuinely non-derived consequence: 'Mail already sent cannot be recalled' — it scopes exactly what cancelling does and does not undo. It also states the return shape ('Confirmation of the cancellation'), which the absence of an output schema makes valuable.

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 labeled blocks, each one sentence, front-loaded with purpose and then exclusions. No filler and every line 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?

For a 2-parameter mutation with full schema coverage and no output schema, the description covers purpose, alternatives, trigger conditions, irreversibility, and return expectation. 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% and both parameters (id as Workflow UUID, executionId as Execution UUID) are self-documented. The description adds no format or relationship guidance beyond the schema, 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?

The description gives a precise verb+resource+scope: 'Stop one contact's run of a workflow.' The 'Not for' line names the two confusable siblings (plunk_cancel_all_workflow_executions and plunk_update_workflow), so an agent can disambiguate the singular-vs-global-vs-config distinction 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/when-not guidance: the 'Not for' section routes to the two alternative tools, and 'Use when' enumerates concrete triggers (replied, unsubscribed, entered by mistake). Nothing about tool selection is left to inference.

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

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

Annotations already establish it as a mutation (readOnlyHint=false), idempotent, and non-destructive. The description adds real value: it only applies to DYNAMIC segments, it forces immediate re-evaluation versus waiting for the normal refresh, and it returns the recomputed state. It stops short of stating cost/latency or failure modes for STATIC segments, but adds meaningful context beyond the annotations.

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

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

Bold-header structure front-loads purpose, exclusion, return, and trigger, with no filler sentences. Slightly heavy on formatting scaffolding for such short content, but every line earns its place.

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

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

For a single-parameter action tool with no output schema, the description covers purpose, the closest alternative, the return value, and the triggering condition. An agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100% with a single documented 'id' (Segment UUID) parameter, so the schema carries the semantics. The description adds nothing about the id beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb (recompute/force re-evaluate) and resource (segment), and narrows scope to DYNAMIC segments. It explicitly differentiates from the sibling plunk_refresh_segment_count, so an agent can pick between them 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?

The 'Use when' clause gives an explicit trigger (contacts or events changed and the segment must be current before sending), and the 'Not for' clause names the cheaper alternative and when to prefer it. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already disclose non-read-only, non-idempotent, non-destructive, open-world. The description adds genuinely useful behavior beyond that: the call only produces a draft and never sends, and delivery requires a separate confirmed step. It does not cover auth/domain-verification prerequisites or side effects like audience-count freezing, so a 4 rather than 5.

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

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

Bold-labeled sections (Purpose, Not for, Returns, Use when, Note) are front-loaded and scannable. Every line earns its place, with no redundant restatement of the name or schema.

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

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

With 11 parameters and no output schema, the description still names the return (created draft with id) and explains the audience-branch complexity. It leaves the non-audience parameters undocumented in prose, but the schema descriptions and enum labels cover much of that, making the definition nearly complete.

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

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

Schema coverage is only 45%, so the description carries extra burden. It usefully explains the audienceType branches (ALL/SEGMENT/FILTERED, segmentId for SEGMENT, inline audienceCondition for FILTERED), which is the hardest part of the schema, but adds nothing for name/subject/body/type/description/replyTo/fromName. Partial compensation for the coverage gap lands at 3.

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

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

States a specific verb+resource ('Create a campaign as a draft') with an explicit scope boundary ('It is never sent by this call'). It names the sibling it is not (plunk_send_transactional) and contrasts campaign vs one-off message, so an agent can distinguish it from the many other campaign 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 'Not for' clause routes the transactional case to plunk_send_transactional, and 'Use when' gives the composing-a-newsletter context. It also flags that sending is a separate, confirmed step, closing the obvious follow-up ambiguity.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so 'safe to call twice' largely restates structured data. The description still earns credit for genuinely new behavior: the upsert on existing email and server-side email normalization (case/whitespace) on Plunk v0.12+.

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

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

Five short labeled lines, front-loaded with Purpose and Not-for, then Returns, Use-when and Note. Every sentence carries information an agent needs; no padding.

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

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

With no output schema, the description usefully states the return value ('the created or updated contact'), and it covers the upsert, the bulk alternative and normalization. The only remaining gap is semantics for the nested `data` object and the `subscribed` flag.

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

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

Schema coverage is only 33%: only `data` has a description (with an example), while `email` and `subscribed` are undocumented. The description adds real meaning for `email` via the normalization note, but leaves `subscribed` and the custom-field semantics of `data` unexplained, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource (create a contact) plus the critical upsert behavior — it updates when the email already exists. It also names the sibling it is not (plunk_import_contacts), so an agent can route correctly 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 'Not for' clause names the alternative tool for bulk creation, and 'Use when' states both selecting conditions (adding a single person, or ensuring one exists before acting on them). Nothing is left to inference.

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

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

Annotations declare the write/non-idempotent/open-world profile, but the description adds real behavioral context beyond them: DYNAMIC re-evaluates continuously so membership self-adjusts, DYNAMIC requires a condition, and trackMembership emits entry/exit events that workflows can trigger on. It also states the return value (segment with id), which is useful since no output schema exists.

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?

Bolded section labels (Purpose/Not for/Returns/Use when/Note) front-load the most important information, and each sentence earns its place with no filler. Structure is immediately scannable for an agent deciding whether to call it.

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

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

For a 5-param tool with 40% schema coverage and no output schema, the description covers the mode semantics, the required-condition constraint, tracking behavior, and the return shape. It does not explain the nested condition/filter/groups structure, but that complexity lives in the schema and is minor against otherwise strong coverage.

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

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

Schema description coverage is 40%, so the description must carry weight, and it does for the non-obvious params: it explains the DYNAMIC/STATIC meaning of type, that condition is required for DYNAMIC, and what trackMembership does. The remaining params (name, description) are self-evident and left to the schema, which is acceptable.

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

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

States a specific verb and resource ("Create a reusable audience") and immediately disambiguates the two modes: DYNAMIC auto-re-evaluates its filter, STATIC holds manual membership. It also names the sibling it is not by pointing to plunk_create_campaign for one-off audiences, so an agent can distinguish it 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?

"Use when" gives the positive condition (audience will be reused, or user wants it visible in the dashboard) and "Not for" explicitly names the alternative tool and its inline audienceType FILTERED mechanism for one-off sends. When, when-not, and the alternative are all stated outright.

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/not-destructive/not-idempotent/openWorld profile, and the description adds real value beyond them: templates become referenceable by id from sends, campaigns and workflow steps, and the call returns the created template with its id. It omits auth/verification requirements and failure behavior, so it falls short of a 5.

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

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

Four labeled sections (Purpose, Not for, Returns, Use when) in a few short sentences, with purpose and the exclusion front-loaded. Every sentence carries distinct information; nothing is redundant.

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?

Annotations carry the safety profile and the description states the return shape ('the created template including its id'), so the return side is covered without an output schema. However, for an 8-parameter create tool the description leaves most parameter semantics undocumented, which is a real gap 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?

There are 8 parameters with only 25% schema description coverage, and the description explains none of them — not 'type' (the one enum: TRANSACTIONAL/MARKETING/HEADLESS), not 'replyTo'/'fromName'/'description', and not the required-vs-optional split. With low schema coverage the description was expected to compensate and does not.

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 reusable email template') plus the reason it exists — sends, campaigns, and workflow steps reference it by id. This cleanly separates it from sibling mutations like plunk_update_template, plunk_duplicate_template, and plunk_get_template.

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 and when not to use this tool ('A one-off email. plunk_send_transactional takes an inline subject and body'), then gives the positive selection condition ('The same email will be sent more than once, or a workflow step needs something to point at'). Nothing is left to inference.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds genuinely useful context beyond them: the created workflow is not usable until steps and transitions are added, and it returns an id. It does not mention permissions or rate limits, so not a 5.

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

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

Four short labeled blocks, purpose first, no filler sentences. The bold headers add a little markup overhead but each section 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?

For a creation tool with no output schema, the description covers the creation scope, the mandatory follow-up calls, and the returned id — everything an agent needs to sequence the workflow-building flow 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 only 40% across 5 parameters, and the description supplies no parameter-level meaning at all — name, enabled, description and allowReentry are never explained, leaving half the inputs undocumented in both places. The required 'eventName' trigger concept appears in the title sentence but is still anemic given the coverage gap.

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

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

States a specific verb+resource ('Create a workflow with its trigger') and immediately scopes the outcome ('Steps and transitions are added afterwards'), which distinguishes it from plunk_add_workflow_step and plunk_add_workflow_transition 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 'Not for' and 'Use when' sections, plus a named alternative flow (add steps, connect them, then enable). The agent knows both when to call this and when it is insufficient on its own.

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 permanence is partly covered. The description adds non-obvious consequences beyond the annotations: that deleting a sent campaign discards performance history, and that cancellation preserves history instead. It stops short of auth/permission requirements.

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

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

Bold-labeled sections are front-loaded (Purpose, Not for, Returns, Use when) with no filler sentences. Every line carries decision-relevant information.

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

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

With no output schema, the description supplies the return contract ('Confirmation of the deletion') and the destruction semantics. For a single-param delete tool, 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?

Only one parameter and schema description coverage is 100% ('Campaign UUID'), so the schema fully carries the semantics. The description adds nothing about the id format, 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 ('Permanently delete one campaign and its record') and explicitly contrasts itself with the sibling cancel tool. An agent can distinguish it from plunk_cancel_campaign and plunk_bulk_delete_campaigns 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 'Not for' exclusion naming the alternative (plunk_cancel_campaign) and the condition that selects it, plus a positive 'Use when' case for unwanted drafts. This is the full when/when-not/alternative pattern.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds behavior beyond them: that event history is destroyed alongside the contact and that the opt-out record is lost so a later import can re-add the person. That downstream consequence is exactly the kind of context annotations cannot convey.

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

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

Four short labeled blocks, front-loaded with purpose, then exclusions, return, and use case. Every sentence earns its place with no filler.

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

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

For a single-parameter destructive tool, the description covers purpose, exclusions, the return confirmation, and the triggering scenario. No output schema exists, but the return value is described in one line, leaving nothing an agent needs 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?

Only one parameter (id) and schema description coverage is 100%, so the schema fully documents it. The description adds no additional semantics about the identifier, which is the correct baseline when the schema does the work.

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 one contact and their event history') and scopes it beyond the tool name by noting event history is included. It also distinguishes itself from the closest sibling, plunk_unsubscribe_contact, 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 provides a 'Not for' exclusion naming the alternative tool and the reason (deleting loses the opt-out record), plus a 'Use when' condition (data-deletion request). When-to-use, when-not-to-use, and the alternative are all stated.

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

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

Annotations already carry the safety profile (destructiveHint=true, idempotentHint=true), so the bar is lower; the description still adds genuinely new context: the blast radius ('from every contact', values included), a downstream side effect on segments, and an expected return value.

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 bold-labeled blocks, front-loaded with purpose, each sentence carrying distinct information (scope, alternative, return, precondition). No filler or repetition.

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

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

For a one-parameter destructive tool with no output schema, the description covers what it does, what it is not for, the return value, and the precondition check — everything an agent needs to call it correctly and safely.

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 a single documented parameter, so baseline 3 applies. The description implies the 'field' argument is a field key/name but adds no syntax, casing, or ID-vs-name guidance beyond what the schema supplies.

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

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

The description states a specific verb and resource ('Remove a custom field and its values from every contact') and immediately distinguishes it from the closest sibling by naming plunk_update_contact for per-contact clearing. An agent can tell it apart from plunk_list_contact_fields, plunk_get_field_usage, and plunk_delete_contact with no schema inspection.

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-not ('Not for: Clearing it on one contact — pass null for that key via plunk_update_contact instead') paired with an explicit when ('A field is genuinely obsolete'), plus a named prerequisite (plunk_get_field_usage) and a stated exclusion scenario (segments filtering on it will stop matching).

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 openWorldHint=true, but the description adds substantial value beyond them: no undo short of re-adding and re-verifying DNS, nothing can be sent from the domain afterward, a confirmation prompt occurs, and the admin-role check is skipped with an API key. These are important operational behaviors not captured by 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 front-loaded with Purpose and immediately followed by exclusions, return value, usage condition, and a critical note. Every sentence adds distinct, actionable information without redundancy.

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

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

There is no output schema, so the description appropriately explains the return value ('Confirmation of removal'). Combined with the irreversible effect, confirmation prompt, and API-key auth nuance, an agent has everything needed to invoke this destructive tool correctly.

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

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

Schema description coverage is 100% and the single parameter 'id' is clearly documented in the schema as 'Domain UUID'. The description adds no further parameter-level meaning, which is acceptable here but does not exceed the baseline for fully covered schemas.

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

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

The description states a specific verb and resource ('Remove a sending domain from the project') and explicitly distinguishes the operation from temporary pausing, which is the closest adjacent concept. It also indirectly differentiates from sibling tools such as plunk_add_domain by noting a shared API-key behavior.

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

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

It gives explicit when-to-use guidance ('A domain is genuinely retired') and when-not-to-use guidance ('Not for: Temporarily pausing sending'), plus the irreversible consequence of using it. The agent does not need to infer the appropriate context.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-structured consequences — that workflows and segments triggering on the event will stop working and that the deletion is project-wide rather than contact-scoped — plus the return shape ('confirmation of the deletion') for a tool with no output schema. It stops short of describing irreversibility or recovery, keeping it out of 5 territory.

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 labeled sections, each one sentence, with purpose and the destructive consequence front-loaded before the prerequisite. No filler, no repetition of the title.

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

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

For a single-parameter destructive tool with no output schema, it covers purpose, exclusions, side effects, prerequisite check, and return confirmation. The only omission is any guidance on the input format or on error behavior when the event name does not exist.

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?

Only one parameter exists and schema description coverage is 0%, so the description must carry the meaning. It implies the parameter is an event name via 'an event name was created in error' and the project-wide scope, but adds no format, casing, or lookup guidance (e.g., that names come from plunk_list_event_names). Baseline 3 for a single self-describing parameter with a small gap.

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

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

States a specific verb (delete) and resource (event) with explicit scope: the event and its recorded history are removed from the whole project. It also names what it is NOT (removing one contact's event record), which cleanly separates it from plunk_get_contact_events and other event siblings.

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

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

The 'Use when' section gives a concrete trigger (an event name was created in error and nothing references it) and an explicit pre-flight step (check plunk_get_event_usage first). The 'Not for' line rules out the adjacent per-contact use case, so an agent has both inclusion and exclusion criteria.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: permanence, that contacts are unaffected, and the downstream side effect that campaigns targeting the segment lose their audience. It does not quantify scope (e.g., member count impact) but the key risk is disclosed.

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

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

Four short labeled blocks, front-loaded with purpose and counter-indication, zero filler sentences. Every line earns its place.

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

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

For a single-parameter destructive tool with no output schema, the description covers purpose, exclusions, the return value ('Confirmation of the deletion'), and side effects. An agent has everything needed to decide and 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?

Only one parameter, and schema description coverage is 100% ('Segment UUID'), so the schema fully documents it. The description adds no format or syntax detail beyond the schema, which is the correct baseline when the schema already does the work.

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 segment') and immediately clarifies scope with 'The contacts themselves are untouched.' It also names the sibling it is not, so an agent can distinguish it from plunk_remove_segment_members 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?

Explicit 'Not for' section names the alternative tool and the condition that selects it, and 'Use when' gives the trigger plus the consequence (campaigns lose their audience). Nothing is left to inference.

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

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

Annotations already declare destructiveHint/idempotentHint, but the description goes further: it states the deletion is permanent (no undo), that the call fails when a campaign or workflow still references the template, and that it returns a confirmation. The referential-integrity failure mode is not derivable 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 purpose, then organized into short labeled sections with no filler; every line carries information. The bold-header scaffolding is slightly heavier than needed for four short lines but 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?

For a one-parameter destructive tool with no output schema, everything needed is present: what it destroys, how it differs from the bulk variant, what blocks it, and what it returns. The safety profile is covered by annotations and reinforced by the description.

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?

Only one parameter (id) and schema description coverage is 100%, so the schema already documents the UUID argument. The description adds no parameter-level meaning, which matches the baseline 3 for a fully documented single-param tool.

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 clear scope: "Permanently delete one template." It explicitly distinguishes itself from the sibling plunk_bulk_delete_templates, so an agent can route correctly 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?

Provides an explicit "Not for" exclusion naming the alternative (plunk_bulk_delete_templates, up to 1000 atomic), a positive "Use when" condition, and a named prerequisite check (plunk_get_template_usage) that determines whether the call succeeds.

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 bar for extra value is met by the description spelling out the destruction footprint — steps, execution history, and the fact that contacts partway through are dropped. That is meaningful context beyond the boolean hint. It stops short of describing return shape or any permission requirements, so not a full 5.

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

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

Four labeled, front-loaded sentences (Purpose, Not for, Returns, Use when) with zero filler. Each line contributes either scoping, an alternative, or an operational consequence.

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

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

For a single-parameter deletion tool with no output schema, the definition covers purpose, the destructive scope, the reversible alternative, and a minimal returns statement. 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% and there is only one parameter (id, a workflow UUID), so the schema fully carries this burden. The description adds no syntax or format detail beyond what the schema provides; 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?

States a specific verb and resource ("Permanently delete a workflow") and immediately enumerates the scope of what is deleted: its steps and its execution history. This distinguishes it from siblings like plunk_bulk_delete_workflows, plunk_delete_workflow_step, and plunk_update_workflow 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?

Explicitly names the alternative and the condition that selects it: "Not for: Stopping it temporarily — set enabled to false via plunk_update_workflow, which is reversible." The "Use when" clause adds the positive trigger ("an automation is genuinely retired"), so both the when and the when-not are covered.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, but the description adds non-obvious behavioral consequences the annotations cannot express: transitions into and out of the step are left dangling and contacts will stall there unless the graph is reconnected. That is exactly the kind of context a mutating tool needs.

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

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

Labelled sections (Purpose/Not for/Returns/Use when/Note) are front-loaded with the routing decision and end with the only cautionary detail. Every sentence carries distinct information; none restates the name or title.

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

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

For a two-parameter destructive tool with no output schema, the description covers purpose, alternatives, return value ('Confirmation of the deletion') and the post-deletion consequence. An agent has everything needed to call it correctly and to warn the user about dangling transitions.

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 both required parameters ('id' = Workflow UUID, 'stepId' = Step UUID) fully documented in the schema. The description adds no syntax or format 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?

The first line states a specific verb+resource ('Remove one step from a workflow') and the 'Not for' line names the sibling it is not (plunk_delete_workflow, which deletes the whole workflow). An agent can distinguish it from plunk_delete_workflow, plunk_delete_workflow_transition and plunk_update_workflow_step 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 ('Removing a step from the graph'), explicit when-not ('Deleting the whole workflow, which is plunk_delete_workflow'), and a remediation workflow (re-fetch and reconnect the graph). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds non-obvious consequence context — that removing a transition can strand downstream steps and the graph should be re-checked — which is real value beyond the annotations, though it doesn't address auth or reversibility.

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 exclusions, then usage, in a scannable labeled structure. 'Returns: Confirmation of the deletion' is mildly redundant filler, but nothing else wastes space.

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

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

For a two-param destructive mutation with full annotation coverage and no output schema, the description supplies everything needed: what it acts on, what it is not, and the downstream hazard to verify.

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

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

Schema coverage is 100% with both id and transitionId documented as UUIDs, so the description correctly does not need to restate them. It adds no syntax or identifier guidance 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 ('Remove a connection between two steps') and explicitly names the sibling it must not be confused with (plunk_delete_workflow_step). An agent can distinguish this from the step-deletion tool 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?

Explicit 'Not for' exclusion plus a 'Use when: Rerouting a workflow' trigger, and it narrows the alternative to a named sibling tool rather than leaving it to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true. The description adds genuinely useful context beyond them: the copy is a fresh, editable draft with its own id, and duplicating is non-destructive to the original. It does not discuss permissions or rate limits, but the annotation coverage keeps the bar low.

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 labeled, front-loaded sections (Purpose, Not for, Returns, Use when), each one sentence with no filler. The negative guidance and return format are surfaced before an agent would need to dig.

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

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

There is no output schema, so the 'Returns' note (the new draft including its own id) usefully covers the response. For a low-complexity, one-parameter tool the definition supplies purpose, exclusions, and return shape, leaving no material 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?

A single parameter (id) with 100% schema coverage, so the schema already carries the semantics; baseline is 3. The description adds no syntax or format detail for the id and only implicitly frames it as the source campaign, which the schema title already conveys.

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

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

States a specific verb (copy/duplicate) and resource (campaign), and specifies what is carried over: content and audience settings. It distinguishes itself from sibling write operations like plunk_create_campaign (new) and send operations like plunk_send_campaign (re-send), so an agent can select it without opening another schema.

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

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

The 'Use when' and 'Not for' clauses give clear positive and negative guidance ('Basing a new send on one that worked' vs 'Sending the same campaign again to the same people'). It stops short of naming the alternative tool (e.g. plunk_send_campaign) explicitly, so it is clear context rather than full when/when-not/alternatives routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the copy is 'independent' and includes 'body and all', and it returns a new copy with its own id. It does not cover permissions or rate limits, so not a 5.

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

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

Four labeled lines, each front-loading a distinct concern (purpose, exclusion, return, usage), 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?

Despite no output schema, the description states the return value ('The new copy including its own id'), and the annotations carry the mutation/safety profile. An agent has everything needed to invoke this one-parameter duplication 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% for the single 'id' parameter, so the schema already documents the input fully. The description adds no format or syntax detail for 'id' beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('Copy a template, body and all, into a new independent template') and explicitly names the sibling it is not for (plunk_update_template), so an agent can distinguish it 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?

It gives an explicit exclusion ('Not for: Editing the original, which is plunk_update_template') and an explicit use case ('Building a variant of something that works, without risking the version already in use'), leaving nothing 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 only cover the safety profile (non-destructive write, not idempotent). The description adds genuinely non-obvious behavioral facts: version prerequisite (Plunk v0.11+), and that the copy lands disabled with no execution state so it cannot start sending by accident. That last detail is exactly the kind of state default an agent could not 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?

Bold-labeled sections (Purpose / Not for / Returns / Use when / Note) with the core purpose front-loaded and no redundant prose. Every line carries information the agent needs.

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

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

Although there is no output schema, the description covers the return value ('the new copy including its own id'), the safety default, and the version requirement. Nothing needed to invoke a single-parameter duplication 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?

Only one parameter (id) and schema coverage is 100%, so the schema already documents it as 'Workflow UUID'. The description adds no syntax or format meaning beyond that, so the baseline 3 applies; there is simply no room for added value here.

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 ('copy a workflow with all its steps and transitions into a new one') and explicitly names the adjacent tool it is not (plunk_update_workflow). An agent can distinguish it from plunk_create_workflow and plunk_update_workflow 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?

Provides both a 'Not for' exclusion pointing at plunk_update_workflow and a 'Use when' condition ('reworking an automation without disturbing the one currently running'). This is the exact when/when-not/alternative structure that makes selection unambiguous.

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=true, idempotent=true, openWorld=true and non-destructive, so the safety profile is covered. The description adds useful behavior beyond that: the feed is ordered newest-first and returns per-event records rather than aggregates. It stops short of describing page size, cursoring, or retention windows for the feed.

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

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

Four short bolded sections front-load purpose, exclusions, return shape and usage. No filler sentences, and the routing information (which sibling to use instead) appears early rather than buried.

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

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

There is no output schema, and the description's 'Returns: a page of individual activity records' adequately sets expectations for a list tool. Safety, scope and alternatives are all covered; the only residual gap is pagination mechanics for the page/limit parameters.

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

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

Schema coverage is only 33% (only the 'type' param is documented), so the description carries real burden. It partially compensates by listing activity categories that map onto the type filter, but gives no example token format, and page/limit are left entirely unexplained beyond the implied newest-first paging.

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 (read the project activity feed) and enumerates the record types (sends, opens, clicks, bounces, complaints) plus ordering (newest first). It explicitly names the two sibling tools that cover adjacent ground, so an agent can distinguish it without opening a schema.

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

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

The 'Not for' section names concrete alternatives (plunk_get_activity_stats for totals, plunk_get_campaign_stats for one campaign) and the 'Use when' section states the selecting condition: investigating what happened to a specific contact or window rather than overall volume. Both when-to-use and when-not-to-use are explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds the aggregation grain and project-wide scope, which are genuine behavioral facts beyond the annotations, though it does not discuss return shape or refresh/recency of the counts.

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 labeled blocks (Purpose / Not for / Returns / Use when) with no filler, and the routing constraint is front-loaded before the return summary. 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?

For a zero-parameter, no-output-schema aggregate tool the description covers purpose, routing, and return grain, which is close to complete. A brief note on what the counts include or their freshness window would close the remaining gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameters means no risk of mis-invocation through unclear arguments.

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 ('aggregate counts across the activity feed — totals per activity type for the project'), including the aggregation grain. It also explicitly names what it is not (plunk_get_campaign_stats, plunk_get_analytics_timeseries), so an agent can discriminate it from siblings 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?

Explicit 'Not for' entries with sibling tool names plus a 'Use when' clause ('project-wide numbers rather than individual events'). Both the when and the when-not are stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety and repeatability are covered for the agent. The description adds only that results are time-bucketed series, with no mention of default interval behavior, range limits, or aggregation windows. Some added context, but not rich 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?

Labelled sections (Purpose / Not for / Returns / Use when) with the scope statement front-loaded and zero redundant sentences. Every line earns its place.

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

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

For a read-only analytics tool with no output schema, the definition covers purpose, exclusions, and use conditions well; the 'Returns: Time-bucketed metric series' line is thin on which metrics are included and what the default bucketing is, leaving a small gap an agent might need.

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

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

Schema coverage is 67%: from/to carry ISO-date descriptions, and interval is a self-documenting enum, so the schema largely carries the load. The description never mentions the parameters, adds no format or default guidance (e.g., default interval, max range) that the schema lacks.

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 (email metrics bucketed) and resource (analytics over time), and explicitly distinguishes itself from plunk_get_campaign_stats and plunk_get_top_campaigns by shape of output (trend vs. total vs. ranking). An agent can route 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?

Contains both a 'Not for' exclusion naming the two relevant siblings and a 'Use when' condition (direction/trend questions: rising opens, bounce spikes, a given week). The selection logic is fully spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuinely useful behavior beyond that: the polling nature of the call and the shape of the result (state, progress, errors), which matters since no output schema exists. It stops short of rate-limit or eventual-consistency details, but the added context is substantial.

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

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

Four short labeled lines, each front-loaded with the key information. No filler; the purpose, exclusion, return shape and trigger each appear once.

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

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

For a single-parameter read-only polling tool with no output schema, the description covers identity, sibling routing and return shape adequately. Only the jobId semantics and any polling cadence guidance are missing.

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

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

Schema description coverage is 0% and the single parameter (jobId) is never mentioned in the description. The name is largely self-explanatory, but with one required parameter undocumented, the description does not compensate for the coverage gap and sits at 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 (check a bulk subscribe/unsubscribe/delete job's progress) and explicitly scopes what it is not for (import jobs). An agent can distinguish it from the many bulk operation siblings without opening the schema.

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

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

Gives an explicit exclusion with the correct alternative ('Not for: Import jobs, which are polled with plunk_get_import_status') and an explicit trigger ('Use when: After starting a bulk operation, to confirm it completed'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds useful scope context — that the full record including audience configuration is returned — but says nothing about failure modes (e.g. behavior for an unknown id) or that responses are unsaved drafts versus sent campaigns.

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 labelled, front-loaded blocks with zero filler; the actionable routing information (what it is, what it is not, what it returns, when to use it) is prioritized in that order. 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?

With no output schema, the description correctly steps in to describe the return payload (full campaign record plus audience configuration and status). For a single-parameter read-only tool with full annotation coverage, nothing an agent needs in order 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?

There is a single parameter with 100% schema description coverage ('Campaign UUID'), so the schema already carries the semantics and the baseline is 3. The description adds no format or sourcing detail 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 (fetch) and resource (one campaign) and enumerates the fields returned (subject, body, sender, audience configuration, status). It explicitly distinguishes itself from the sibling stats tool, so an agent can route between them without opening either schema.

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

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

Contains both an explicit exclusion ('Not for: how it performed after sending — that is plunk_get_campaign_stats') and a positive use case ('Use when: reviewing a draft before sending, or checking who a campaign is configured to reach'). Nothing about when to pick this tool is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds the comparative scope and roughly what is returned ('per-campaign statistics across the selected range'), but discloses no auth needs, pagination, or result-size behavior beyond that.

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

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

Bold-labeled sections are front-loaded and each sentence carries routing or scope information with no filler. The formatting is slightly heavier than needed for four short lines, but nothing is wasted.

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

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

For a read-only analytics tool with no output schema, the description tells the agent what the call returns, when to choose it, and which sibling to avoid. The main gap is the silent interval parameter, which mildly undercuts completeness for a time-bucketed breakdown.

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

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

The description says nothing about the to/from window or the interval parameter, so the 'Returns: across the selected range' phrasing is the only implicit nod to parameters. With schema coverage at 67% and the interval enum carrying no description, the description fails to compensate for the undocumented portions.

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+resource ('comparative campaign statistics across the project, broken down for analysis') and explicitly distinguishes itself from the closest sibling, plunk_get_campaign_stats, 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?

It contains both a 'Not for' exclusion naming the alternative tool and a 'Use when' positive trigger ('comparing campaigns against each other rather than reading one in isolation'). This is exactly the when/when-not/alternative structure that earns a top score.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds value beyond them by disclosing the return shape (counts and rates) and by clarifying that bounce/complaint counts are aggregates whose underlying addresses require a different tool. It does not mention auth or rate limits, keeping it short of a 5.

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

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

Bolded labeled sections (Purpose / Not for / Returns / Use when / Note) front-load the essential purpose and make routing information scannable. Every sentence carries distinct information with no filler.

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

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

With no output schema, the description compensates by naming the returned metrics and their form (counts and rates). Combined with the sibling routing and the recipient-count caveat, an agent has everything needed to select and call this tool correctly.

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

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

Schema description coverage is 100% for the single 'id' parameter ('Campaign UUID'), so the schema carries the semantics. The description adds no syntax or format detail beyond it, which matches the baseline 3 for a fully documented 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+resource (delivery/engagement figures for one campaign) and enumerates the exact metrics returned (sends, opens, clicks, bounces, complaints). It explicitly distinguishes itself from plunk_get_campaign and plunk_get_top_campaigns by name.

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

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

Contains both a 'Not for' clause naming the correct alternatives and their domains, and a 'Use when' clause keyed to the user intent ('how a specific campaign performed'). Also routes to plunk_list_campaign_recipients for recipient-level detail. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safe read-only profile is covered. The description adds useful behavioral context by disclosing what the record contains (custom data, subscription state) and that the full record is returned, but says nothing about auth requirements, rate limits, or error behavior when the id is unknown.

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

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

Four short labeled sections, each one sentence, with the purpose front-loaded and the exclusion placed before the returns/usage notes. Every line carries information and nothing is redundant.

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

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

No output schema exists, so the 'Returns' line earns its place by describing the payload, and the description covers purpose, exclusion, and prerequisite for a single-parameter read tool. Nothing an agent needs to select or invoke this tool 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 there is only one parameter ('id', documented as a Contact UUID). The description adds the notion that the id must already be known but contributes no format, sourcing, or validation 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 specific verb (fetch) and resource (one contact by id) and immediately names the scope of what's included — custom data and subscription state. It also explicitly distinguishes itself from the sibling plunk_lookup_contacts, which addresses the most likely confusion.

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 'Not for' section excludes the email-lookup case and names the alternative tool by name, and the 'Use when' section states the prerequisite (you already have a contact id and need the full record). Both when-to-use and when-not-to-use are explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is largely covered. The description's only behavioral addition is that results are returned 'in order'; it says nothing about pagination, limits, or the shape of event records. Consistent with annotations but modest value beyond them.

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

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

Four short labeled lines, each front-loaded and purposeful: purpose, exclusion, return, and trigger condition. No filler, and the exclusion is stated before the use case where it matters.

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

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

With no output schema, the description does tell the agent what comes back ('that contact's event history' in order), which is enough to call it correctly. It stops short of describing event record fields or result volume, a minor gap for a tool with no 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?

Single required parameter with 100% schema description coverage ('Contact UUID'), so the schema carries the load. The description's 'for one contact' scoping adds no syntax or format detail beyond what the schema already provides — 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 — 'List every event recorded for one contact, in order' — and explicitly carves out the sibling situation: delivery activity lives in plunk_get_activity. An agent can distinguish this from plunk_get_activity and plunk_list_events 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?

Has an explicit 'Not for' line naming plunk_get_activity and the condition that routes there, plus a 'Use when' framing the diagnostic scenario (why a contact did/did not enter a workflow or segment). Both when-to-use and when-not are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is covered. The description adds only that it returns aggregate figures; it does not mention auth needs, rate limits, or what dimensions are aggregated. With annotations carrying safety, this is a minimal but acceptable addition.

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

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

Four bolded lines, front-loaded and telegraphic, with no filler. Each line adds purpose, exclusion, return type or trigger.

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?

Simple zero-parameter read tool with rich annotations, so the description is nearly complete. The only gap is that without an output schema, 'aggregate event figures' remains vague about the exact metrics returned; minor for a stats endpoint.

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?

Zero parameters; per rubric baseline is 4. Schema coverage is 100% and there are no parameters for the description to clarify.

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 'Aggregate' and resource 'tracked events', and explicitly distinguishes itself from plunk_get_top_events. However, 'aggregate statistics'/'aggregate event figures' is generic and does not say which statistics, leaving some ambiguity versus the sibling plunk_get_event_usage.

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 'Use when' line gives context (summarising event volume for the project) and a 'Not for' exclusion routing to plunk_get_top_events. This is exactly when-to-use and when-not guidance; other siblings are not excluded, but the primary confusion is handled.

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 still adds value by disclosing the return content (workflows and segments referencing the event) and the impact framing ('what would break'), which helps the agent reason about the result. It stops short of richer context such as result size or truncation 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?

Four labeled sections, each one sentence, front-loaded with Purpose and free of redundancy. Zero waste; every line informs selection or invocation.

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

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

With no output schema, the description supplies the missing return contract ('the workflows and segments referencing this event') and the routing to alternatives. An agent has everything needed to decide when to call it and what to expect back.

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

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

There is one required parameter, eventName, with 0% schema description coverage, so the description must carry the burden. It refers to 'an event name' consistently with the parameter, but adds no format or matching detail (exact vs. partial, case sensitivity, whether the name must already exist). Partial compensation for the coverage gap justifies a baseline 3.

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

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

States a specific verb and resource ('Show where an event name is referenced') and enumerates exactly what counts as a reference: workflows that trigger on it and segments that filter by it. It is immediately distinguishable from sibling analytics tools like plunk_get_event_stats and plunk_get_top_events.

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

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

Explicitly names what the tool is NOT for (firing frequency → plunk_get_event_stats or plunk_get_top_events) and gives a concrete trigger scenario ('Before deleting or renaming an event, to see what would break'). Both the when and the when-not/alternative are stated, leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds only that it returns 'usage figures for this field' — marginally useful context about the nature of the result (population density rather than values), but no detail on shape, cardinality, or cost of the open-world lookup.

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 labeled sections (Purpose / Not for / Returns / Use when) with one sentence each; the key differentiator and the alternative tool are front-loaded and no sentence is redundant.

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

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

For a single-parameter read tool with no output schema, the description covers purpose, exclusion, return nature and decision context adequately. It stops short of describing the returned figures (counts vs. percentages, per-contact breakdown), which is the only remaining gap.

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

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

Schema coverage is 100% with a single documented 'field' parameter, so the schema carries the semantics. The description's references to 'a custom field' and 'this field' add nothing 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+resource ('Report how widely a custom field is populated across contacts') and explicitly names the sibling it is not (plunk_get_field_values), so an agent can distinguish the two without opening either schema.

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

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

The 'Use when' block names two concrete decision contexts (whether a field is worth segmenting on, or safe to delete), and 'Not for' routes away the adjacent tool. Both when-to-use and when-not-to-use are explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully carried by structured data. The description adds only the return semantics ('distinct values'), with no mention of pagination, result caps, or auth requirements; acceptable but adds little 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?

Four labeled, front-loaded fragments (Purpose / Not for / Returns / Use when) with no filler. Every sentence carries distinct information and the routing constraint is placed early.

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

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

For a one-parameter read tool with no output schema, the definition covers purpose, disambiguation from the nearest sibling, and the shape of the return value. Nothing an agent needs to select or 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% with a single required 'field' parameter, so the schema already documents the input. The description reinforces that the field is a custom field name but adds no format, naming-convention, or validation detail 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 (distinct values in one custom field) with a clear scope restriction ('one custom field'). It also explicitly distinguishes itself from the sibling plunk_get_field_usage, 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?

Provides an explicit 'Not for' clause naming the alternative tool (plunk_get_field_usage) and its differing purpose, plus a 'Use when' clause describing the triggering scenario (building a segment filter). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare read-only, idempotent, non-destructive, so safety is covered. The description adds value by disclosing what the call returns (state, progress, errors) — meaningful for a polling tool with no output schema — and by delineating the job-type boundary. It stops short of noting anything about polling cadence or terminal states.

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

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

Four short labeled lines, each earning its place: purpose, exclusion, return shape, trigger. Front-loaded purpose with zero 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?

No output schema exists, and the description compensates by summarizing the return payload (state, progress, errors). Combined with the explicit routing to the sibling status tool, this is nearly complete; only the parameter's origin/format remains 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 0% and there is one required parameter, so the description carries the burden. It implies jobId is the identifier returned by plunk_import_contacts, which is useful, but never names or describes the parameter explicitly, leaving a gap.

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

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

States a specific verb+resource ('check how an import job ... is progressing') and explicitly ties the tool to its producer, plunk_import_contacts. It distinguishes itself from the nearest sibling (plunk_get_bulk_job_status) in the same breath.

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 'Not for' clause naming the alternative polling tool with its job types, plus a clear 'Use when' trigger. An agent can route between import-status and bulk-status polling without inspecting either 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 establish read-only, idempotent, non-destructive, open-world behavior. The description adds a trait the annotations do not: the value is cached for speed, signaling potential staleness, which is genuinely useful for an agent deciding whether to trust the figure.

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

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

Four short labeled sections, purpose front-loaded, every sentence carrying distinct information. The bold-header formatting is slightly heavier than needed for such a small tool but nothing is wasted.

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

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

With no output schema, the description steps in to say the return is a single count, and it covers the no-parameter invocation fully. The one remaining gap is that 'recently' has no defined time window or freshness guarantee, which matters for interpreting a cached number.

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

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

The tool takes zero parameters, so the baseline is 4; there is no argument surface to misdocument. The description correctly notes it returns one count rather than a dimensioned result.

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 output — a single cached count of recent project activity — and explicitly contrasts it with tools that produce breakdowns. It is distinguishable from siblings like get_activity_stats, get_event_stats, and get_analytics_timeseries via the 'no dimensions to slice' framing, though it never names those siblings directly.

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 an explicit 'Use when' (a cheap check of whether anything is happening before deciding what to investigate) and a 'Not for' exclusion (anything requiring breakdown). Clear routing context, but no named alternative tool for when a breakdown is actually needed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the return includes the full filter condition tree, and the recommended scenario is read-before-edit. It does not cover error behavior for a missing/invalid segment id, which keeps it below a 5.

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

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

Four short labeled lines covering purpose, exclusion, return, and trigger. Front-loaded with the purpose, zero filler, and the labeled structure makes scanning trivial for an agent.

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

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

For a single-parameter read tool with no output schema, the description supplies what is needed: what it returns (the full record including the condition tree) and when to use it. Exact response fields remain unspecified, but given the tool's simplicity that is a minor gap rather than a blocker.

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

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

Only one parameter ('id'), and schema description coverage is 100% ('Segment UUID'), so the schema carries the parameter burden. The description adds no format, prefix, or lookup detail beyond the schema. Per the rubric, a 3 is the correct baseline when the schema is complete.

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

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

States a specific verb and resource ('Fetch one segment in full, including its filter condition tree'), which is far more precise than the title 'Get segment'. It also explicitly names the adjacent sibling it is not for (plunk_list_segment_contacts) and, by implication, the summary-list tool. An agent can distinguish it from the other ~10 segment 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?

Provides an explicit 'Use when' scenario (diagnosing why a segment matches, prior to editing its filter) and an explicit 'Not for' exclusion routing to plunk_list_segment_contacts. Both the selection condition and the boundary case are stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value beyond them by disclosing that the response contains the full body/subject and by flagging the cost consideration of fetching bodies individually versus listing. It doesn't cover pagination or size limits, but for a single-record read 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?

Four short labeled sections, each front-loading its point (purpose, exclusion, return, trigger). Every sentence earns its place and the critical exclusion is stated early.

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

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

With one simple required param, no output schema, and annotations covering the safety profile, the description supplies everything needed: what it returns, the alternative, and when to reach for it. Nothing essential is missing.

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

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

The schema has a single parameter ('id', Template UUID) at 100% description coverage, so the schema already carries the semantics. The description adds nothing about the identifier format beyond what the schema states, 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 (fetch) plus the resource (one template) and enumerates what is included: HTML body and subject. It explicitly names plunk_list_templates as the alternative it is not, so an agent can differentiate 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?

The 'Not for' and 'Use when' sections give explicit when/when-not guidance and name the competing sibling (plunk_list_templates) with the condition that selects it. Nothing is left to inference.

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

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

Annotations already establish readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description adds meaningful behavioral context beyond that: the result is a reference graph rather than analytics, which prevents a common misread of a similarly named tool. It stops short of describing result size, pagination, or ordering, so not a full 5.

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

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

Four short labeled blocks that are front-loaded with purpose and each carry distinct information: scope, exclusion, return, and trigger. No redundant restatement of the tool name or annotations.

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

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

No output schema exists, and the description compensates by describing the return set ('the campaigns and workflows pointing at this template'). Combined with the safety annotations and the pre-delete/pre-edit use case, an agent has everything needed to select and call this tool correctly.

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

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

There is a single parameter with 100% schema description coverage ('Template UUID'), so the schema already carries the semantics and a baseline of 3 applies. The description's phrase 'this template' confirms but does not extend the schema's meaning.

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

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

States a specific verb and resource: 'List the campaigns and workflows that reference a template.' It explicitly distinguishes itself from the closest-sounding sibling by naming plunk_get_campaign_stats and clarifying that this reports references, not delivery metrics.

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 'Use when' trigger (before deleting or editing a template, to see what a change would affect) and an explicit exclusion ('Not for: Delivery numbers'), routing the agent to plunk_get_campaign_stats instead. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the ranking/ordering behavior ('leaderboard', 'ordered by performance'), which is genuinely beyond the annotations, but it claims ranking 'across a period' while the schema exposes no period or date parameter, leaving the actual scoping mechanism unexplained.

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

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

Four short labeled blocks, each doing one job, with the core purpose front-loaded. No filler sentences; every line earns its place.

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

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

For a read-only ranking tool with no output schema, the description covers purpose, alternatives and the return shape ('campaigns ordered by performance'). Minor gaps remain: the undefined ranking metric, the unexplained 'period', and the undocumented limit parameter.

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

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

The single 'limit' parameter has 0% schema description coverage and the description never mentions it, so its meaning (how many campaigns are returned, defaults, maximum) is undocumented in both places. A 1-param, low-coverage schema required the description to compensate and it does not.

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 ('Rank campaigns by performance') plus scope ('across a period'), and explicitly contrasts itself with two named siblings via the 'Not for' line. An agent can tell this leaderboard apart from plunk_list_campaigns and plunk_get_campaign_stats 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?

Provides explicit when-to-use ('The user asks what worked best, or you need the strongest performers without fetching every campaign') and explicit when-not-to-use naming the two alternative tools. Routing guidance is unambiguous.

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 fully covered by structured data. The description adds that results are 'ordered by volume,' but does not disclose pagination, the fixed/default time window implied by 'across a period', or result cardinality. Adequate but not rich 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?

Four labeled sections (Purpose, Not for, Returns, Use when) are tightly written and front-loaded, with each sentence earning its place and zero filler.

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

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

For a simple read-only ranking tool the description covers purpose, routing and return ordering well, but it omits any explanation of the limit parameter and the period over which ranking occurs, both of which an agent needs to call it correctly. Since no output schema exists, the return description carries more weight but remains thin.

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

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

The single parameter (limit) has 0% schema description coverage and is never mentioned in the description. Worse, the description references 'across a period' while the schema exposes no time-range parameter, leaving the period semantics unexplained. With low coverage the description should compensate but does not.

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

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

The description states a specific verb and resource with scope: 'Rank tracked events by how often they fired across a period.' It explicitly names siblings it is NOT for (plunk_get_event_stats, plunk_list_event_names), so an agent can distinguish it from the large set of event-related tools 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?

It provides both a 'Not for' exclusion naming the two closest alternatives and a 'Use when' clause giving concrete scenarios ('what your contacts actually do most', 'which events are worth building a workflow around'). When-to-use and when-not-to-use are both explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds genuinely useful behavioral context beyond that: that the payload is a complete graph and that its nodes reference each other by id, which is the reason the read must precede any edit. It does not mention permissions or any size/pagination behavior, keeping it short of a 5.

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

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

Four short labeled blocks (Purpose / Not for / Returns / Use when), front-loaded and scannable, with no filler. Each sentence carries distinct information an agent needs.

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

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

No output schema exists, and the description compensates by describing the return as a complete workflow graph. Combined with the explicit sibling exclusion and the pre-edit usage rule, an agent has everything needed to select and invoke it correctly.

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

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

There is a single required parameter (id) with 100% schema description coverage, so the schema already carries the semantics. The description adds no identifier format or sourcing guidance beyond what the schema states, which is the expected baseline at this coverage level.

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

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

States a specific verb and resource ('Fetch one workflow') plus the exact scope of what comes back: trigger, every step, and the transitions connecting them. This distinguishes it from plunk_list_workflows and from the execution-history sibling it explicitly names.

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 'Not for' exclusion (run history -> plunk_list_workflow_executions) and an explicit 'Use when' condition ('Always, before editing a workflow'), with the reason: steps and transitions cross-reference by id, so the current graph is required to edit safely.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context by describing what the returned record contains (steps taken, current position, next scheduled action), which tells the agent what to expect from the call.

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

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

Four labeled, front-loaded lines with no filler; each block (Purpose, Not for, Returns, Use when) carries distinct information. Nothing extraneous.

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

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

No output schema exists, so the description must gesture at return values — it does, describing the execution detail and summarizing the record. Both required UUIDs are clear. Slightly thin on the return shape for a detail-fetch tool, but adequate.

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% — both 'id' (Workflow UUID) and 'executionId' (Execution UUID) are documented in the schema. The description adds nothing about parameter format or the relationship between workflow id and execution id, 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 (fetch) and resource (one workflow execution) and enumerates the substance of the record: steps taken, current position, what is scheduled next. It also explicitly names the sibling it is not (plunk_list_workflow_executions), so an agent can distinguish it 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?

Provides an explicit 'Not for' line pointing to plunk_list_workflow_executions and a 'Use when' line giving concrete diagnostic scenarios (a contact stuck, what they have already been sent). When, when-not, and the alternative are all present.

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