Volanea

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

readOnlyHint=true already establishes the safety profile, and the description usefully adds that the rendered HTML comes back truncated, that engagement counters and errors are included, and that the no-id path is a bounded recent list. It does not disclose pagination or rate-limit behavior, but the annotation plus schema status semantics carry most of the burden.

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

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

Two sentences, zero filler, with the core action and both modes front-loaded before the supporting examples. Every clause earns its place and nothing is repeated from structured fields.

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

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

With annotations covering safety, an output schema covering return shape, and 100% schema description coverage, the description only needs to supply mode intent and use cases — both of which it does. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so per-parameter meaning is already documented (the `status` overview in particular). The description adds value beyond the schema by explaining the emailId/no-emailId mode switch and the transactional/campaign/workflow/inbound origin grouping, which no single parameter description 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 and resource ('Inspect the send log') and then crisply defines the two operating modes — detailed lookup by `emailId` versus a filtered recent-message list. It also names the sibling it complements (volanea_send_test_email), so an agent can place it against alternatives without opening any schema.

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

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

Gives clear conditions for both modes ('with emailId… the way to confirm a volanea_send_test_email rendered correctly'; 'without it… useful to confirm a workflow actually sent its email') and ties the `source` filter to a concrete question. It stops short of explicit exclusions — it never says when to prefer volanea_wait_for_email instead of polling this log.

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

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

Beyond the readOnlyHint annotation it explicitly confirms it "never suppresses, unsubscribes, or creates anything" and explains the two distinct gate mechanisms (suppression blocks all sends; contact unsubscribe blocks marketing only). This is substantive behavioral context an agent could not get from the annotation alone.

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

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

The key question and the both-gates warning are front-loaded, and each sentence carries useful information. The gating explanation is a dense em-dash-heavy sentence, slightly reducing readability, 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 an output schema present, return values need not be detailed, yet the description still previews the result ("which gate would close and why"). Combined with the gate semantics and read-only confirmation, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% with a single parameter already documented (normalization of case/space). The description adds no parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with the exact question it answers ("can I actually send to this address?") and a specific scope: checking the two send-pipeline gates for one address. It is clearly distinguishable from sibling tools like check_delivery or send_test_email.

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

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

It states the context of use explicitly ("before writing or debugging a send path") and stresses checking both gates rather than one. It does not name alternative tools or give when-not-to-use guidance, so it falls short of a 5.

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

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

Annotations only supply destructiveHint=true and a title; the description carries the real behavioral load: it runs as a preview by default and only deletes with { confirm: true }, it refuses to remove resources that were merely updated, and it can sweep auto-created contacts produced by enrollment or tracking. That is exactly the destructive-safety context an agent needs before calling a mutation tool.

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

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

Three sentences, each earning its place: scope, exclusions, preview/confirm mechanics, and the recommended usage moment. The destructive preview default is front-loaded relative to the usage advice, and there is no filler.

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

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

With an output schema present, the description needn't explain the preview payload, and it covers everything else: scope limits, safety behavior, and when to invoke. An agent has all it needs to call this destructive tool correctly without surprising deletions.

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

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

Schema coverage is 100%, so both parameters are already documented in the input schema with the same semantics the description restates ('preview by default', confirm:true). The description adds the useful nuance that kinds omitted means 'everything this server created', but otherwise duplicates the schema rather than extending it. 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 (remove) and an explicit, enumerated resource set (templates, segments, workflows, webhook endpoints, campaign drafts, auto-created contacts), and pins the scope to 'YOU created ... through this MCP server.' It implicitly separates itself from volanea_delete_resource by declaring exactly what it can and cannot touch, so an agent can distinguish it without opening the schema.

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

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

