Mailercloud

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

Annotations already declare non-readonly, non-destructive, non-idempotent and open-world, and the description adds real value on top: it discloses the return payload (DNS records with type, host, value, status, next action) and that verification is asynchronous and deferred to a later call. Missing are failure modes such as duplicate-domain behavior or permission requirements.

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

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

Three sentences, front-loaded with the action and auth purpose, then the return shape, then the follow-up step and the dry-run escape hatch. No sentence is filler.

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

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

No output schema exists, and the description compensates by enumerating the returned DNS record fields and the required follow-up action. Combined with 100% param coverage and full annotations, an agent has everything needed to call and interpret 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 coverage is 100%, so both parameters are already fully documented, including the dry_run semantics the description merely restates ('validate without adding'). The only added nuance is framing domain as authentication-related, which is marginal — 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 (add a sending domain) plus the authentication purpose (SPF, DKIM, DMARC), and implicitly distinguishes itself from the read-side siblings get_domain/list_domains by being the creation step. An agent can identify 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?

Explicitly sequences the workflow: add here, publish the returned records, then verify with get_domain, and offers dry_run:true for a non-mutating check. It gives clear context and a named alternative, though it never states when NOT to use it (e.g. domain already exists, use list_domains first to check).

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 (readOnlyHint=false, idempotentHint=true) by disclosing atomicity ('changing nothing' on refusal), the name-based matching limitation imposed by the API, the merge/de-duplicate save semantics, and the specific failure modes. This is exactly the extra context an agent needs before mutating a campaign.

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

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

Four sentences, front-loaded with the action, then the matching caveat, then refusal conditions, then the safe-preview advice. No filler; every clause carries operational information.

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

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

Covers mutation scope, refusal behavior, and side effects for a tool with no output schema and full annotation coverage. Minor gap: it doesn't say what a successful non-dry-run response contains (ids vs. names), though the dry_run sentence hints at the shape.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real value by explaining how list_ids are resolved (exact-name matching to current lists) and what dry_run surfaces ('resulting lists and approximate audience'). It also implicitly corrects the schema's list_ids text ('add or remove'), since this tool only adds and retains.

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 (Add), resource (lists), and target scope (a DRAFT campaign's recipients) while explicitly noting existing lists are retained — which separates it from remove_lists_from_campaign at a glance. No schema inspection needed to know what it does.

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

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

Gives concrete when-not conditions ('refuses if the campaign is not a draft, or if it sends to a segment') and recommends dry_run: true to preview results. It never names remove_lists_from_campaign as the counterpart for removal, so the alternative-routing is only implied by the 'keeping the lists it already has' phrasing.

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 known; the description adds genuinely new behavior: the batch is all-or-nothing and one invalid address rejects everything, the effect is on future sends only, and the agent must confirm with the user first. It also disambiguates the three scope values in terms of which downstream traffic they actually block.

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

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

Front-loaded with purpose, then the critical exclusion, then scopes, batch semantics, and the safety warning — every sentence carries information. It is dense and slightly repeats the scope semantics already present in the enum descriptions, so not flawless, but no filler.

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

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

With no output schema and four parameters (one enum), the description supplies everything an agent needs: blast radius, scope distinctions, batch atomicity, the concurrency/confirmation protocol, and a validation escape hatch via dry_run.

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

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

Schema coverage is 100%, so the baseline is 3; the description still earns credit by explaining that 'marketing' scope covers only PROMOTIONAL Email API traffic and explicitly not Marketing Platform campaigns, which the schema's short enum text does not make as clear. The confirm/dry_run workflow also gets behavioral context (preview, then confirm) beyond the schema's one-liners.

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 recipients to the API Platform suppression list) and immediately draws the boundary that matters: it does NOT stop Marketing Platform campaigns. An agent can distinguish it from list_suppressions and reactivate_suppression without opening any schema.

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

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

Explicitly names the conditions that select a different tool: to stop campaigns, use update_contact (unsubscribe) or import as suppressed in the panel. It also prescribes the call sequence (dry_run first, confirm after user approval), 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?

The annotations already establish that this is read-only, idempotent, non-destructive, and open-world. The description adds meaningful behavioral detail by explaining the types of analysis returned: letter grade, benchmark-weighted scores, deliverability health, insights, and recommendations.

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 two efficient sentences, front-loading the core purpose and then summarizing return contents. There is no redundant or filler language.

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

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

For a read-only analysis tool with no output schema, the description does a good job explaining what the agent will receive. It could be slightly more complete by noting the optional cost_per_email parameter or routing relative to sibling analysis tools, but the core context is present.

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

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

Schema description coverage is 100%, so campaign_id and cost_per_email are already documented. The description does not add further meaning about the required campaign identifier or the optional cost-per-email ROI input, so the baseline score 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 specific verb and resource: deep-dive analysis of a single campaign's performance. It also previews the outputs, making the tool's role clear, though it does not explicitly name sibling tools like analyze_latest_campaigns or compare_campaigns.

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 phrase 'single campaign's performance' implies when this tool is appropriate, but there is no explicit when-to-use guidance, exclusions, or comparison to alternatives such as get_campaign or campaign_health_dashboard.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds substantive value by enumerating what the analysis produces (grades, benchmark comparison, trends, list-level performance, ROI context, action plan) — meaningful since there is no output schema.

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

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

Front-loaded with purpose and scope before the output enumeration, in a single dense sentence with no filler. The long list of outputs is justified because no output schema exists to convey them.

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 and no output schema, the description compensates by describing the return contents and the count/cost parameters. It leaves only the batch-vs-single routing to the agent, which is a minor 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% and both parameters carry descriptions matching the text (default 5 / max 20, cost for ROI projections). The description restates rather than extends the schema, 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 description states a specific verb (analyze) and resource (recent completed campaigns), plus the key scoping qualifier 'as a batch.' 'Batch' implicitly separates it from the single-campaign sibling analyze_campaign, though it never names that alternative outright.

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

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

It gives clear operational context: default of 5 campaigns, up to 20 via count, and recent completed only. It lacks an explicit 'use X instead when...' routing to analyze_campaign or compare_campaigns, so the agent must infer the batch-vs-single boundary.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuine context beyond that: it describes what the tool returns (pass/fail checklist plus specific fix-it recommendations) and the pre-send constraint, which is exactly the value-add expected when annotations carry the safety load.

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

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

Two sentences, zero filler, and the core purpose is front-loaded before the check list and the call to action. Every clause carries either scope or usage 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 a single required parameter, no output schema, and annotations covering the safety traits, this description is complete: it covers what is checked, what is returned (checklist and recommendations), and when to call it. 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 coverage is 100%, so the schema fully documents campaign_id. The description contributes the nuance that the ID should point at a draft, but gives no format or eligibility details beyond that; 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 ('audit') and resource ('campaign draft') and then enumerates exactly what is checked: subject line length, spam triggers, sender config, list selection, content, preheader. An agent can tell this apart from analyze_campaign or campaign_health_dashboard because the audit is explicitly pre-send and gated on a draft.

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 this before scheduling any campaign' gives a clear trigger condition, which is the main usage decision an agent needs. It does not contrast itself against the analytic siblings (analyze_campaign, campaign_health_dashboard), so the agent still infers the boundary.

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, non-idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful compliance context (sensitive data prohibition) but says nothing about partial-failure handling, what happens to contacts that already exist, or batch size limits — significant gaps for a bulk write.

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

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

Two short sentences, front-loaded with the action and scope. The second sentence earns its place as a compliance constraint, though it partially duplicates the same warning embedded in the custom_fields schema 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 bulk mutation with no output schema, an agent still lacks information about how per-contact results or errors are returned and whether the operation is atomic. Annotations cover the mutation safety profile, but the batch-specific behavior an agent needs is not described.

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

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

Schema description coverage is 100%, including per-field descriptions inside the nested contact object, so the schema carries parameter meaning. The description adds only that contacts are handled in bulk and repeats the sensitive-data restriction already present in the custom_fields schema text.

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

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

States a specific verb and resource with explicit bulk scope ('Create multiple contacts at once in bulk'), which implicitly separates it from the single-record create_contact sibling. It does not name the alternative tools outright, so the differentiation is inferred rather than stated.

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

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

Usage is implied by the bulk wording, and there is an explicit must-not rule about sensitive personal data. However, there is no guidance on when to prefer this over create_contact or upsert_contact, nor any mention of the dry_run option for pre-validating a batch.

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 contributes what annotations cannot: the shape and contents of the response (grade, benchmark comparisons, working/needs-attention split, trends, priority action). It does not address the scope of 'recent' (how many campaigns, what time window) or caching/rate behavior, which keeps it 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?

Three tight sentences with zero filler: purpose first, output contents second, routing guidance last. The most decision-relevant information (it's a fast overview, not deep analysis) is front-loaded.

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

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

With no output schema, the description's enumeration of return contents does the necessary work, and the sibling routing is unambiguous. The only meaningful gap is the undefined scope of 'recent campaigns' (count or time window) and whether the portfolio spans all campaigns or a filtered subset.

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 optional parameter, cost_per_email, and schema description coverage is 100% with its own dollar-denominated explanation. The description adds no parameter detail at all, so the schema carries the full burden and 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: portfolio-level health check across recent campaigns, then enumerates exactly what the returned dashboard contains (grade, metric status vs benchmarks, what's working vs needs attention, trends, top priority action). It also names the sibling analyze_latest_campaigns as the differentiator, so an agent can distinguish the two 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 splits the decision space: 'Use this for a fast 10-second overview; use analyze_latest_campaigns for deep analysis.' Both the when and the named alternative are stated outright, leaving nothing for the agent to infer.

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 tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful behavioral context by describing what the tool computes: side-by-side metrics, scores, grades, per-metric winners, and recommendations based on what worked best. It stops short of describing output format or pagination, but that is a minor gap given the annotations.

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

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

Two tightly written sentences with no filler. The primary purpose is front-loaded, followed by a compact enumeration of outputs.

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 analytical tool with fully documented parameters and no output schema, the description provides enough context about what the tool returns and how it is used. A small gap remains: the role of cost_per_email in shaping the results is not mentioned, though the schema covers 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%, and both parameters are well described in the schema itself. The description adds no parameter-level detail beyond the schema—it only implies the campaign_ids requirement via 'two or more campaigns' and does not mention the optional cost_per_email parameter at all.

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 ('side-by-side comparison of two or more campaigns') and enumerates the outputs (metrics, scores, grades, winner, recommendations). It implicitly distinguishes itself from single-campaign tools like analyze_campaign by requiring two or more campaigns, but it does not explicitly name any sibling alternatives.

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

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

The 'two or more campaigns' framing implies when to use it, but there is no explicit guidance on when to prefer it over analyze_campaign, campaign_health_dashboard, or analyze_latest_campaigns. No exclusions or prerequisites 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?

Goes well past the annotations: it warns that is_publish/scheduled_at SENDS email, spells out the required preview-then-confirm handshake, notes sender auto-resolution and the prompted-choice fallback, and states that exclusions and frequency_cap can only be set at creation or in the panel. Those are exactly the consequences an agent cannot infer from readOnlyHint=false / destructiveHint=false.

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

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

Front-loaded with purpose and default behavior, and nearly every sentence carries a distinct operational fact. It is a dense single paragraph though, so the branching publish/confirm workflow is harder to scan than it needs to be at this length.

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

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

For a 25-parameter mutation tool with no output schema and thin annotations, it covers the risky paths (send trigger, confirmation, content source, sender resolution) well. The remaining gap is the return value — there is no output schema and the description never says what comes back (campaign ID? preview payload?), which matters for the confirm-then-create flow.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics the schema lacks: the mutual exclusivity of html/email/template_id, the reply-to defaulting to sender email, the "give all five fields" constraint on pause_rules, and the lifecycle restriction on exclusion fields. It leaves secondary params (segments, tag_ids, email_preheader, frequency_cap) 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?

Opens with a specific verb and resource ("Create a new email campaign in MailerCloud") and immediately scopes the default behavior (creates a DRAFT, sends nothing). It distinguishes itself from create_dnd_email_template by positioning that sibling as the place to design content, and the draft-vs-publish framing separates it from update_campaign.

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 conditional guidance: use dry_run to validate, use the two-step confirm flow when is_publish or scheduled_at is set, and pick exactly one of html/email/template_id. It does not address the sibling ambiguity with schedule_campaign (which schedules an existing campaign) versus scheduling here at creation, nor when to use update_campaign instead.

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

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

Annotations already declare write, non-idempotent, open-world, non-destructive behavior, so the bar is lower. The description adds genuinely non-structured context: a compliance constraint against submitting health, financial, government ID, card, or password data, which an agent would otherwise not know.

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

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

Three short sentences, with the action and its target front-loaded and the safety caveat last. The 'Email and list_id are required' sentence duplicates the schema's required array and is the one line that does not fully earn 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 14-parameter mutation with a nested object and no output schema, the description covers the action, required inputs, and a data policy, but remains silent on duplicate-email behavior, partial-failure semantics, and what a successful response contains. Adequate but leaves real gaps for a write tool.

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

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

Schema coverage is 100% and each of the 14 parameters carries its own description, including the nested custom_fields contract (keyed by field ID/name/key, values text/number/date as YYYY-MM-DD). The description merely restates the two required params, so 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 ('Create a new contact in a MailerCloud list') and names the container resource, so an agent knows exactly what is produced. It does not distinguish itself from close siblings such as upsert_contact, update_contact, or batch_create_contacts, so it stops short of full sibling differentiation.

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

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

It gives the required inputs and a clear prohibition on sensitive personal data, and the schema's dry_run description implies a validate-first path. However there is no guidance on when to use this instead of upsert_contact or batch_create_contacts, and no mention of what happens when the email already exists in the list.

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

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

The description adds vital operational context beyond the annotations, specifically the business rule that a field's type is immutable ('fixed once created') and the system capacity limit ('Accounts can have up to 100 custom 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?

All necessary information—naming rules, type limitations, capacity limits, and dry run usage—is packed into a single, highly efficient paragraph 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?

The description is exceptionally complete, covering all operational constraints (field limits, character counts), behavioral constraints (type immutability), and operational features (dry run).

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?

Although the schema provides 100% coverage, the description uses the parameter details to reinforce constraints (3-30 characters for name) and critical behavioral semantics (type immutability) which helps the agent validate input quality against the tool's business logic.

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

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

The description clearly states the verb ('Create'), the resource ('custom contact field'), and its specific nature ('property'). It is unambiguously distinct from 'update_custom_field' and 'list_custom_fields'.

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 clear guidance on how to use the 'dry_run' parameter for preview. Furthermore, stating that the type is 'fixed once created' is crucial context for when not to expect a successful modification later.

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

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

Adds substantive context beyond annotations: a postal address is mandatory (footer slot or settings.address) and must be requested from the user, merge tags have no fallback and must not follow a greeting, and dry_run performs a validate-and-preview pass. Annotations already cover safety profile, so this extra operational detail is a genuine value-add; response/return behavior after saving is not 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?

Purpose is front-loaded in the first clause, and each following sentence carries distinct, actionable information (build order, catalog resource, address requirement, merge tags, dry_run). It is dense and long-ish, but waste is minimal.

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 deeply nested creation tool with no output schema, the description covers the essential build model, the external catalog dependency, the mandatory postal address, and the dry-run validation path. It stops short of saying what is returned on success or how validation failures surface, which matters for a non-idempotent creation call.

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 a 3 baseline applies, but the description goes further by explaining the row model (layout+columns+blocks vs a ready-made section), the [[key]] merge-tag syntax, and where the address slot lives. That said, it leaves some nested field intent (e.g. layout 'props' vs block 'props') to the schema and catalog resource.

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

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

Opens with a specific verb and resource: 'Design a new email and save it as a template' that lands in Mailercloud's drag-and-drop editor. The 'never send HTML' line implicitly separates it from the HTML-template sibling create_template, but it never names create_template or update_dnd_email_template directly, so sibling differentiation is left to inference.

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

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

Gives a concrete build order (settings, then rows), names the helper tools/resources to consult (list_email_sections, mailercloud://email-blocks/catalog), and tells the agent to use dry_run:true to preview. It does not state when to prefer this over create_template or when to switch to update_dnd_email_template for an existing template.

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 write semantics (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true). The description adds nothing beyond restating the title: it doesn't say whether duplicate names are rejected, whether creation is reversible, or how dry_run behaves. For a mutating, non-idempotent tool, that is a real gap.

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

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

A single front-loaded sentence with no filler. It is appropriately sized, though its brevity reflects under-specification rather than tight editing.

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

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

For a non-idempotent creation tool with a dry_run flag and no output schema, the description should explain what gets created, what dry_run returns, and duplicate-name behavior. Nearly all of that is absent, so an agent must infer behavior from the schema alone.

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 all three parameters are documented structurally, and the baseline is 3. The description itself contributes no extra meaning about name constraints, valid list_type values, or the preview semantics of dry_run.

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

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

States a specific verb and resource: 'Create a new contact list'. Clear enough to distinguish from delete_list and update_list. However, it does nothing to separate it from sibling creators like create_segment, create_tag, or create_custom_field, so the agent gets no resource differentiation beyond the name itself.

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

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

No indication of when to use this versus alternatives, no prerequisites, and no mention of what to do if a list with the same name already exists. The existence of a dry_run parameter (only in the schema) suggests a preview workflow that the description never surfaces.

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, open-world, non-idempotent, non-destructive profile; the description adds that rules are validated before any API call, dry_run previews the request, and a rule cannot target one specific campaign. It also notes the current custom-field limitation, though permissions and response behavior are left unstated.

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 and generally efficient, but it is a single dense paragraph that mixes schema-restated field enumerations with genuinely useful examples and constraints. The length is largely justified by the complex nested rule schema, though it could be structured more scanably.

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

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

For a complex nested rule builder, it covers the essential branches, examples, validation, and dry_run preview. It leaves the created segment's return shape and any permission assumptions unstated, so an agent can invoke it correctly but has minor gaps about the result.

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?

Even with 100% schema coverage, the description adds cross-parameter meaning: how match combines rules, how list names narrow the base or default to all contacts, and how each filter_type pairs with operators, filter_by values, and value shapes. The two JSON examples make the nested rule object clearer than the schema alone.

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 precise verb and resource ('Create an audience segment') and defines it as 'a saved, dynamic filter over contacts,' which clearly separates it from list_segments, get_segment, update_segment, and from create_list/create_tag by resource. An agent can identify the operation without opening the schema.

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

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

It explains how to populate match, lists, and rules, and when to use dry_run for previewing. However, it never explicitly names update_segment/list_segments as alternatives or states when not to use this tool, so it is clear context but not full when/when-not routing.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write with open-world scope, so the safety profile is covered. The description adds nothing beyond that: it does not say what happens on a duplicate name (relevant given idempotentHint=false), whether the tag is immediately usable on contacts, or whether a dry-run preview is meaningful — the dry_run parameter's purpose is only explained in the schema.

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

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

A single, front-loaded sentence with zero filler or redundancy. It is efficient, though the brevity comes at the cost of any usage or behavioral detail.

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 two-parameter create tool with a fully documented schema and helpful annotations, the description is minimally adequate — no output schema exists, so it needn't explain return values. However, it omits duplicate-name behavior and any post-creation workflow, which are the main unknowns for this operation.

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 `name` and `dry_run` documented in the schema itself. The description adds no constraint, format, or uniqueness detail beyond that, so the baseline 3 applies.

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

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

The description states a specific verb and resource ("Create a new tag") plus the domain purpose ("for organizing contacts"), which is clearer than a bare restatement of the name. It does not distinguish itself from sibling creation tools like create_list or create_segment, which an agent must infer from the resource name alone.

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

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

There is no guidance on when to create a tag versus a list, segment, or custom field, and no mention of prerequisites or how to associate the tag with contacts afterward. The agent is left to infer everything about selection from the tool 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?

Beyond the annotations, which already declare this is mutating, non-idempotent, open-world, and non-destructive, the description discloses the merge-tag replacement rules and the exact validation conditions that cause refusal. That is rich behavioral context an agent would not get from the annotations or schema 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 description is front-loaded with purpose and alternative, then adds the two pieces of behavioral information that materially affect calling the tool: merge-tag format and validation refusal rules. Every sentence earns its place, and there is no repetition 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?

For a mutating create tool with no output schema, the description is nearly complete: it covers the source HTML use case, the sibling alternative, merge tags, and validation failures. The remaining gap is that it does not describe success/return behavior or mention the dry_run use case, though dry_run is documented in the schema.

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

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

With 100% schema description coverage, the baseline is 3. The description adds meaningful semantics for the html parameter by explaining [[key]] merge tags, the [[name]] example, keys from list_custom_fields, and that {{…}} is not replaced in campaigns. It does not add comparable guidance for dry_run, plain_text, or category_id, so it is not a 5.

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

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

The description states a specific verb and resource: 'Create a new email template from HTML the user pasted or supplied.' It explicitly distinguishes this tool from create_dnd_email_template, making the intended use case unambiguous 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 alternative and the condition that selects it: use this tool for user-supplied HTML, and use create_dnd_email_template for an email you design so it opens in the drag-and-drop editor. It also provides concrete guidance on merge-tag syntax and which tag source to use via list_custom_fields.

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 that this is a non-read-only, non-idempotent, open-world, non-destructive operation. The description adds only that the webhook is for receiving event notifications; it does not cover endpoint validation, delivery semantics, or what happens on creation beyond the annotations.

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

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

The description is a single front-loaded sentence with no wasted clauses. It is properly concise, though its brevity contributes to gaps covered in other dimensions.

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 does not explain what is returned (e.g., webhook ID or secret) or operational requirements. Annotations and the schema cover safety and parameters, but the description is too sparse to fully prepare an agent for invoking 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 100%, so name, url, events, and dry_run are already documented in the input schema. The description only indirectly references event subscriptions and adds no extra meaning such as URL requirements or event-selection behavior, so the baseline 3 applies.

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

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

The description uses a specific verb and resource ('Create a new webhook') and adds a brief intended effect ('to receive event notifications'). It is clear enough to distinguish from list/get/update/delete webhook siblings by the verb, but it does not explicitly contrast itself with those alternatives.

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 no explicit when-to-use guidance, prerequisites, or exclusions. An agent can infer that this is the creation operation among webhook siblings, but the description does not state when to choose create_webhook rather than test_webhook, toggle_webhook, or update_webhook.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that – notably it omits the two-phase preview-then-confirm workflow enforced by the `confirm` parameter, which is the most important behavioral fact about this tool.

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

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

A single front-loaded sentence with no waste, though it is arguably too terse for a destructive operation rather than optimally concise.

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, open-world mutation the description should hint at the preview/confirm sequence and consequences. The rich schema descriptions compensate, but an agent relying on the description alone would not know deletion requires confirmation.

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 all three parameters (contact_id, dry_run, confirm) are self-documenting, and the baseline is 3. The description adds no meaning beyond what the schema already provides.

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

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

Specific verb ('Delete') plus resource ('contact') plus the key selector ('by ID'). It is clearly distinguishable from siblings such as update_contact, get_contact, and batch_create_contacts, though the description itself does not call out the neighboring delete_* 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?

No statement of when to use this versus alternatives (e.g., update_contact, upsert_contact, batch operations) and no prerequisites. The critical guidance about previewing before confirming lives only in the schema, not the description.

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 bar is lower, yet the description adds real value: it names the collateral damage (stored values are lost), discloses a precondition failure, and explains the two-phase confirmation protocol including that the first call is a no-op.

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 destructive effect and its blast radius, then the failure condition, then the protocol. No filler and nothing 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 destructive tool with no output schema, the description covers effect, precondition, and safety protocol well. It stops short of saying what the preview actually returns (e.g., affected contacts) or whether the deletion is reversible, which would matter since no output schema exists to explain the preview payload.

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 confirm/dry_run are already documented there, so the baseline is 3; the description earns an extra point by explaining the sequencing semantics of confirm (preview first, nothing deleted, then confirm: true) rather than merely restating the boolean.

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

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

States a specific verb and resource ("Delete a custom contact field") plus the scope of destruction ("the values stored in it"), which distinguishes it from list_custom_fields and update_custom_field without any 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 prescribes the workflow: call without confirm for a preview, get an explicit yes from the user, then call with confirm: true. It also names the blocking condition ("Fails if the field is used in a webform"), which tells the agent when the tool will not succeed.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds nothing beyond restating 'delete' — no mention of cascade effects on list membership, permanence, or the required preview/confirm two-step, all of which would be valuable for a destructive operation.

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

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

A single front-loaded sentence with zero filler. It is efficient, though its brevity leaves behavioral gaps rather than being over-stuffed.

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

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

For a destructive mutation, the annotations supply the safety flags and the schema supplies the confirm/dry_run protocol, so an agent can technically execute correctly. However, the description itself does not mention the two-step confirmation requirement that the annotation title hints at, leaving the description thin relative to the tool's risk.

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 all three parameters (list_id, confirm, dry_run) are fully documented with the preview-then-confirm pattern explained inline. The description's 'by ID' lightly reinforces the required key but adds no syntax or format 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 (delete), resource (contact list), and lookup key (ID), which distinguishes it from delete_contact, delete_tag, and delete_custom_field siblings. It stops short of explicitly differentiating behavior against those alternatives, but the resource is unambiguous.

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

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

The description gives no indication of when to use this versus alternatives (e.g., delete_contact) or of prerequisites. The useful preview-then-confirm workflow guidance lives in the schema's `confirm` parameter description, not in the tool description itself.

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/idempotentHint but say nothing about blast radius or safety protocol. The description adds the cascade effect across all contacts, states that the first call deletes nothing, and mandates user consent before the destructive call — exactly the 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?

Two sentences, no filler, and the highest-stakes information (deletes from every contact) is front-loaded before the procedure. Every clause earns its place.

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

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

For a destructive, open-world tool with no output schema, the description covers consequence and required user flow, which is the essential burden. Minor gap: dry_run and its precedence over confirm are only in the schema, and nothing is said about the preview payload or failure behavior.

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

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

Schema coverage is 100%, so tag_id, confirm, and dry_run are already fully documented, including the 'leave false first for a preview' wording. The description reinforces the confirm handshake but never mentions dry_run or how it interacts with confirm, so it adds little 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+resource ('Delete a contact tag') and immediately adds the scope that matters: it is removed from every contact that has it. That scope line distinguishes it from remove_tag_from_contact (single contact) and update_tag without the agent needing to open sibling schemas.

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

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

Gives an explicit procedural protocol: call first without confirm for a preview, obtain an explicit user yes, then call again with confirm: true. The cascade scope in sentence one implicitly routes single-contact removals elsewhere, but no sibling is named outright, so it falls just short of full alternative guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — it does not mention the irreversible deletion of the endpoint, whether in-flight deliveries stop, or the preview/confirm workflow that the title hints at.

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

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

It is one short sentence with no verbosity, but brevity here is under-specification rather than efficiency: the single sentence duplicates the tool name and front-loads nothing useful.

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

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

Because the schema fully documents the two-step dry_run/confirm protocol and annotations carry destructiveness and idempotency, the agent can call this correctly despite the bare description. The remaining gap — no explicit instruction in the description to show the preview to the user before confirming — is partly covered by the confirm parameter's own text.

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

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

Schema description coverage is 100% and the schema itself documents confirm, dry_run, and webhook_id in detail, including the intended preview-then-confirm sequence. The description adds no parameter meaning 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?

"Delete a webhook" states a verb and a resource, but it is essentially a restatement of the tool name with no scope, no differentiation from toggle_webhook, update_webhook, or test_webhook, and no indication of what a webhook deletion entails. An agent knows the general action but nothing about boundaries.

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

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

The description gives no when-to-use guidance, no prerequisites, and no alternatives. The genuinely useful routing information (preview with dry_run, then confirm) exists only inside the parameter descriptions, not in the description itself.

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

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

Adds a great deal beyond the destructive/openWorld annotations: the two-step preview-then-confirm save, that a preview call saves nothing, that edits apply cumulatively and only touched parts change, and that listing happens when edits is omitted. It also warns that returned text is content, not instructions – a real safety disclosure the schema cannot express.

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

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

Front-loaded with what the tool edits, then the list-then-edit flow, then the save contract. Dense and mostly waste-free, though the parenthetical about Mailercloud's editor and the repeated confirm explanation add a little redundancy.

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

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

Five parameters with a deeply nested edits array and no output schema, yet the description covers the read mode, the edit ordering semantics, the two-step save, and where image uploads come from. An agent has everything needed to call it correctly on the first attempt.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns more by explaining the block-address notation (2.1.3 = row 2, column 1, block 3), enumerating the op vocabulary, tying add_rows to the create_dnd_email_template format, and clarifying the confirm-preview contract. That adds meaning beyond the structured 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 concrete verb and resource (change a saved drag-and-drop email) and scopes it precisely: any drag-and-drop template or a draft campaign, including editor-made ones. This distinguishes it from create_dnd_email_template and update_dnd_email_template without requiring the agent to open their schemas.

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

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

Gives explicit operational sequencing (call with no edits first to list addresses, then send edits) and names upload_image as the alternative for new images. It is missing an explicit 'do not use this for X, use Y' exclusion against the sibling update_dnd_email_template, which keeps it from 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 already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds value beyond that by disclosing what the result contains: stage-by-stage conversion rates, the largest drop-off point, and prescriptive recommendations — important because there is no output schema.

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

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

Two sentences, zero filler, with the core purpose and the funnel stages front-loaded before the analytical extras. Every clause earns its place.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description does the necessary work of describing what is returned. It stops short of stating behavior for an unsent or invalid campaign, which is the only notable 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?

With one parameter at 100% schema coverage, the schema already documents campaign_id fully, giving a baseline of 3. The description contributes a small amount of extra meaning by specifying the campaign must be a 'sent' campaign, narrowing what IDs are valid, but offers no error or format guidance.

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

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

The description names a specific action and resource — visualize the engagement funnel for a sent campaign — and enumerates the exact stages (sent → delivered → opened → clicked). This is clearly distinguishable from sibling reporting tools like get_campaign_opens or analyze_campaign, though it never names those siblings explicitly.

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

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

The phrase 'for a sent campaign' implies a precondition (the campaign must already have been sent), which is useful context. However, there is no explicit statement of when to prefer this over analyze_campaign, campaign_health_dashboard, or compare_campaigns, so the agent must infer the choice.

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

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

The annotations already declare read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context by saying the response includes product overviews, plan and contact usage, and chat-versus-app capabilities, though it does not describe response structure in detail.

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 definition is front-loaded with the key usage instruction and then explains what the tool returns. Every clause is relevant: trigger conditions, source of truth, product coverage, account usage, and chat/app scope.

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

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

Given that there are no parameters and no output schema, the description carries the needed context well. It explains when to call the tool, what broad information it returns, and how the agent should use the result.

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

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

The tool takes no parameters and the schema is empty, so there are no parameter semantics to get wrong. The baseline for a zero-parameter tool is 4, and the description does not need to compensate for missing input documentation.

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

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

The description states a specific verb and resource: it returns an overview of every Mailercloud product plus account plan and contact usage. It also distinguishes this tool from the surrounding sibling tool list by explicitly telling the agent to start here rather than infer capabilities from the tool list.

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

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

It gives explicit triggering conditions: when the user asks what you can do, what Mailercloud offers, or how to get started. It also gives a clear execution instruction: call this tool first and answer from its overview, not from the tool list.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context of its own and leaves an important ambiguity: whether 'filtered by node type' narrows the returned workflow structure or changes which automation is matched. No permission or rate-limit notes.

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

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

A single compact sentence with no filler, front-loaded with the core action. It is efficient, though the brevity leaves the node_type ambiguity unaddressed.

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 should indicate what 'details' means (workflow structure, nodes, status, metadata), and it does not. For a simple two-parameter read tool this is a moderate gap rather than a fatal one, since the annotations cover safety.

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

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

Schema description coverage is 100% (both parameters documented), so the baseline is 3. The description restates 'optionally filtered by node type' but does not clarify what filtering means here - whether it returns only nodes of that type within the workflow or affects matching - which is exactly the detail the terse schema description 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 and resource ('Get details of a specific automation workflow'), which is unambiguous. There are no other automation-related siblings in the list, so differentiation is less of a concern, but it does not distinguish itself with respect to the many other 'get_*' 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?

Usage is only implied: the agent can infer it is for fetching a known automation by ID plus an optional filter. There is no explicit when-to-use guidance, no preconditions, and no mention of alternatives or what to do when the ID is unknown.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about what the report contains — benchmark comparisons, pattern identification, and prioritized recommendations — but does not clarify data scope (e.g., which campaigns or time range) or behavior when no campaign data 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?

The description is a single, front-loaded sentence that efficiently enumerates the report's value. Every clause contributes to the agent's understanding of the output; 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 no output schema and no parameters, the description carries most of the burden for explaining what the tool returns, and it does describe the report contents well. It leaves minor gaps around data scope (all-time vs. recent campaigns) and whether prerequisites exist, such as needing prior campaign history.

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 and has 100% schema coverage, so there is nothing to document. The description appropriately implies the report is generated from the account's existing data without requiring input parameters. Baseline 4 applies for a zero-parameter 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: 'Generate a comprehensive email marketing best practices report based on your actual campaign performance data.' The report contents are enumerated (benchmarks, patterns, improvement areas, recommendations). It does not differentiate itself from similar analytical siblings like campaign_health_dashboard or analyze_campaign, which keeps it from a 5.

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

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

Usage is implied by 'based on your actual campaign performance data,' suggesting it is an account-level analysis. However, there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as campaign_health_dashboard or analyze_campaign.

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 useful detail that results include performance metrics, but says nothing about error behavior for invalid IDs, auth requirements, or rate limits.

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

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

A single front-loaded sentence with no filler; both clauses earn their place, with the detail clause ('including performance metrics') doing real work by signaling the payload scope.

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 carries the burden of describing return content, and 'full details ... including performance metrics' is only indicative rather than concrete about what fields come back. For a simple single-parameter read tool with full annotation coverage this is adequate, but an agent cannot predict the response shape.

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%, so the schema already documents campaign_id. The description repeats 'by ID' without adding format, source, or where to obtain the ID, which is the baseline 3 case.

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

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

States a specific verb and resource ('Get full details of a specific MailerCloud campaign by ID') and hints at scope ('including performance metrics'), which separates it somewhat from the narrow sibling tools like get_campaign_opens, get_campaign_clicks and analyze_campaign. It stops short of explicitly positioning itself as the superset/details view versus those siblings, so it is clear but not fully differentiated.

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

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

Usage is only implied: an agent infers it should call this when it has a campaign ID and wants details. There is no explicit statement of when to use this versus list_campaigns, analyze_campaign, or the per-metric campaign tools, and no mention of prerequisites such as needing a valid ID first.

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, openWorldHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds the pagination ceiling and the optional date window, but says nothing about ordering, default sort, or empty-result behavior. With annotations carrying the behavioral load, a 3 is right.

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

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

Two short clauses with zero filler; the core purpose and returned fields come first, with the pagination/date constraints trailing in a compact fragment. Every element 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, paged listing tool with full schema coverage and no output schema, naming the returned fields (email, name, lists, time) is the key missing piece and it is supplied. Minor gaps are sort order and whether contacts with multiple clicks are deduplicated.

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

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

Schema description coverage is 100%, so every parameter including campaign_id and the date format is already documented in the schema. The description only restates limit and date_from/date_to, adding no semantics beyond the structured fields. Baseline 3 applies.

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

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

States a specific verb and resource ('List the contacts who clicked a link in a campaign') and enumerates the returned fields, which cleanly separates it from get_campaign_opens and get_campaign_unsubscribes. An agent can pick this over its 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?

Usage is only implied by the pagination and date-filter hints ('Paged (limit 1-100); optional date_from/date_to'). There is no explicit when-to-use, when-not-to-use, or pointer to a sibling such as get_campaign_opens for open data.

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 covered. The description adds the precondition that the campaign must be sent, which is genuinely useful behavioral context, but says nothing about result ordering, pagination behavior, or what happens for unsent 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?

A single front-loaded sentence with no filler and no redundancy. It is efficient, though its brevity leaves little room for the routing guidance an agent would benefit from.

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 three-parameter read tool with full schema coverage, annotations, and no output schema, the definition is adequate. However, it never specifies which domain-level statistics are returned, leaving a real gap given the absence of an output schema.

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

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

Schema description coverage is 100% and all three parameters (campaign_id, page, limit) are documented in the schema, so the schema does the heavy lifting. The description adds only the implicit constraint that campaign_id refers to a sent campaign, which is marginal beyond the structured fields.

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

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

States a specific verb ('Get') and resource ('domain-level performance statistics') scoped to a sent campaign, which distinguishes it from click/open report siblings. It stops short of naming the exact metrics returned, so the purpose is clear but not fully sharpened against adjacent report 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?

Usage is only implied: the phrase 'for a sent campaign' hints that the campaign must already be sent, but there is no explicit when-to-use, when-not, or named alternative among the many sibling report tools (get_campaign_clicks, get_campaign_opens, analyze_campaign).

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 that this is a read-only, idempotent, non-destructive open-world query. The description adds useful behavioral context by saying results are paged, the limit range is 1-100, dates are optional, and the returned fields include email, name, lists, and open time.

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

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

The description is compact and front-loaded: one sentence states the core purpose, and a short parenthetical adds paging and date-filtering context. Every sentence carries useful information with no filler.

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

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

For a read-only, fully documented 5-parameter query tool with no output schema, the description is largely complete: it names the returned fields, notes pagination, and explains date filtering. It omits the page parameter and default limit size, but the schema covers those details.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the input schema. The description mentions paging, the limit range, and optional date_from/date_to, but those details largely repeat the schema and it does not explain the page parameter or add syntax beyond what is already provided.

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

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

The description states a specific verb and resource: list contacts who opened a campaign. The word 'opened' distinguishes this from sibling report tools such as get_campaign_clicks and get_campaign_unsubscribes, and the returned fields make the purpose concrete.

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

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

Usage is implied by the purpose: use this to list contacts who opened a campaign, optionally filtered by date. However, the description does not explicitly say when to choose this over adjacent siblings like get_campaign_clicks or get_campaign_unsubscribes, and it gives no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: it lists the returned fields and explains that 'Abuse' means the contact reported spam, which is a semantic detail annotations cannot convey.

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

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

One tightly packed sentence plus a short paging clause; the resource and returned fields are front-loaded and every phrase 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 list tool with no output schema, the description helpfully names the return fields (email, name, lists, time, reason) and paging bounds, so an agent knows what to expect. Only the absence of any sibling routing guidance keeps it from full completeness.

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

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

Schema description coverage is 100%, so page, limit, date_from, date_to and campaign_id are all documented in structured data. The description only restates the limit range and the optional date filters, adding no format or edge-case 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 and resource — 'List the contacts who unsubscribed from a campaign' — and enumerates returned fields. It is clearly distinguishable from siblings like get_campaign_clicks or get_campaign_opens, though it never names them explicitly.

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

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

Usage is implied: 'Paged (limit 1-100); optional date_from/date_to' gives the operating context, but there is no statement of when to prefer this over the other campaign-report siblings or of prerequisites. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that the response is 'detailed', without describing what data is returned or any auth/scope 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?

A single efficient sentence with the verb and resource front-loaded. No padding, though it is arguably too terse for the information it must carry.

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 and the schema covering both parameters, the main remaining gap is what 'detailed information' actually returns, since there is no output schema. For a simple read-side getter this is adequate but 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?

Schema coverage is 100%, so the schema already documents both parameters, including the contact_id alias. The description adds nothing about parameter syntax and mildly misleads by framing lookup as ID-only when the schema permits an email 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 ('Get') and resource ('detailed information about a specific contact'), which distinguishes it from list_contacts and batch_create_contacts. The only weakness is that it says 'by ID' while the schema also accepts an email address.

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 word 'specific' implies single-record lookup as opposed to listing, but there is no explicit guidance on when to prefer this over list_contacts or update_contact, and no mention that email lookup is supported.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds real context beyond that: it enumerates the possible record statuses and discloses that invalid records come back with a suggested fix, which shapes how an agent interprets the response. It stops short of saying whether a lookup triggers a live DNS re-check or what happens for an unknown domain_id.

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

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

A single front-loaded sentence with zero filler; the status enumeration and fix disclosure are packed in without 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 carries the burden of return-value disclosure and does so reasonably (statuses, remediation). Missing only edge behavior such as not-found handling or freshness of the DNS check, which is minor for a one-parameter read.

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

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

Schema coverage is 100% and domain_id is documented with its provenance (list_domains or add_domain). The description adds nothing about the parameter, 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 ('Get one sending domain') and even previews the payload (per-record DNS status plus remediation text). The singular 'one' implicitly separates it from list_domains, though it never names that sibling.

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

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

There is no when-to-use or when-not guidance in the description; the only routing hint ('from list_domains or add_domain') lives in the schema, not the description. An agent must infer that this is the detail-view counterpart to list_domains.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the deliverability-monitoring framing, but says nothing about date-range limits, result granularity, or whether data is aggregated per provider/domain.

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 operation front-loaded and the optional filters and purpose following. Nothing could be removed 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?

With no output schema, the description carries the burden of describing return values, and it only gestures at 'placement data' and 'deliverability across email providers' without stating the shape, aggregation level, or time granularity. Adequate to call the tool, but thin for interpreting results.

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

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

Schema description coverage is 100%, so all four parameters including date formats (YYYY-MM-DD) are already documented. The description only restates that campaign and domain are optional filters, adding no datetime constraints or filter-combination 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 (get inbox placement tracking data) plus the scope (date range, optional campaign/domain filters). It is clear what the tool returns conceptually, though it does not name any sibling it differs from, e.g. get_campaign_domain_report or get_campaign_opens.

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 second sentence ('Helps monitor deliverability across email providers') implies the monitoring use case but gives no explicit when-to-use/when-not conditions and does not point to any alternative tool for adjacent reporting needs.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, so safety is covered. The description adds only the hint that subscriber counts are returned; no pagination, error behavior, or scope details are 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?

A single front-loaded sentence with no wasted words; the resource and the notable output field both appear immediately.

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

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

For a one-parameter read tool with full annotation coverage and no output schema, this is nearly sufficient. The only gap is what else 'details' contains beyond subscriber counts, but that is minor.

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 only one required parameter (list_id) exists. The description reinforces that the id refers to a contact list but adds no format or sourcing guidance beyond the schema's bare 'List ID'.

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

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

States a specific verb and resource ('Get details of a specific contact list') and adds scope ('including subscriber counts'). It implicitly contrasts with list_contact_lists by saying 'a specific' list, though it doesn't name the sibling.

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

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

Usage is implied: fetch the full record for one list identified by list_id, as opposed to listing many. No explicit when-to-use, prerequisites, or alternative routing is given.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds a genuinely useful behavioral trait beyond that: rules are returned 'exactly as saved', signalling verbatim round-trip fidelity needed for update_segment. It says nothing about failure modes for an invalid ID or about pagination/size limits on large segments.

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

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

Two sentences, zero filler, and the returned-field list is front-loaded immediately after the verb. The trailing clause earn its place by explaining why verbatim rules matter.

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

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

With no output schema, the description usefully enumerates the return payload, which is the main gap it had to fill. For a single-param read tool with full annotation coverage the definition is essentially complete; only error behavior for a bad ID is unstated.

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

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

One parameter with 100% schema coverage, where the schema itself says 'Segment ID from list_segments'. The description restates the same sourcing hint without adding format, length, or validation detail, 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+resource ('Show one segment's full definition') and enumerates exactly what comes back: name, match mode, lists, contact count and all rules. It also distinguishes itself from the sibling list_segments, which returns the collection rather than the definition.

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 prerequisite workflow ('Find the ID with list_segments') and a follow-up use case ('so they can be passed to update_segment'), which is the read-modify-write pattern. It stops short of an explicit exclusion like 'do not use this to browse segments', but the routing 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 non-destructive behavior, so the safety profile is covered. The description adds that the response includes details and HTML content, which is useful behavioral 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?

The description is a single front-loaded sentence with no wasted language. It states the action and lookup methods immediately.

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

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

For a simple read-only tool with rich annotations and full schema coverage, the description is largely complete: it names the return content and both lookup keys. It could be slightly more complete by clarifying behavior when neither or both identifiers are provided, but the core usage is clear.

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, including the exact-name qualification and the alternative-to-template_id relationship. The description reinforces the lookup options but does not add syntax or failure-mode details beyond the schema.

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

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

The description gives a specific verb and resource: it retrieves a template's details and HTML content, and it identifies the two lookup keys. It is clear what the tool does, though it does not explicitly contrast itself with sibling tools such as list_templates or update_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?

It explains that retrieval can be done by template_id or by exact name, which is useful context for selecting the correct lookup mode. It does not explicitly state when to prefer this tool over list_templates or what to do if both identifiers are supplied.

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 nothing beyond that – no mention of error behavior for a missing/invalid ID or what the returned details contain.

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

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

A single front-loaded sentence with zero filler. It is efficient, though its brevity reflects under-specification rather than tight information density.

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

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

For a trivial one-parameter getter with rich annotations and no output schema, the description is minimally sufficient to call the tool correctly. It leaves gaps on lookup failure behavior and what 'details' includes, which would matter for an agent composing a workflow.

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 the schema documents it at 100% coverage as 'Webhook ID'. The description merely restates that a specific webhook is targeted, adding no format or sourcing hints; baseline 3 applies 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 ('Get') and resource ('webhook') scoped to a single item, which distinguishes it from list_webhooks and the mutation siblings implicitly. It does not name any sibling explicitly, so the separation is inferred rather than stated.

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

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

'Specific webhook' implies a known webhook_id is required, but the description never says when to use this versus list_webhooks, nor what to do if the ID is unknown. No prerequisites or exclusions are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it discloses pagination and enumerates the return fields (names, IDs, subjects, statuses, performance metrics). It stops short of stating default page size, ordering, or rate limits.

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

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

Two sentences, front-loaded with the operation and scope, followed by a compact return-value summary. Every sentence adds information 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 simple read-only list tool with full schema coverage and rich annotations, the description covers purpose, pagination behavior, and return contents. No output schema exists, so the return-field summary in the description compensates; nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters (page, limit) are already documented in the schema, including the minimum limit of 10. The description mentions pagination but adds no syntax, defaults, or format details 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?

The description states a specific verb and resource ('List MailerCloud campaigns') and adds scope ('with pagination'), so an agent knows this is a paginated list operation. It does not explicitly distinguish itself from siblings like get_campaign or analyze_campaign, which keeps it from a 5.

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

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

Pagination implies this is for enumerating campaigns, but the description gives no explicit when-to-use or when-not-to-use guidance relative to get_campaign, analyze_campaign, or compare_campaigns. Usage is only implied by the verb 'List'.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile needs no restating. The description contributes only the fact that results are paginated — useful, but silent on default page size, total counts, or whether an empty account returns an empty array.

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

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

A single front-loaded sentence with no filler, no restatement of the title, and the pagination trait placed where an agent will read it first.

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

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

For a two-parameter read-only list tool with full schema coverage and rich annotations, this is nearly sufficient. The only meaningful omission is pagination semantics (defaults, whether a total is returned), which matters slightly more here since no output schema exists.

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

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

Schema description coverage is 100% — both 'page' and 'limit' are documented in the schema. The description adds nothing beyond echoing 'pagination', so the baseline 3 applies; no defaults or ranges are clarified.

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 all MailerCloud contact lists' — plus the pagination behavior. It implicitly contrasts with get_list_details (singular) but never names a sibling or scoping rule, so it lands just short of full differentiation.

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

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

There is no explicit when-to-use or when-not guidance and no alternative named. An agent must infer from the name alone that this is the enumeration entry point and that get_list_details is for a single list's details.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds only the fact that results are paginated; it does not mention default page size, maximum limits, or result ordering, but with annotations carrying the burden that is an acceptable gap.

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

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

A single sentence with no filler, and the essential scoping detail (contact list) is front-loaded before the pagination note.

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

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

For a simple read-only list endpoint with complete schema coverage and full annotations, the description supplies what an agent needs to select it and call it correctly. Only minor gaps remain around result ordering and what a page beyond the end returns, which are not essential.

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% – page defaults to 1, limit is constrained to 10-100 with a default of 20, and list_id is documented. The description adds no parameter semantics 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?

The description gives a specific verb and resource ('List contacts') plus the scoping qualifier ('in a specific MailerCloud contact list') and notes pagination support. It does not explicitly distinguish itself from close siblings like get_contact or list_contact_lists, so an agent must infer that this is the bulk-retrieval tool for members of one list.

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

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

Usage is implied by the phrase 'in a specific MailerCloud contact list', which suggests the caller must already have a list_id, but there is no explicit when-to-use/when-not guidance or reference to alternate tools such as get_contact for a single record or batch_create_contacts for writes.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered; the description adds real value by explaining what the returned field_value actually is (the key used in personalisation) and flagging that custom-field segmentation is currently UI-only. It omits pagination behavior and whether a total count is returned, but that is a modest gap against the annotation coverage.

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

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

Two sentences, front-loaded with the purpose and no filler. The trailing UI navigation detail '(Audience > Segments)' is slightly more than an agent strictly needs, but it earns its place by clarifying where the unsupported workflow lives.

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 carries the burden of describing returns — and it does, noting that each item includes its field_value key. Pagination semantics are left entirely to the schema, which covers them, so nothing critical for correct invocation 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% — page and limit (including the 10-100 range and default 20) are fully documented in the schema. The description mentions neither, so it adds nothing beyond the structured field data; baseline 3 applies.

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

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

Specific verb + resource: 'List the custom contact properties/fields defined in your account', with the returned payload characterized (each field's key, field_value). It is clearly distinguishable from create_custom_field / update_custom_field / delete_custom_field, though it never names those siblings explicitly.

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

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

The description implies the primary use case (fetching field_value keys for personalisation) and adds a scope caveat that segments on custom fields must be built in the Mailercloud UI. However, it never states when to call this versus the create/update/delete custom-field siblings, and the segment remark is a vague limitation rather than an explicit 'do not use for X'.

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 non-destructive behavior, so the safety profile is covered. The description adds the status enumeration and confirmable filter capabilities, but says nothing about pagination defaults or result ordering beyond what the schema carries.

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 core purpose and the returned status values, with zero wasted wording.

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, zero-required-parameter list tool, this is largely sufficient: annotations carry safety and the schema carries parameter detail. Only the absence of any return-shape hint (there is no output schema) keeps it from a 5.

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 all four parameters are already documented in the schema. The description restates the status values and name-search intent without adding syntax or behavioral nuance beyond it, 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?

States a clear verb ('List') and resource ('sending domains') and names the key returned attribute (authentication status with its values). It doesn't explicitly distinguish itself from siblings like get_domain or add_domain, so it falls short of a 5.

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

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

The mention of 'Filter by status or search by name' implies how the tool is used, but there is no explicit when-to-use guidance, no exclusions, and no reference to the single-domain alternative (get_domain).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description is free to add the behavior that matters: what the call yields ('Shows each section's ID and the slots you can fill'), which is key since there is no output schema. It adds no notes on result volume or whether sections are user-defined vs built-in, but the value-add is real.

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

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

Three short sentences, front-loaded with what the tool is, followed by what it returns, followed by the alternative. Nothing is restated or padded.

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

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

For a two-optional-filter listing tool with no output schema, the description covers what is returned (IDs plus fillable slots) and where to go for content outside its scope. An agent can select and call it correctly with nothing further.

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 filters are already documented. The description's category examples (headers, banners, products, footers) loosely echo the schema's category examples but add no syntax, matching behavior, or default semantics beyond it. 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 (browse) and a precisely scoped resource (the drag-and-drop editor's ready-made sections, enumerated as headers/banners/products/footers). It also distinguishes itself from two neighbors: the consumption point (create_dnd_email_template) and the broader catalog resource (mailercloud://email-blocks/catalog).

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 frames the use case ('to use in create_dnd_email_template') and routes the agent to the alternative for other content types ('The full catalog (settings, layouts, blocks) is the resource mailercloud://email-blocks/catalog'). No explicit 'when not to use' beyond that routing, which keeps it 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 already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description adds that these are configured reply addresses and their downstream use, but it doesn't disclose ordering, pagination defaults, or other behavioral traits beyond what 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?

Two sentences, front-loaded with purpose, then a clear usage note. No filler, and 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 simple read-only list tool with no output schema and rich annotations, the description covers purpose and downstream integration. It doesn't specify returned fields beyond 'IDs' and 'email addresses', but that is a minor gap for such a straightforward operation.

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 fully documents 'page' and 'limit' with their descriptions. The tool description itself adds no parameter-specific meaning (the 'reply_id' mentioned belongs to create_campaign), 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 description states a specific verb ('List') and a unique resource ('reply-to email addresses configured in your MailerCloud account'), which distinguishes it from sibling list tools like list_senders or list_domains. An agent can immediately tell what this tool returns.

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 second sentence gives clear downstream context: 'Use the returned IDs when creating campaigns with the reply_id parameter.' This tells the agent when the result is needed. It doesn't explicitly exclude alternatives, but no sibling overlaps, so the guidance is sufficient.

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 covered. The description adds only the availability of search and sorting, which is essentially parameter information; it says nothing about default page size, pagination behavior, or result ordering that would go beyond the structured data.

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

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

A single, front-loaded sentence with no filler. It is efficiently sized, though the brevity comes at the cost of the missing usage and behavioral detail noted elsewhere.

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, fully-optional, read-only list tool with 100% schema coverage and rich annotations, the description covers the core purpose adequately. With no output schema, return-value explanation is not required, and the remaining gaps (pagination defaults, result shape) are minor.

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 all five parameters (page, limit, search, sort_field, sort_order) are already documented in the schema. The description mentions search and sorting but adds no syntax, defaults, or allowed values 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?

States a specific verb ('List') and resource ('audience segments') with a note on optional filtering/sorting, so the agent can tell this apart from mutation siblings like create_segment or update_segment. It doesn't explicitly contrast with other list_* tools (list_contact_lists, list_tags), leaving some sibling differentiation implicit.

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 sentence describes what the tool does but gives no when-to-use guidance, no prerequisites, and no alternatives. An agent must infer that this is the retrieval path for segments, and nothing tells it whether to paginate, when to pass search, or how it relates to create_segment/update_segment.

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 fully covered. The description adds only the 'verified senders' scope, with no mention of pagination behavior or result size — minimal added value beyond annotations.

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

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

Two short sentences, zero waste, with the purpose front-loaded and the integration hint following immediately.

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

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

A read-only, no-output-schema list tool with complete schema and annotation coverage. The description covers what it returns (sender IDs) and why they matter; only pagination behavior is left unstated, which is minor given the schema's page/limit params.

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 both parameters (page, limit), so the schema already documents them. The description contributes no additional syntax, defaults, or paging guidance, so the baseline 3 applies.

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

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

States a specific verb and resource ('List all verified senders') and scopes the result to the account. It doesn't explicitly distinguish itself from other list_* siblings, but the resource is unambiguous.

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

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

Explicitly tells the agent the downstream purpose: use the returned sender IDs when creating campaigns with the sender_id parameter. This gives clear usage context and links to create_campaign, though it names no exclusions or alternative list tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them by defining exactly what each suppression scope blocks (global = every API Platform send, marketing = only PROMOTIONAL Email API messages via metadata campaignType, transactional = non-promotional). It also clarifies the platform boundary, which is the main source of agent error here.

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 platform exclusion are front-loaded in the first two sentences, and the scope explanation is dense with actionable detail. There is mild redundancy — the Marketing Platform caveat and the scope definitions are restated twice, and the PROMOTIONAL capitalization is noisy — but no full sentence is wasted.

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

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

With 8 optional params and no output schema, the description supplies the critical missing piece by telling the agent that each returned entry carries its scope, plus what that scope blocks. It does not describe pagination behavior or result shape beyond that, a minor gap given the fully documented schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the schema only lists scope values while the description explains what each scope means operationally. The reason-filter values are merely restated, so the lift is partial rather than full.

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 suppressed recipients on the API Platform suppression list") and immediately scopes it away from Marketing Platform campaigns, which no sibling covers. An agent can distinguish it from add_suppressions and reactivate_suppression 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 names the domain boundary ("This list does not apply to Marketing Platform campaigns") and enumerates the available filters and their values, giving clear selection context. It stops short of naming the sibling tool to use for adding or reactivating suppressions, so the alternative routing is implied rather than 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=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no pagination behavior, no default page size, no note on whether all tags are returned across pages.

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

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

One front-loaded sentence with zero redundancy. It is on the terse side rather than padded, but it does not waste words.

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-optional-param read tool with no output schema, the description tells the agent enough to call it correctly. However, it says nothing about the shape of the result (tag list with IDs, pagination metadata), which would help since no output schema exists.

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

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

Schema description coverage is 100%, so page and limit are already documented in the schema; the baseline is 3. The description does not supplement with default values or max limits, but none is required given full schema coverage.

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

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

States a specific verb and resource ('List all tags') scoped to the account, which is unambiguous against create_tag/update_tag/delete_tag. It does not explicitly name sibling alternatives, but the read-only listing intent is unmistakable.

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

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

No when-to-use or when-not-to-use guidance, and no mention of related tools such as list_contacts or list_segments for tag-adjacent workflows. The agent must infer usage purely from the verb.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds nothing beyond the annotations—no note on result size, pagination, or whether categories are account-scoped versus global—so it contributes no behavioral 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?

A single front-loaded sentence with zero filler. Nothing could be removed and nothing essential 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 zero-parameter read with no output schema, the description adequately conveys that the result is the full set of template categories. A brief hint at the return shape (names vs. IDs, whether paginated) would make it complete, but the remaining gap is small.

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 and the schema is an empty object, so there is nothing for the description to document. Baseline 4 applies; no parameter meaning is missing.

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

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

The description uses a specific verb and resource ('List all email template categories') and names the product, so the agent knows exactly what is returned. It is distinguishable from list_templates by the resource noun, though it does not explicitly contrast the two siblings.

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

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

Usage is only implied: an agent can infer this is the discovery call to make before create_template or get_template, but the description never states when to call it or that it takes no filters. No exclusions or alternatives are named.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds non-obvious behavior — that template body content is omitted from results and that IDs are interoperable with two other tools — though it says nothing about pagination or rate 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?

Three tight sentences with no filler. The returned-fields list and the filtering capability come first, with cross-tool routing placed after, which is the right order for an agent scanning for fit.

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

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

With no output schema, the description usefully enumerates the returned fields and flags the content exclusion, which is the key completeness risk. Minor gap: it does not describe pagination behavior or default page size, though the schema covers those defaults.

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

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

Schema coverage is 100%, so the schema already documents every parameter's meaning, defaults, and ranges. The description names the filter categories (template_type, status, category_id, search_name, sort) but adds no syntax or semantics 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?

States a specific verb ('List') and resource ('saved email templates') and enumerates the fields returned (name, ID, editor, type, status, dates). It contrasts itself with get_template, so an agent can distinguish this list tool from the single-record reader without inspecting schemas.

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

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

Explicitly says content is not included and routes the agent to get_template for that need. It also tells the agent that drag-and-drop template IDs are valid inputs to edit_dnd_email and create_campaign template_id, giving clear downstream usage.

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 covered. The description adds useful return-content context (names plus addresses), but says nothing about ordering, pagination, or how the 'search' filter matches, which would matter for an open-world list operation.

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

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

One compact sentence that leads with the resource and ends with the intended purpose. Every clause earns its place, with no filler or restated 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 trivial read-only lister with one optional param and full schema coverage, the definition covers purpose, return contents and the call it feeds. The only gaps are matching behavior of 'search' and result ordering, which are minor and partly inferable.

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 optional 'search' parameter with 100% schema description coverage ('Filter groups by name'), so the schema already carries the semantics. The description never mentions filtering at all, so it adds nothing 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 and resource ('List saved test-email groups') and parenthetically discloses what each item contains ('group name and addresses'). It also names the downstream consumer (send_test_email), which separates it from generic siblings like list_contacts or list_senders without needing 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?

The clause 'for use as send_test_email recipients' implies the workflow and hints at the natural next call, but there is no explicit when-to-use/when-not guidance or named alternative (e.g., use list_contacts for individual recipients). Usage 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.

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds account scoping but does not mention pagination behavior, ordering, or rate limits, and 'all' is slightly ambiguous given the page/limit parameters.

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

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

It is a single front-loaded sentence with no wasted words. The purpose and account scope are stated immediately.

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

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

For a simple list tool with rich annotations and full parameter schema coverage, the description is mostly sufficient. However, it omits pagination behavior and return shape, which matters because page and limit parameters exist and no output schema is provided.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema. The description adds no parameter meaning beyond the 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?

The description states a specific verb ('List') and resource ('webforms') with account scope. It is clearly distinguishable from most siblings by resource, though it does not explicitly contrast with other list_* 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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. Usage is only implied by the name and the phrase 'List all webforms'.

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 carried by structured data. The description adds nothing beyond that — no note on pagination defaults, whether results are filtered, or how large collections are returned.

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

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

A single front-loaded sentence with zero filler. It is efficient, though the brevity comes at the cost of the missing details noted elsewhere rather than being intentional minimalism.

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

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

For a zero-required-parameter read tool with annotations and full schema coverage, this is minimally adequate. An agent can call it, but has no information on result ordering, default page size, or total-count behavior, which matter for a paginated list 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?

Schema description coverage is 100% and both parameters (page, limit) are documented in the schema, so the schema does the heavy lifting. The description does not add defaults, max values, or pagination behavior 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 and resource ('List all webhooks') plus the service scope (MailerCloud), so the operation is unambiguous. It does not differentiate from the many webhook siblings (get_webhook, create_webhook, toggle_webhook, test_webhook), relying on 'list all' to imply the distinction.

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

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

There is no explicit guidance on when to use this versus get_webhook for a single webhook or the other webhook tools. The only cue is the word 'all', which implies a collection-wide fetch but is never contrasted with any alternative.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds essential scope: it clears the whole address across every reason and scope, leaves Marketing Platform status untouched, and blocks spam-complaint reactivations. This tells the agent exactly what will be destroyed and what constraints apply, beyond what 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?

Four sentences, each carrying non-redundant information: purpose and scope first, then the Marketing Platform boundary, the spam-complaint exclusion, and the dry_run preview. 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 destructive two-parameter toggle with no output schema, the description covers scope of effect, platform boundaries, a blocking exception, and how to preview safely. 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?

Schema description coverage is 100%, so both parameters are fully documented in the input schema. The description's mention of dry_run: true previews the same behavior already stated in the schema, so it adds little semantic value beyond 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 (Remove) and resource (recipient from the API Platform suppression list) with the outcome (can receive API Platform mail again). It explicitly distinguishes this from Marketing Platform contact status, separating it from sibling tools like add_suppressions and from marketing-side operations.

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

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

Gives clear context and a hard exclusion: spam-complaint suppressions cannot be reactivated here, and dry_run previews the change. It does not name an alternative tool for handling spam-complaint cases or Marketing Platform suppressions, so the routing guidance is incomplete but still useful.

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 destructive and idempotent annotations, it discloses exact-name matching, atomic refusal with no changes on invalid input, exclusion of non-draft and segment campaigns, and the dry_run preview path. This is strong behavioral detail for a destructive 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?

The description is two compact sentences, front-loads the core action, and then adds only the constraints and preview hint an agent needs. There is no redundant or filler text.

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

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

Given the rich annotations, fully described schema, and absence of an output schema, the description covers the important operational constraints and preview behavior completely enough to call the tool correctly.

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