Gives a clear context ('Use this at the end of an integration session so a production project isn't left holding your scaffolding') and a strong when-not boundary (human-made or REST-API resources and merely-updated resources are never touched). It never names the obvious alternative, volanea_delete_resource, for removing individual resources, so routing guidance is clear but not fully 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?

With only a title annotation, the description carries the burden and discloses the critical trait that it never sends and why, plus that unsubscribed contacts are excluded from every audience. It stops short of stating rate limits, error/refusal behavior, or what the draft record looks like on return.

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

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

Two tight sentences, front-loaded with the draft/no-send constraint that matters most, then the audience and A/B options. No filler or repetition.

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

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

An output schema exists and schema coverage is total, so return values and per-parameter syntax need not be explained. The description covers the audience model, A/B options, and the draft-only contract; minor gaps (verification failure behavior, rate limits) remain but are not blocking.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters in depth. The description restates audience modes and names abSubjectB/abSamplePct for the A/B test, adding only modest framing beyond what the schema already says.

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 ('create'), resource ('campaign'), and the exact resulting state ('as a DRAFT for the user to review and send from the dashboard'). It also distinguishes itself from a nonexistent send tool, so an agent knows this is a write-but-not-deliver operation.

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

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

Explains the workflow (create draft, review in dashboard, there is deliberately no send tool) and gives explicit selection guidance between the three audience modes, including the tradeoff for 'filter' ('a one-off audience you do not want to keep'). It also routes the agent to volanea_get_project_status before choosing fromEmail.

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

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

Annotations only declare idempotentHint=true; the description goes well beyond that by disclosing beta gating with the `inboxes_not_enabled` error, that addresses are permanent and never recycled, and—critically—that this server never sends from an inbox so replies must go through a code-side POST. These are non-obvious behavioral constraints an agent cannot infer from the schema or 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?

Purpose and the shared-domain default are front-loaded, then idempotency, then the workflow handoff. Every clause carries information: the reply-path sentence in particular prevents the agent from hunting for a nonexistent send tool, so it earns its space rather than being padding.

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

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

For a zero-required-param creation tool with an output schema (so return values need not be described), the description covers the precondition, the default behavior, idempotency, follow-up tools, and the non-sending constraint. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents all four fields. The description still adds meaning beyond the schema by explaining the idempotency consequence of `clientId` in outcome terms ('returns the same inbox instead of making another') and reinforcing that omitting `domain` yields an immediately usable address.

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 an email inbox an agent can receive mail at') with the intended audience spelled out. It is immediately distinguishable from siblings like volanea_read_inbox, volanea_search_inbox, and volanea_wait_for_email, which are the consumption-side tools.

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

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

Gives explicit routing: omit `domain` for the shared domain to get an immediately usable address, pass `clientId` to get idempotent re-calls, and then hand off to volanea_wait_for_email for receiving and volanea_read_inbox for reading. It also states the precondition (project must be in the private beta) and the resulting error code, which is exactly the when-not guidance an agent needs.

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

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

Annotations only carry idempotentHint and a title, so the description adds real value: dynamic recomputation of membership, dry-run non-mutation, idempotency keyed on name, and the warning that unseen event/data fields surface in `warnings` while MCP-seeded test contacts are excluded from counts. It stops short of describing persistence, rate limits, or failure modes, so it is above the annotation bar but not exhaustive.

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

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

Three sentences, front-loaded with the core purpose followed by the dry-run instruction and the idempotency note. Every sentence carries weight, though the density of operational caveats makes it slightly heavier than strictly necessary.

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

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

With an output schema present and rich per-parameter descriptions (including the dry-run preview contents and its skewing caveats), the description covers the creation contract, the safe preview path, and idempotency. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and the nested condition tree, operator lists, and dryRun caveats are already documented in the schema. The description restates idempotency-by-name (already in the `name` field description) and the dryRun workflow, adding little syntax or format meaning beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a dynamic audience segment') plus the mechanism ('from a condition tree') and the key behavioral property ('membership recomputes automatically'). No sibling tool creates segments, and the phrasing makes it unambiguous against create_campaign_draft/create_workflow/create_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?

Gives an explicit prerequisite workflow: 'ALWAYS run once with `dryRun: true` first', and states what that call returns and why (confirm the filter matches intent). It also explains the alternative semantics of omission (nothing is created) and the idempotency-by-name rule, so the agent knows how to sequence calls.

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 idempotentHint annotation by disclosing versioning behavior (content changes snapshot a new version, old versions retained) and the exact shape of the reply (id, version, detectedVariables, not the body). That is precisely the information an agent needs to avoid assuming the response echoes the submitted HTML.

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

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

Four sentences, each carrying distinct load: what it creates, idempotency/versioning, copy guidance, and return shape. The idempotency behavior is front-loaded right after the purpose, and there is no filler.

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

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

For a 7-parameter mutation tool with an output schema, this covers the mutation semantics, the versioning side effect, the placeholder contract, and the return shape. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already explains name-as-idempotency-key, the transactional/marketing compliance split, and the verified-domain requirement for fromEmail. The description restates the idempotency key and placeholder syntax but adds no new per-parameter meaning, 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 ('Create a reusable email template') and immediately qualifies the scope with the {{variable}} placeholder support and the create-or-update idempotency semantics. An agent can distinguish it from volanea_get_template and volanea_render_template without opening any schema.

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

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

Gives clear operational context: name is the idempotency key, existing names get updated, and it names volanea_get_template as the follow-up when the stored HTML is needed. It does not explicitly contrast itself with create_campaign_draft or render_template, so the when-not-to-use side is left implicit.

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 carry idempotentHint and a title, so the description carries the real burden and delivers: idempotency keyed on URL, return of the signing secret, event-pattern matching semantics, and the hard constraint that deliveries originate from Volanea's servers so localhost/private addresses silently receive nothing. That is materially more than the annotations provide.

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

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

Front-loaded with the core action and the returned secret, then the pattern and reachability caveats. Every sentence earns its place, though the tunneling sentence makes the whole thing a touch long for a single tool.

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

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

With an output schema present, return values need not be detailed, yet the description still highlights the one output that matters (the signing secret). Event filtering, idempotency, and reachability caveats cover everything an agent needs to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning beyond the schema by noting idempotency is keyed on the URL and by spelling out that an omitted events array subscribes to everything. The public-reachability constraint on url is a semantic requirement the schema does not state.

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 an endpoint ... to receive Volanea events') and explicitly names the key return value (the whsec_ signing secret). It is clearly distinguishable from siblings like volanea_update_webhook_endpoint and volanea_test_webhook_delivery.

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 strong when-to-use context: explains why you register (to write signature verification), how events filter (patterns or omit for all), and the crucial public-internet constraint with concrete tunneling advice. It does not explicitly route to the update/delete siblings for modifying an existing endpoint, so it stops short of full alternative coverage.

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

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

Annotations only declare idempotentHint; the description adds substantial context beyond that — the tool produces a DRAFT rather than a live workflow, activation is a separate explicit step, and idempotency is keyed on name. It also enumerates the accepted trigger formats including segment enter/exit, which the agent could not infer.

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

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

Front-loaded with the action and resource, then the lifecycle constraint, then trigger syntax. Every clause carries operational weight with no filler, despite the density.

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

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

An output schema exists so return values need no explanation, and the description still covers the draft/activate state machine, idempotency key, and trigger formats — the pieces an agent needs to call this correctly for a complex nested-graph 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 already 100%, so baseline is 3. The description adds meaning on top by expanding the trigger vocabulary beyond the schema's example (segment:enter/exit, event:<name> posted via /v1/events or volanea_track_event), though it does not restate the graph node semantics that live in the schema.

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

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

Specific verb+resource ("Create an event-triggered automation workflow from a node/edge graph") and it explicitly names the two sibling tools it hands off to (volanea_test_workflow, volanea_update_workflow). An agent can distinguish this from create_campaign_draft or create_segment 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?

States the full lifecycle: created as DRAFT, verify with volanea_test_workflow, then activate via volanea_update_workflow { status: 'active' }. It names both alternatives and the condition that selects each, 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 declare destructiveHint=true; the description adds substantial context beyond that — the deliberate preview-unless-confirm:true two-step, and non-obvious cascade boundaries (deleting a segment does not delete contacts, deleting a template does not recall sent mail, deleting a workflow strands mid-run contacts). The remaining gap is that it never states whether deletion is reversible or what recovery exists, which matters for a permanent-destroy tool.

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

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

Front-loads the destructive action and the confirm gate in the first sentence, then handles alternatives and cascade caveats. Some of the meta-commentary about deliberately mirroring siblings and making the agent 'say twice' is self-referential padding that could be trimmed without losing information.

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

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

For a destructive single-target delete with an output schema present, the description covers what the agent needs: the confirm gate, the sibling alternative, and the cascade side-effects per resource type. Return values are covered by the output schema, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning about `confirm` beyond the field text by framing it as an intentional double-confirmation contract rather than a mere flag. The `resource`/`id` prefix-match rule is already fully covered by the schema, so no extra credit there.

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 ('Permanently delete ONE resource by id'), so the agent knows exactly what it does and that it is single-target rather than bulk. It also names the sibling it pairs with (volanea_list_resources) and the sibling it should not be confused with (volanea_cleanup_test_data).

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

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

Explicitly routes the agent: use volanea_cleanup_test_data when tidying up server-created artifacts, use this tool when the target may include human-built resources. The condition that selects the alternative is stated, not implied, and the confirm-gate requirement is 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 only provide readOnlyHint; the description carries far more: base URL, Bearer auth, the Idempotency-Key header on sends, mode precedence (indexOnly over operations), and concrete payload sizes (a few KB vs 40-50 KB). It even flags the context-cost consequence of dumping a full resource on every later turn — exactly the behavioral context annotations cannot express.

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

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

The purpose and alternative-to-avoid come first, then auth, then the mode breakdown ordered by increasing cost. Dense but every sentence carries distinct, actionable information; nothing is redundant with the schema 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?

With an output schema present, return shape need not be described, and the description instead supplies the auth, cost model, and mode-selection guidance an agent needs to invoke this reference tool efficiently. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters, making 3 the baseline. The description goes further by explaining why indexOnly takes precedence and why omitting `operations` produces the oversized unfiltered dump, adding decision-level meaning beyond the field docs.

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

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

States a specific verb and resource — an authoritative REST API reference for writing integration code — and clarifies it is a documentation lookup, not a mutating action, which cleanly separates it from the many create/update/delete siblings. An agent can tell exactly what this returns without opening the schema.

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

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

Explicitly says to use this 'instead of guessing endpoint shapes or SDK names,' and lays out the three call modes with a recommended sequence: start with indexOnly, then expand only the two or three operations you will actually call. When-to-use and which-mode-to-use are both prescribed.

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 readOnlyHint=true, and the description is consistent with a safe read. Beyond that it discloses a non-obvious behavioral trait: the returned fingerprint lets the caller verify it is inspecting the same project, and it surfaces setup hints/verification status rather than raw data. It does not discuss rate limits or pagination, so it stops 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?

The imperative lead ('Call this FIRST') is front-loaded and the middle sentence efficiently packs the return payload into one list. The trailing fingerprint instruction is useful but slightly wordy relative to the rest, keeping it out of 5 territory.

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

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

An output schema exists, so the description is not obliged to enumerate return values, yet it does so on top of giving use-case context. Combined with the readOnlyHint annotation, an agent has everything it needs; the only minor redundancy is restating fields the output schema already defines.

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 and there is nothing for the description to disambiguate. It correctly implies the operation is scoped implicitly to the authenticated project.

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

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

The description names a specific verb and resource ('get project status') and enumerates exactly what comes back: plan, reputation, key mode, key fingerprint, sending domains with verification status, webhook endpoints, and resource counts. It is clearly distinguishable from siblings like volanea_list_resources or volanea_get_api_reference, which return different objects.

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 sequencing ('Call this FIRST in any integration session') and an explicit purpose ('Use it to plan the integration before creating anything'), which routes the agent before it reaches for any create_* sibling. It also names a concrete follow-up action (compare apiKey.fingerprint against the app's configured key), so the when and the why 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 only declare readOnlyHint=true; the description goes well beyond, explaining that 404 is returned for an unknown id rather than an empty template, that the summary/full split is deliberate for token cost, and what the read is used for. This is genuine behavioral context the annotations cannot supply.

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

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

Front-loads the core purpose, then the sibling differentiation and the anti-pattern, then the 404 behavior. Slightly long but every sentence earns its place; only minor tightening possible.

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

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

Output schema exists so return values need not be restated, yet the description still names the returned fields, explains the summary-vs-full tradeoff, warns about ids, and covers error behavior. Nothing an agent needs in order to call correctly is missing.

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

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

Schema coverage is 100% and the single parameter's format ('tmpl-…' id) is fully documented in the schema. The description reiterates the id source but adds no syntax beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read ONE template in full') and enumerates exactly what is returned — subject, HTML body, fromEmail, type, version, variables. It explicitly distinguishes itself from volanea_list_resources and volanea_create_template, which return bodyless summaries.

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 ('inspect or restyle existing content', 'check which placeholders a send must supply') and an explicit when-not-to-use ('Do NOT use it to discover ids — volanea_list_resources { templates } is far cheaper'). This is textbook routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered, and the description adds real value by specifying the depth of what is returned (full graph, node config, canvas positions, run counts) versus the summary-only sibling. It stops short of stating auth requirements or any size/rate considerations, so it is strong but not exhaustive.

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

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

Three tight sentences with no filler: the read scope comes first, then the sibling contrast, then the ordering guidance relative to update_workflow. Every sentence carries distinct decision-relevant information.

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

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

For a single-parameter read tool with an output schema and readOnlyHint already present, the description supplies everything an agent needs: what it returns, how it differs from the list tool, and when to call it in the edit sequence. Return-value details are extra credit rather than a gap.

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

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

Only one parameter exists and schema description coverage is 100% ('The wf-… id.'), so the schema carries the parameter burden. The description implies the tool takes a workflow id but adds no syntax, format, or lookup guidance beyond the schema, which is the expected 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 ('Read ONE workflow') plus the exact payload scope ('the complete node/edge graph with every node's config and canvas position, plus per-node run counts'), which clearly separates it from volanea_list_resources, which 'returns summaries only.' An agent can pick this over its siblings 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 workflow: read the stored graph with this tool before editing via volanea_update_workflow, 'so you send back a modification of what is actually saved rather than a guess.' It also names the alternative (volanea_list_resources) and the condition under which it is insufficient.

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, so the safety profile is covered. The description adds genuine behavioral context beyond that: what the two discovery enums actually return (usage counts, already-seen event names) and the failure mode that filters naming non-existent fields 'silently match zero contacts forever.' It stops short of noting limits/pagination, but the added caveat is substantive.

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

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

Two sentences, purpose and rationale front-loaded before the enum specifics. Efficient, though the second sentence largely re-narrates what the schema's enum description already says, so a little redundancy is present.

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 readOnly annotations, a full enum schema, and an output schema, the description only needs to add routing and rationale, which it does. The main remaining gap is that return shape and any list limits are left entirely to the output schema, which is acceptable 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 coverage is 100% and the enum's own description already documents every value, including the same contact_fields/event_names guidance and the zero-match warning. The description restates rather than extends that, so per the high-coverage baseline a 3 is appropriate.

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

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

States a specific verb+resource ('List existing resources of one kind') and immediately gives the goal ('find ids and avoid duplicating work'). It also distinguishes the discovery pair (contact_fields, event_names) from the summary lists, and implicitly separates itself from the get_* siblings. An agent can tell what this does without opening the schema.

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

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

Gives clear context for when to call it: 'use to find ids and avoid duplicating work' and explicitly 'call those before writing segment conditions or workflow triggers.' This is real when-to-use guidance with a rationale, though it does not state when NOT to use the tool or name the alternative get_* tools inside the description proper.

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

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

Beyond the readOnlyHint annotation, it discloses result ordering (recently active threads vs. oldest-first messages), the fields returned (subject, participants, preview, text, sanitized HTML), and a prompt-injection warning about untrusted message content. That is substantive behavioral context an agent cannot get from the annotations alone.

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

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

Three dense sentences, all front-loaded: capability first, mode behavior second, safety warning last. No filler and every clause carries information.

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

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

For a 3-parameter read tool with an output schema and readOnlyHint, the definition covers both modes, result shape, ordering, and the untrusted-content caveat. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 67%, so the schema already documents threadId ('Omit to list threads') and cursor; the description mostly restates the threadId branch while adding the useful detail of what each branch returns and in what order. Baseline 3 is appropriate since the schema carries the parameter burden.

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

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

States a specific verb and resource ('Read an inbox') and crisply splits the two operating modes by return content (thread list vs. thread messages). It does not, however, differentiate itself from the sibling search_inbox, so the agent must infer which read tool applies.

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

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

Gives clear conditional usage tied to threadId ('Without threadId... With threadId...'), which tells the agent exactly which mode it will get. It stops short of naming when to prefer search_inbox or other read siblings, so there are no exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true, but the description adds substantive context beyond that: nothing is sent and no send-log row is written, and it discloses that unsubstituted placeholders are surfaced in the result. It could still note idempotency or variable fallback behavior, but it meaningfully exceeds the annotation.

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

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

Two sentences, front-loaded with the core action and side-effect disclaimer, then the routing guidance. Slightly dense but every clause 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?

An output schema exists, so return values needn't be fully explained, yet the description still names the key outputs (subject, HTML, unsubstituted placeholders). The no-side-effect and routing details cover the main agent ambiguities; minor gaps like error behavior on bad templateId remain.

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

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

Schema description coverage is 100%, so both templateId and variables are already documented with format hints ('tmpl-...') and semantics ('Sample values for {{variable}} placeholders'). The description adds the placeholder-substitution concept but no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (render) on a specific resource (template) and specifies the return payload (subject, HTML, unsubstituted placeholders). Explicitly distinguishes the side-effect-free nature from send tools, making it clearly separable from volanea_send_test_email.

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

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

Gives explicit when-to-use ('while iterating on copy') and names the alternative (volanea_send_test_email) with its selecting condition ('only when you want a real logged message'). This is textbook when/when-not/alternatives guidance.

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

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

Annotations only declare readOnlyHint=true, but the description goes much further: it records feedback without creating the capability, does not retry or unblock, is write-free, reads no project data, and costs one call. This is exactly the extra behavioral 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?

The trigger conditions come first, the crucial 'changes NOTHING' caveat is bolded and front-loaded, and the follow-up routing closes it out. Length is justified by the amount of 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 an output schema present, return values need no explanation, and the description fully covers when to call, what it does and does not do, and how to proceed afterward. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already defines both parameters, including how to phrase 'capability' as an operation and what 'context' should capture. The description body adds no parameter detail beyond that, 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 (report) and resource (a missing tool/capability gap) and frames it as meta-feedback rather than a project action, clearly separating it from every sibling that actually performs work. An agent can tell immediately this is not a capability it can use to accomplish the task.

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

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

Gives three explicit trigger conditions — falling back to a raw REST call, telling the user to do something by hand, or abandoning an approach — and states the tool changes nothing and that the agent should continue via volanea_get_api_reference afterward. When-to-use and what-happens-next are both spelled out.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, but the description adds real behavioral context beyond that: exact-word matching with no stemming, best-match ordering, and the notable exclusion of messages held by the security scan. It does not describe pagination or how the limit interacts with results.

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

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

Three tight sentences, front-loaded with the action and scope, then usage, then matching/exclusion caveats. No filler, every clause carries information.

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

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

With an output schema present, return values need not be described, and the description covers scope, usage, matching behavior, and exclusions. The remaining gap is limit/pagination behavior and a fuller statement of inboxId requirements.

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 q is documented). The description partially compensates by clarifying that 'one inbox' scopes results (inboxId semantics) and that matching is exact/no-stemming, which adds value for q. However, limit and its 1-50 bound are left entirely to the schema.

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

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

States a specific verb and resource ('Full-text search one inbox's mail') with the searched fields enumerated (subject, sender, reply text) and result ordering ('best match first'). This clearly distinguishes it from siblings like volanea_read_inbox and volanea_wait_for_email.

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

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

Gives explicit when-to-use contexts: finding an earlier conversation before replying, or checking whether something already arrived. It does not name alternative tools (read_inbox, wait_for_email) or state when not to use it, so it stops short of a 5.

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

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

Annotations only carry openWorldHint and a title, so the description carries most of the load — and it does: ALWAYS forced into test mode, never delivered to a real inbox even with a live key, but rendered and logged for inspection. This is exactly the behavioral context the sparse annotations don't provide.

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

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

Three tight sentences, front-loaded with the core action, then the safety guarantee, then the workflow. No filler; every clause adds 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 an output schema present, return values need not be explained, and the description covers modes, the never-delivers guarantee, and the read-back path. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value by framing templateId+variables and subject/html as mutually exclusive alternatives ('either...or'), clarifying the conditional requiredness the schema only implies.

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 ('Render and send a test message') and immediately disambiguates the two supported modes: saved template (templateId + variables) versus ad-hoc (subject/html). An agent can tell this apart from siblings like volanea_render_template and volanea_test_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?

Gives a clear workflow ('Use it to verify content renders correctly, then read it back with volanea_check_delivery'), naming the follow-up sibling. It lacks an explicit exclusion against the near-neighbor volanea_render_template (render without sending), so a 4 rather than a 5.

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

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

Annotations cover idempotency and open-world reach; the description adds concrete behavior beyond them — what the first call returns, the state transition to `verified`, and the exact criteria (ownership + DKIM + SPF) for that transition. 'Safe to call repeatedly' reinforces, rather than contradicts, the idempotentHint.

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

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

Three tight sentences, front-loaded with the tool's dual purpose and followed by the call sequencing. No filler, though the sentence structure is slightly denser than strictly necessary.

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

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

An output schema exists, so return-value documentation isn't required, yet the description still summarizes what comes back on the first call (the DNS record set). Both invocation modes and the verification condition are covered, leaving no significant gaps.

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

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

There is a single parameter fully documented in the schema (100% coverage) with an example format ('mail.example.com'), so the schema already does the work. The description adds no further parameter detail — baseline 3 is appropriate.

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

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

States a specific verb and resource ('Add a sending domain', 'check its DNS') and makes the dual-mode nature explicit up front. No sibling tool overlaps with domain setup, so an agent can route here without ambiguity.

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

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

Explicitly describes the call sequence: first call registers and returns records, second call (after installation) runs the live check, and verification requires ownership + DKIM + SPF. It doesn't name alternative tools, but no sibling competes for this task.

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

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

Annotations only declare openWorldHint=true; the description adds significant context: it mentions the delivery is REAL and signed, returns status/body/signature, and creates a delivery row that persists in the log. It doesn't cover auth/permissions or rate limits, but for a test tool this is good transparency.

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

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

Two sentences, front-loaded with the core action and outcome, then the rationale. Zero waste and well-structured.

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

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

The description covers what it does, what it returns, and the side effect (delivery row creation). With an output schema present, return value details needn't be explained, but it doesn't mention authentication requirements or potential impact on the endpoint owner. Still sufficiently complete for an agent to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description doesn't add syntax or format details beyond what the schema provides (e.g., default event name is in schema). Baseline 3 is appropriate 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 and resource ('Send a REAL signed test delivery to a registered endpoint') and clarifies the exact output returned. It distinguishes itself from siblings like volanea_check_delivery by emphasizing the test-and-prove-signature purpose.

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

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

Clearly explains when to use it: 'This is how you prove the signature-verification code you wrote actually verifies, rather than assuming it does.' However, it doesn't explicitly name alternatives like volanea_check_delivery or warn about side effects on production data beyond the delivery-log note.

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 supply only openWorldHint=true, so the description carries most of the behavioral burden — and it delivers: it discloses the contact-creation side effect, that the workflow must be ACTIVE, and that the operation waits before reading the log. It does not state whether a failed run is retried or what auth is required, but the key mutation and state requirements are covered.

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

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

Four tight sentences that lead with the purpose in caps, then behavior, then usage, then prerequisite. Nothing is filler; the prerequisite is deliberately placed last as the immediate next action.

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

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

With an output schema present it needlessly but harmlessly narrates the return shape, and it covers prerequisite, side effect, and usage intent. Minor gaps remain around cleanup of the persisted test contact and failure semantics, but nothing blocking for correct invocation.

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

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

Schema description coverage is 100%, with the email parameter carrying especially rich notes on contact creation and test-artifact tagging, so the schema does the heavy lifting. The description corroborates the create-if-missing behavior and references the update_workflow call, but adds no syntax or format detail beyond what the schema already provides — baseline 3 is appropriate.

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

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

States a specific verb and resource ('END-TO-END TEST for an automation'), then enumerates the concrete behavior: enrolls a contact, waits, returns a per-step run log. It is clearly distinguishable from the similarly-named sibling volanea_test_webhook_delivery, which targets webhooks rather than workflows.

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 ('prove a workflow actually works before telling the user it is done') and a hard prerequisite with the exact call to satisfy it ('Activate the workflow first with volanea_update_workflow { status: active }'). It stops short of naming exclusions or pointing at the volanea_cleanup_test_data sibling for post-test teardown, which the test-artifact side effect would suggest.

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

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

Annotations only declare openWorldHint and a title, so the description carries the burden and does so richly: auto-creation of unknown contacts, SYNCHRONOUS workflow and webhook firing on event:<name>, test-artifact tagging, exclusion from segment evaluation and campaign audiences, and reserved system prefixes. These are exactly the non-obvious traits an agent needs to avoid misdiagnosing results.

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

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

Three dense sentences, front-loaded with the primary purpose and mechanism before the seeding caveat. Nothing is wasted, though the exclusion clause is long enough that a reader must parse it carefully.

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

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

An output schema exists, so return values need no explanation. For a tool with synchronous side effects and test-data semantics, the description covers the trigger, the side effects, and the one trap (test artifacts invisible to segments/campaigns) completely.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above that by adding constraints not in the schema — the reserved system prefixes for `name` and the guidance to use the app's real event name, plus the note that `data` is exposed as workflow variables.

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

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

States a specific verb and resource ('Send a product event exactly as the user's app would (POST /v1/events)') and immediately discloses the side effects that separate it from siblings like volanea_test_workflow or volanea_test_webhook_delivery. An agent can distinguish it without opening any schema.

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

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

Gives clear usage context: 'this is how you verify an event-triggered automation for real' and 'Also useful to seed a test contact.' It also supplies a strong when-not caveat about the test-artifact exclusion. It does not name an alternative tool for the primary use case, so it falls short of the explicit when/when-not/alternative triad.

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 supply `idempotentHint`, so the description carries the rest and does so well: it states this is a partial update where omitted fields are untouched, and that the signing secret is never rotated so existing verification code keeps working. Those are exactly the mutation semantics an agent needs and cannot derive from the schema or 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?

Purpose and the three mutation cases are front-loaded in the first sentence, and the behavioral notes follow. The middle clause justifying the tool's existence ('the server could diagnose a problem it could not fix') is meta-commentary that does not help an agent decide or invoke, a small amount of waste.

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

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

With an output schema present, return values need no explanation, and the description covers mutation scope and secret non-rotation. It omits permission/auth prerequisites and any rate or delivery-side effects, but for a 5-param partial update with full schema coverage this is close to complete.

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

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

Schema description coverage is 100% and the per-parameter text is already detailed (events replaces entirely, enabled stops deliveries, URL must be public), so the baseline is 3. The description reinforces intent with real-world framing ('repoint `url` after a tunnel restarts') but adds no syntax or format detail beyond the schema.

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

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

Specific verb ('Change') plus resource ('an existing webhook endpoint'), then enumerates the three concrete mutations it supports: flipping `enabled`, repointing `url`, and replacing subscribed events. This clearly separates it from `volanea_create_webhook_endpoint` and `volanea_test_webhook_delivery`.

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

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

Gives concrete triggering scenarios (endpoint stuck at `enabled: false`, tunnel restart changing the URL) and cross-references `volanea_get_project_status` as the diagnostic that surfaces the problem. It stops short of naming explicit alternatives or when-not-to-use conditions, but the usage context 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 supply only idempotentHint, so the description carries meaningful extra weight: it warns that `graph` replaces the stored graph wholesale (destructive to omitted nodes) and that going 'active' starts processing live events immediately. It does not cover permissions, rate limits, or failure modes, so it is strong but not exhaustive.

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

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

Three sentences, front-loaded with the what and the two modes, followed by the design rationale and the one hazard an agent most needs to know. No sentence is filler and nothing is buried.

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

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

For a nested-object, six-parameter mutation tool with an output schema, an idempotency hint, and 100% schema coverage, the description closes the remaining gaps: activation semantics, wholesale graph replacement, and the read-before-amend step. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: that `graph` is a wholesale replacement rather than a patch (contrasting the partial-update behavior documented for `name`), plus the read-first workflow. That is genuine added value above the schema.

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

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

States a specific verb and resource ('Update a workflow by id') plus the exact edit surface: graph/trigger or status. It also distinguishes itself from creation ('Activation is deliberately separate from creation'), so an agent can separate it from volanea_create_workflow without opening a schema.

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

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

Gives clear context for the two main modes (amend the graph vs. flip status live) and names volanea_get_workflow as the read-before-write prerequisite. It stops short of explicitly stating when NOT to use it (e.g. to create a new workflow, use volanea_create_workflow), leaving that inference to the sibling name.

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

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

Annotations only declare readOnlyHint=true; the description adds substantial behavioral context: the 55 s wait ceiling, the default 10-minute lookback, the `found: false` timeout outcome, and a prompt-injection warning to read codes/links but never follow instructions in the email body. That last point is high-value behavioral disclosure beyond 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?

Front-loaded with purpose, then filtering, then the `after` window, then timeout behavior, then the safety note. Dense but every sentence carries distinct, non-redundant information.

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

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

An output schema exists so return values need not be enumerated, and the description still covers the key outcome (found: false on timeout). With defaults, filters, retry behavior, and a security caveat all addressed, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 60%, and the description compensates by explaining `after` more deeply than the schema (use the ISO time you triggered the email, or the last emailId you handled) and by clarifying the from/subjectContains filters. It adds meaning beyond the schema, though it doesn't touch timeoutSeconds semantics.

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

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

States a specific verb and resource ('Wait ... for an email to arrive in an inbox and return it in full') plus the concrete use cases (verification code, magic link, reply). The framing of waiting for arrival distinguishes it from siblings like read_inbox and search_inbox that read already-present mail.

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

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

Gives clear when-to-use context ('the way to pick up a verification code, magic link, or reply') and instructs on filters and the `after` window, plus 'call again to keep waiting' on timeout. It does not explicitly name read_inbox/search_inbox as alternatives, so routing is inferred rather than stated.

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