MisarMail MCP Server

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

Annotations indicate a write operation (readOnlyHint=false), and the description confirms by stating it adds a domain. It additionally reveals the return value (DNS records) and a critical temporal constraint (cannot send until verification), going well 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 two sentences, front-loading the core action and output in the first sentence, with an important qualification in the second. Every sentence adds value with no redundancy.

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

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

For a simple, single-parameter tool with no output schema, the description fully covers what the tool does, what it returns, and the follow-up required. It is complete given the low complexity and rich structural information from the schema and annotations.

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

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

The schema already provides a clear description for the single parameter ('Domain to add, e.g. example.com') with 100% coverage. The description adds no extra meaning for the parameter, meeting the baseline expectation but not exceeding it.

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

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

The description uses a specific verb ('Add') and resource ('sending domain') and clearly states the additional output ('return the DNS records to publish'). It distinguishes from sibling tools like verify_domain and check_dmarc by focusing on the initial addition step.

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

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

The description provides explicit post-condition context ('The domain cannot send until those records are live and verify_domain succeeds'), guiding the agent to follow up with verify_domain. However, it does not explicitly contrast with alternatives or state when not to use this tool.

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

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

The annotation already indicates destructiveHint=false and idempotentHint=true, but the description adds concrete behavioral context: the operation moves the email to an archive folder and is reversible, which goes beyond the annotations and clarifies the exact effect on the email.

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, well-structured sentence that is front-loaded with the action and includes a crucial qualifier (reversible). There is no redundancy or unnecessary 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 mutation tool with one parameter and no output schema, the description provides enough context about the operation's effect and safety. It doesn't explain return values, but that is not critical for such a straightforward archiving action.

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

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

The schema fully covers the single 'id' parameter with a clear description ('Email ID to archive'), and schema description coverage is 100%. The tool description does not add extra parameter context, but the baseline 3 is appropriate because the schema carries the load.

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

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

The description clearly states a specific action ('Move an email to the archive folder') with a clear resource (email) and differentiates from sibling tools by emphasizing it is not a deletion. This is a precise verb+resource+outcome statement.

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

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

The description provides clear context: use this tool to move an email out of the main inbox into the archive, and it is reversible. It implicitly contrasts with deletion by noting the message is not deleted, offering enough guidance for selection among email-related siblings, though it doesn't explicitly name alternatives.

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

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

Annotations already convey idempotentHint=true (safe to retry) and destructiveHint=false (no destruction). The description adds important behavioral context: it consumes AI credits (a cost/resource implication) and implies it processes a batch (max 50). No contradiction with 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 concise, front-loaded sentences. The first sentence states the core function, the second provides critical usage guidance. Every word adds value; no 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?

Given the low complexity (1 param, no output schema), the description is sufficient. The agent understands input, behavior (AI credit consumption), and constraints (max 50). A minor gap: the output format (returned labels/priority) is not described, but since there is no output schema, this is a soft miss rather than a hard requirement.

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% (only one parameter, 'email_ids', well-described with array type, string items, and max 50 limit). The description reinforces that these are emails 'to categorise' and adds the consumption cost context, which helps the agent decide which IDs to pass. No additional parameter documentation is needed beyond what's 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 uses a specific verb ('Run AI categorisation') and resource ('batch of inbox emails') and states the outcome ('label intent and priority'). This clearly distinguishes it from siblings like 'archive_email', 'reply_to_email', or 'get_email', which handle different operations on emails.

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 explicitly advises to only pass emails that need triaging due to AI credit consumption. This provides clear when-to-use guidance. However, it does not explicitly mention when NOT to use this tool (e.g., for already categorized emails) or name specific alternative tools, though the sibling list provides implicit context.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds context beyond annotations by noting the check is 'live,' and that it 'report[s] alignment problems with the exact record to publish.' This provides actionable insight into what the tool does with the data it fetches, which is not covered by annotations.

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

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

The description is two sentences long, front-loads the core purpose, and contains no filler or redundancy. Every sentence contributes critical information: what records are checked, what is reported, and scope of applicability.

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 full annotations and a single parameter, the description is largely complete. It covers the DNS record types checked, the output (alignment problems and publishable record), and domain scope. The absence of an output schema is acceptable since the description adequately describes what the tool returns.

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

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

Schema coverage is 100% with a single parameter described as 'Domain to check, e.g. example.com.' The description adds value by stating 'Works for any domain, not only your own,' which clarifies that the domain parameter is not restricted to the user's own domains—a meaningful addition beyond the schema description.

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

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

The description clearly states the tool checks live SPF, DKIM, and DMARC DNS records for a domain and reports alignment problems with the exact record to publish. It uses specific verbs ('Check', 'report') and identifies the resource (DNS records for a domain), distinguishing it from sibling tools like verify_domain or run_deliverability_audit.

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 states 'Works for any domain, not only your own,' clarifying domain scope and implying broad applicability. However, it does not explicitly mention when to use this tool versus alternatives (e.g., verify_domain), nor does it provide any 'when not to use' guidance or prerequisites.

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

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

Annotations already indicate destructive and idempotent behavior, and the description adds valuable context beyond those: it guarantees the operation only applies to intercepted test messages, never real mail. This is a crucial safety trait for a destructive tool, even if details like irreversibility or authentication are not mentioned.

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 core action, and every word adds value. The second sentence is a precise safety qualifier rather than filler.

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

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

For a parameterless, simple deletion tool, the description is complete. It states the action, the scope, and the safety boundary. Annotations already cover idempotency and destructiveness, and no output schema is needed 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?

The tool takes zero parameters and the schema is empty, so there is no parameter-level meaning to add. The description's scope clarification fully covers the only semantic ambiguity (what gets deleted), earning the baseline 4 for a no-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?

The description clearly states the action ('Delete every captured sandbox email') with a specific verb and resource. It also distinguishes itself from related tools by scoping to sandbox emails ('Affects only intercepted test messages, never real sent mail'), making it distinct from list_sandbox_sends or send_email.

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

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

The description clearly implies when to use this tool (when you want to clear all captured sandbox emails) and provides an explicit when-not boundary by stating it never affects real sent mail. It does not name alternative tools for other email operations, but the context is clear enough for tool selection.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=true and destructiveHint=false, covering the safety and repeatability profile. The description adds the useful behavioral detail that a webhook receives POSTed inbound messages and that an MX record is returned, but says nothing about 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?

Two tightly written sentences with no filler; the routing purpose is front-loaded and the return value is stated second. 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?

With no output schema, the description valuably states the return value (the MX record to publish), so the agent knows what to expect and how to act on it. It is nearly complete for a three-required-param configuration tool, missing only prerequisite ordering relative to add_domain/verify_domain.

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 (domain, subdomain, webhook_url) are already documented in the schema. The description echoes the subdomain/webhook concept but adds no format or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

The description names a specific verb (Configure) and resource (inbound email routing for a subdomain) and states the outcome, that replies land in the MisarMail unified inbox. This clearly distinguishes it from generic siblings like add_domain or verify_domain, though it does not explicitly name 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?

The route purpose ('so replies land in the MisarMail unified inbox') implies when this tool is relevant, but there is no explicit when-to-use versus add_domain/verify_domain guidance and no stated prerequisites such as the domain existing or being verified 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 only supply the generic safety profile (not read-only, non-destructive, non-idempotent, open-world). The description adds substantive behavioral context annotations cannot express: the one-variant-per-call write model, send_percent splitting of the audience, and that winner selection can be automatic after winner_wait_hours. It does not spell out auth requirements or what the response contains, keeping it short of a 5.

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

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

Three tightly packed sentences, front-loaded with the core action before the multi-call mechanic and the winner-selection option. No filler, though the density is high and could be marginally tighter.

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 12-parameter mutation tool with no output schema, the description covers the critical call pattern and the automated vs manual winner path that the schema cannot express. Return-value behavior is undocumented, but with no output schema the burden is lower.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining how parameters interact across calls (same campaign_id, distinct variant labels) and by clarifying the audience-splitting role of send_percent, which the schema's per-field wording doesn't convey.

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

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

States a specific verb+resource (create one A/B test variant on a campaign) and immediately clarifies the non-obvious cardinality: the API stores a single variant per call. This distinguishes it cleanly from create_campaign, list_ab_tests and select_ab_test_winner.

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 procedural guidance (call once per variant with the same campaign_id and distinct variant labels; twice for a plain A/B split) and names the alternative path for winner selection ('or use select_ab_test_winner to do it manually'), with the auto_select_winner/winner_wait_hours condition attached.

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 it is a non-read-only, non-destructive, non-idempotent, open-world write, but the description adds the crucial behavioral detail those hints cannot: the created object is a paused draft, not a live workflow. It also discloses the API's reduced field surface and the required follow-up step (dashboard configuration, then toggle_automation).

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

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

Two sentences, front-loaded with the core action and resulting state, with the limitation and next step in the second. Dense but nearly every clause carries decision-relevant information; a small amount of nesting makes it slightly heavier than strictly necessary.

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

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

For a three-parameter mutation tool with no output schema and annotations already covering the safety profile, the description supplies everything missing: the resulting draft state, the fields that take effect, and the path to activation. Nothing an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds genuine meaning by clarifying that the create endpoint honors only name and trigger. That note slightly oversimplifies trigger_config, which the schema still exposes, so it is informative but not perfectly precise.

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 an automation workflow from a trigger') plus the resulting state ('saved as a paused draft'). It is immediately distinguishable from siblings like get_automation, list_automations, and toggle_automation, which the description explicitly names.

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

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

It routes the agent precisely: create here, configure the step sequence in the MisarMail dashboard's visual builder, and use toggle_automation to activate once reviewed. It also states what this endpoint cannot do (no steps, no starting active), which is exactly the when-to-use/when-not guidance an agent needs.

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

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

Annotations already declare a non-read-only, non-destructive, non-idempotent write. The description adds the key behavioral fact that creation never sends or schedules, which tempers the write semantics and explains the draft state. It does not cover duplicate handling or draft visibility beyond the internal/external name split 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?

Two sentences, zero filler, front-loaded with the core action and immediately followed by the routing constraint. 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 9-param creation tool with a fully documented schema and no output schema, the description covers purpose, draft semantics, and the send/schedule handoff. It omits what is returned on success and whether duplicate names are allowed, which are minor gaps given schema 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% with 9 params, so the schema already documents every field including html/text/template_id and segment_id. The description adds only the loose phrase 'content and audience' which gestures at body and segment params but no format or constraint detail. 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 (create) and resource (email marketing campaign) and constrains the result to a draft, which sharply separates it from send_campaign. An agent can pick it over the sibling list without opening the schema.

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

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

Explicitly names the follow-up alternative (send_campaign) and the condition that triggers it ('once the content and audience are confirmed'), plus states when this tool stops short. Nothing about routing is left to inference.

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

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

Annotations already declare a non-read-only, non-idempotent write. The description goes beyond them by disclosing a meaningful side effect: that adding a contact records consent to email, with reputational and CAN-SPAM/GDPR consequences. This is real behavioral context not encoded in 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 zero waste. The core action is front-loaded and the compliance caution follows immediately 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 full schema coverage and annotations covering the safety profile, the description supplies the one thing structured fields cannot: the consent/compliance semantics of the operation. It does not address duplicate handling or behavior when the email already exists, which is a minor gap given no output schema.

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

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

Schema description coverage is 100%, so all six parameters (email, tags, source, names, custom_fields) are already documented in the schema. The description adds no syntax, format, or uniqueness detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource: 'Add a single contact.' The word 'single' implicitly separates it from the bulk import_contacts sibling, but no sibling is named, so the differentiation is left to inference rather than made explicit.

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

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

Provides a genuine when-not condition ('only add addresses that opted in'), which is real selection guidance and a stronger condition than typical. However, it never names alternatives such as import_contacts for bulk adds or update_contact for existing records, so the routing is incomplete.

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

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

Annotations already declare readOnly=false, idempotent=false, openWorld=true, destructive=false, so the safety profile is covered. The description adds real value beyond that: it discloses the return value (public URL) and the underlying data-model quirk (inputs are translated into one 'hero' block because the API has no headline/CTA fields). What it does not cover is auth/permission requirements or side effects on existing pages, so this is good but not complete behavioral disclosure.

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, then the return value, then the caveat and alternative. No filler, though the final sentence is long and packs two distinct ideas (block-array translation and the editor alternative) that could be split for faster scanning.

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

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

For a creation tool with no output schema and annotations already covering the safety profile, the description supplies the return shape (public URL), the block-translation behavior, and the escape hatch to the dashboard editor. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description rises above it by explaining that cta_text does not yield an actual CTA link but is folded into the translated hero block — a semantic caveat about input interpretation that the per-field schema descriptions do not convey.

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

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

States a specific verb and resource ("Create a hosted landing page") and immediately scopes it to "a single hero block (headline, subheadline, CTA)". No sibling tool creates landing pages, so the agent can place it unambiguously among the email/campaign/domain 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?

The description explicitly names the when-not case and the alternative: "for multi-block pages or a real CTA link, use the landing page editor in the MisarMail dashboard." This routes the agent away from the tool for cases it cannot handle, which is exactly what usage guidance should do.

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 mark this as a non-read-only write operation; the description adds context beyond annotations by explaining variable substitution at send time and previewability via render_template. No contradiction with 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 sentences with front-loaded action ('Create a reusable email template') and a follow-up sentence that explains variable behavior and links to a sibling tool. Every sentence earns its place with no redundancy.

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

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

For a create tool with 6 parameters and no output schema, the description covers the core purpose and a key behavioral nuance (variable substitution). It doesn't explain return values, but that's less critical without an output schema; the schema handles parameter 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?

The input schema has 100% coverage with descriptions for all six parameters, so the baseline is 3. The description reinforces the {{variable}} placeholder concept but does not add parameter-specific semantics beyond what the schema already documents.

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 'Create a reusable email template', using a specific verb and resource. It distinguishes itself from siblings like render_template by focusing on creation, and introduces the key personalization feature via {{variable}} placeholders.

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 when to use this tool (to create templates) and explicitly names render_template as the tool for previewing, providing a useful alternative. However, it does not explicitly state when not to use it or compare with other creation tools like create_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?

The description adds minimal behavioral context beyond the existing annotations (readOnlyHint, idempotentHint). It does not disclose aspects like response format, data freshness, or limitations, which are important for a report generation 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 sentences, front-loaded with the core purpose, and wastes no words. Each 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?

Given no output schema, the description should hint at return format (e.g., JSON) or example usage. It covers input well but leaves agents uncertain about output structure, making it minimally complete.

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

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

With 100% schema coverage, the description adds value by explaining the enum options (especially 'send_time_heatmap' with a parenthetical hint) and reinforces the date range concept. This goes beyond the raw 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 clearly states the tool generates structured analytics reports over a date range and lists four specific report types. However, it does not differentiate from the sibling 'get_analytics', which may have overlapping functionality, slightly diminishing clarity.

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 guidance is provided on when to use this tool versus alternatives like get_analytics. The description only explains what it does without contextual usage advice.

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

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

Annotations already declare destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety and determinism profile is largely covered. The description's 'AI ... variants' wording hints at non-deterministic generation, consistent with idempotentHint=false, but it discloses nothing about cost/credits, rate limits, or output shape beyond what the annotations imply.

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 core action, and no filler. Every clause carries information about purpose or downstream use.

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

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

No output schema exists, so the description carries the burden of describing the return value, and it says only 'variants' without specifying the shape (e.g., array of strings, count honored). It is adequate for a simple four-parameter generator but leaves the response format to guesswork.

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 tone enums, defaults and the count max all documented in the schema itself. The description only gestures at tone/audience tuning ('optionally tuned to a tone and audience'), adding no 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?

States a specific verb and resource ('Generate AI subject-line variants') plus the input scope ('for a campaign topic'), which is unambiguous. It references the downstream sibling create_ab_test, giving some pipeline context, but does not explicitly contrast itself with any competing generator or list a sibling it should not be confused with.

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?

'Good input for create_ab_test' implies the intended workflow, so the agent can infer when this tool fits. However, there is no explicit when-to-use trigger, no when-not-to-use case, and no named alternative, leaving usage largely 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. The description adds the specific metrics returned and the grouping behavior, which is consistent with the annotations. It does not contradict them and provides additional context about the nature of the response, though it could mention that the operation is non-modifying (already covered by annotations).

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

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

The description is a single sentence of 25 words that front-loads the core purpose ('Get delivery and engagement analytics'), then enumerates metrics and constraints without redundancy. Every clause adds essential information, making it highly efficient for an agent to parse quickly.

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 is no output schema, the description adequately covers what the tool returns (list of metrics), how data can be scoped (account/campaign), and the grouping options. It does not describe the response structure (e.g., JSON format, nesting) or behavior when no data exists, but for a read-only analytics tool with well-defined parameters, this is sufficient for an agent to decide whether to invoke 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?

The input schema has 100% description coverage for its 5 parameters, so the baseline is 3. The description adds semantic value by listing the exact metrics (sent, delivered, opened, etc.) that the tool returns—information not present in the schema—and by clarifying that campaign_id is optional and defaults to account-wide. This helps the agent understand what kind of data to expect beyond parameter definitions.

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

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

The description clearly states the verb 'Get', the resource 'delivery and engagement analytics', and specifies exact metrics (sent, delivered, opened, clicked, bounced, complained). It also defines scope ('account or one campaign') and grouping ('day/week/month'), which distinguishes it from sibling tools like get_deliverability_score or get_monetization_stats that cover different or narrower aspects.

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 explains what data the tool returns and the two scopes (account-wide vs. per campaign), but it does not explicitly contrast with similar tools (e.g., get_deliverability_score, get_monetization_stats) or state when not to use it. The agent must infer usage from the listed metrics and parameters; no exclusion criteria or alternatives 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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds real behavioral scope beyond that by enumerating the metrics returned and noting coverage across every send medium, though it says nothing about row limits or behavior on very wide date windows.

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

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

Two sentences, no filler, with the core payload (what is broken down) front-loaded and the disambiguating contrast placed last. 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?

With no output schema, the description does the work of naming the returned metric set and the mediums covered, which is the key missing piece. Remaining gaps are minor: no note on output shape or date-range validation limits.

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 enum values and defaults documented, so the schema already carries the parameter burden. The description's 'day/week/month' phrasing loosely corroborates group_by but adds no format, default, or interaction detail beyond the schema.

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

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

States a specific verb (Get) plus the exact resource (day/week/month breakdown of named email metrics) and scopes it to all send mediums. It also explicitly contrasts itself with the sibling get_analytics ('period totals'), so an agent can separate the two without opening either schema.

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

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

The closing sentence gives clear selection context: this is the timeline/granular view, whereas get_analytics provides period totals. That is a usable routing rule, but there is no explicit guidance on when not to use it (e.g. date-range limits or fallback behavior).

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 and idempotentHint=true, indicating a safe read operation. The description adds behavioral detail about the response contents (trigger, steps with delays, completion stats), which goes beyond the schema and helps the agent understand what data will be available.

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, focused sentence that front-loads the verb and resource. It contains no filler or redundant information.

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

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

For a simple one-parameter read tool, the description covers the key return elements: trigger, steps, delays, and completion stats. Combined with strong annotations, this is sufficient contextual information, though it does not mention error cases or the overall automation metadata.

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 input schema fully documents automation_id as a UUID string (100% coverage), so the description does not need to add parameter details. The description's mention of 'one automation workflow' aligns with the parameter but adds no extra semantic meaning 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 uses a specific verb 'Get' with a resource 'one automation workflow' and details the scope: 'in full: trigger, every step with its delay, and per-step completion stats.' This clearly distinguishes it from sibling tools like list_automations, which likely returns summaries.

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

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

The description implies usage when full details of a single automation are needed, but it does not explicitly state when to use this tool versus alternatives like list_automations. No exclusions or alternative references 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 establish read-only, idempotent, and non-destructive behavior. The description adds return-content context but no additional behavioral traits such as error handling, authentication needs, or rate limits. No contradiction 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, focused sentence that front-loads the action and object, then lists the included detail categories efficiently. Every phrase adds value 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?

For a one-parameter read-only tool with no output schema, the description adequately conveys what the caller receives. It could mention error behavior or exact output structure, but the listed categories are sufficient for a tool of this simplicity.

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

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

The schema already fully documents the single parameter campaign_id with type and description. The tool description adds no further parameter-level detail, so the baseline score of 3 applies given 100% 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?

The description uses a specific verb and resource ('Get full details for one campaign') and enumerates the returned content categories: content, audience segment, schedule, and delivery statistics. This clearly distinguishes it from list_campaigns and other getter 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?

The description implies use when needing full details of a single campaign, but it does not explicitly state when not to use it or mention alternatives such as list_campaigns. Usage context is clear but exclusionary guidance is absent.

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 clear. The description adds behavioral context by explaining the two modes of operation (single contact vs. list-wide) and the output fields (engagement score, tier, churn risk), which goes 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 two sentences, front-loaded with the core purpose, and includes a usage hint. Every word earns its place; no fluff or redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete enough. It explains the two modes, the output fields, and the recommended usage context. The only minor gap is that it doesn't specify the format of the output (e.g., JSON structure), but that's acceptable without 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?

The schema already provides 100% coverage for the single parameter (contact_id) with a clear description. The tool description adds value by explaining the behavior when contact_id is omitted, which is not fully captured in the schema. This is a good complement 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?

The description clearly states the tool's purpose: it retrieves engagement score, tier, and churn risk for a contact, or the lowest-engagement contacts when contact_id is omitted. This is specific and distinguishes it from sibling tools like get_deliverability_score or get_analytics.

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

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

The description provides clear context for when to use the tool ('Use before a re-engagement campaign') and explains the dual behavior based on contact_id presence. It doesn't explicitly mention alternatives, but the context is sufficient for an agent to decide when to invoke it.

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, fully covering the safety profile. The description adds the return content (score, grade, factors) but no additional behavioral traits beyond what is obvious from the name and schema. The description does not contradict 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 sentences, zero wasted words. The first sentence defines the tool's output, and the second gives a clear use case. 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 tool with no parameters and no output schema, the description is nearly complete. It specifies the output and a typical use case. It could be slightly more complete by explicitly stating it returns account-level data, but the current text is sufficient.

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

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

There are no parameters, so schema coverage is 100% by default. The description adds value by explaining the tool's output (score range, grade, factors) beyond the empty schema. Baseline for 0 parameters is 4, and the description meets that by providing purpose and return details.

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

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

The description clearly states the tool retrieves the account deliverability score (0–100) and letter grade (A–F) along with contributing factors. It explicitly names the output format and scope, and the 'Start here' hint differentiates it from more detailed sibling tools like run_deliverability_audit.

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 includes explicit usage guidance: 'Start here when asked why emails are landing in spam.' This clearly indicates the primary use case. However, it does not explicitly mention when not to use this tool or name alternatives, leaving room for slight ambiguity.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds the key side effect 'marks the email as read', which is crucial. It also enumerates what content is returned. It doesn't mention authentication or rate limits, but those are not critical for a simple read-like operation. No contradiction with 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 two short sentences. The first states the purpose and content coverage, the second reveals the side effect. It is front-loaded and contains no filler. Every word adds value.

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

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

With only one parameter, no output schema, and low complexity, the description fully captures what the tool does, what it returns, and its side effect. Annotations cover safety profile. Nothing essential is missing.

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

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

The schema covers 100% of parameters (only 'id' with description 'Email ID (UUID)'). The description merely repeats the parameter name and doesn't add extra meaning, such as where the ID comes from or format nuances. Baseline 3 is appropriate since the schema already documents it.

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

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

The description clearly states the action (read full content), the resource (single email), and the scope (by ID, including headers, body, attachments metadata). It distinguishes from sibling tools like list_emails which likely provide summary metadata without full content.

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 when to use this tool (when full content of a specific email is needed). It doesn't explicitly mention alternatives or exclusions, but the context with siblings like 'list_emails' and 'archive_email' makes the usage obvious. A brief 'use this instead of list_emails when you need full content' would be 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds expected return contents but no additional behavioral context 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?

The description is a single, front-loaded sentence with no wasted words. It gets straight to the point and effectively communicates the purpose.

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 one-parameter read-only tool with comprehensive annotations and no output schema, the description sufficiently conveys the tool's purpose and return contents. No further context is needed given the low complexity.

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 input schema provides 100% coverage with a clear description of form_id ('Form ID (UUID)'). The tool description adds no extra meaning to the parameter, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action (Get), the specific resource (one signup form), and the scope of returned data (fields, embed code, redirect behaviour). This distinguishes it from sibling tools like list_forms (which lists forms) and get_form_submissions (which gets submissions).

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: use when you need details of a single signup form by ID. However, there is no explicit guidance on when to use this tool versus alternatives, nor any mention of exclusions or when not to use it.

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, so the safety profile is covered. The description adds valuable context about the return content (field values and timestamps), which the annotations do not convey. This goes 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?

The description is a single, front-loaded sentence that states the action, resource, and scope without unnecessary detail. Every word 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 listing tool with complete parameter schema and solid annotations, the description provides a clear picture of what it returns (field values, timestamps) and covers the essential context. It could be slightly richer by mentioning pagination behavior, but the schema already covers pagination parameters, so this is adequate.

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

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

The input schema has 100% description coverage, so the baseline applies. The description does not add syntax or format details beyond the schema, but it does clarify that 'form_id' refers to a signup form and that results will include field values and timestamps, which indirectly relates to the 'form_id' and response semantics.

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

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

The description uses a specific verb ('List') and resource ('submissions for a signup form'), and adds what is included ('submitted field values and timestamps'). This clearly distinguishes it from sibling tools like get_form or list_forms.

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 context implies this tool is used when you need submissions for a signup form, but there is no explicit mention of when to use it over alternatives or when not to use it. Since it's a unique function among siblings, the guidance is implicit rather than explicit.

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

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

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds meaningful behavioral details beyond them: it returns every message in the conversation, ordered oldest first, and includes sender and timestamps. This supplements the safety profile with concrete return characteristics, though it does not mention pagination or full message content details.

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 sentence, front-loaded with the primary verb and resource, and packs essential details (scope, ordering, output fields) without any wasted words. It is highly concise and structured for quick comprehension.

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 tool with one parameter and no output schema, the description provides sufficient context: it states the operation, the scope (one conversation), the ordering, and the included fields. The only minor gap is that it does not explicitly state whether full message bodies are returned, but for a read-only fetch, this is relatively complete.

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

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

The schema already provides 100% coverage with a description for conversation_id ('Conversation ID (UUID)'). The tool description does not add any extra meaning about the parameter, so it stays at the baseline of 3 for high schema coverage. No additional semantic help is offered 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 uses a specific verb ('Get') and resource ('every message in one inbox conversation'), and clearly distinguishes from sibling tools like list_inbox_conversations (which lists conversations, not messages). It also specifies ordering and fields (oldest first, with sender and timestamps), which unambiguously states the tool's function.

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 clearly implies when to use it: when you need all messages from a specific conversation. It does not explicitly name alternatives or exclusions, but the purpose is so specific that an agent would infer the appropriate context relative to siblings like list_inbox_conversations or categorize_inbox_emails. No misleading guidance is present.

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

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

Annotations already declare readOnlyHint true, idempotentHint true, and destructiveHint false, so the safety profile is covered. The description adds value by specifying the returned content (configuration, scopes, last sync result), which is useful behavioral context in the absence of an 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?

The description is a single, clear sentence of ten words that fronts the verb and resource. It contains no wasted words or repetition of schema/annotation information.

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

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

For a simple read tool with one parameter and no output schema, the description adequately covers the purpose, scope, and expected return values. It does not describe error behavior (e.g., integration not found), but that is a minor omission given the low complexity.

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 input schema has 100% description coverage for the single required parameter integration_id ('Integration ID'). The description does not add further detail about the parameter, so it does not exceed the baseline for fully described schema parameters.

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 "Get one integration's configuration, scopes, and last sync result" clearly uses the verb 'Get' and specifies both the resource (one integration) and the scope of what is returned. This distinguishes it from siblings like list_integrations (which lists integrations) and toggle_integration (which toggles state).

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 'one integration' establishes clear context for when to use this tool—when you need details of a specific integration rather than a list. It does not explicitly name alternatives or exclusions, but the contrast with list_integrations is implied and the description is self-explanatory.

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 and destructiveHint=false, so the safety profile is known. The description adds value by disclosing the return contents (full preview, author, install count), which is especially useful given no output schema. No contradiction with 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?

A single, front-loaded sentence effectively communicates the core behavior without wasted words. It is concise and to the point.

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 getter with one parameter and no output schema, the description adequately covers the operation and key return fields. It could further clarify what 'full preview' includes, but the overall context is sufficient.

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 item_id described as 'Marketplace item ID'. The description does not add extra meaning about the parameter, so it relies on 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?

The description uses a specific verb ('Get') and resource ('one marketplace listing') with concrete detail ('full preview, author, and install count'). It clearly distinguishes from the sibling list_marketplace_items by emphasizing a single item.

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 usage for fetching a specific marketplace item but does not explicitly state when to choose this tool over alternatives like list_marketplace_items. No direct exclusion or alternative is mentioned.

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 readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds that results are tied to a time period ('for the period') and lists the specific metrics, which provides some behavioral context beyond annotations, though it does not disclose aggregation details or other constraints.

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 immediately states the action and resource, then lists the returned metrics. Every word contributes value; there is no fluff or redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description adequately covers the return value by enumerating the metrics. It could also clarify whether these are workspace-wide or per-newsletter, but given the tool's simplicity, the description is sufficiently complete.

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

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

The schema already fully describes the single 'period' parameter with an enum and default value. The description's phrase 'for the period' adds no additional semantic meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Get' with a clear resource 'newsletter monetization stats' and enumerates the exact metrics returned (paid subscribers, MRR, churn, sponsorship revenue). This distinguishes it from siblings like get_revenue_attribution or get_analytics, which focus on broader or different analytics.

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 when to use it (whenever monetization metrics are needed) but provides no explicit guidance on when not to use it or which alternative tools to prefer. Sibling tools like get_revenue_attribution or get_analytics overlap somewhat, and the description does not clarify 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 readOnlyHint and idempotentHint true, and destructiveHint false, so the description doesn't need to reiterate those. It adds context by naming specific outputs (revenue per campaign, per contact, average order value), which helps the agent understand what to expect. However, no mention of any side effects or limitations (e.g., data freshness, permissions) 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?

The description is a single sentence that concisely conveys the tool's purpose and key metrics. It is well-structured and front-loaded with the core action. Every word contributes value, making it efficient and easy to parse.

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 tool has no output schema, the description partially compensates by listing output fields (revenue per campaign, per contact, average order value). Annotations cover safety and idempotency. For a simple read tool with only two parameters, this is minimally complete, but could include more context on data scope or granularity.

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

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

Schema description coverage is 100%, with both period (enum, default 30d) and campaign_id (optional filter) well-documented. The description doesn't add new parameter semantics beyond what the schema provides, so baseline of 3 is appropriate.

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

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

The description clearly states the tool attributes revenue to email and lists specific metrics (revenue per campaign, per contact, average order value). It distinguishes itself from sibling tools like 'get_analytics' and 'get_campaign' by focusing on attribution, but could be more precise about what it doesn't do (e.g., raw analytics).

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 this is for tracking email-driven revenue, providing implicit context for when to use it vs. siblings like 'get_campaign' or 'get_analytics'. However, it lacks explicit guidance on when not to use it or mention of alternatives, which would help an AI agent decide.

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 value beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by warning about the consequences of exceeding warm-up capacity. It does not contradict the annotations, and the added context helps agents understand the importance of the tool's output.

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 consists of two concise sentences: the first states the function, and the second adds a crucial warning. No unnecessary words or repetition, and the key information 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?

The description explains the tool's purpose and importance but lacks details about the return format (e.g., whether it returns a percentage, number, or structured object). Without an output schema, the agent may not know how to interpret the result for downstream decisions, which is a 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?

The tool has zero parameters, and schema description coverage is 100% (trivially). Per the guidelines, the baseline score is 4. The description does not need to add parameter meaning, as there are none.

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 'Get IP/domain warm-up progress and today's remaining send capacity,' specifying the exact verb and resource. It distinguishes this tool from siblings like get_deliverability_score and send_campaign by focusing on warm-up status, which is unique among the sibling list.

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

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

The phrase 'Exceeding warm-up capacity on a new domain is the fastest way to get throttled or blocklisted' implies the tool should be used before sending to new domains to avoid issues. However, it does not explicitly state when not to use it or compare it to alternative tools for similar purposes.

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 flag this as destructive and non-idempotent, and the description adds real substance on top: existing addresses are skipped by default rather than duplicated, update_existing switches to overwrite, and results are returned per row with rejection reasons. That explains the blast radius and partial-failure semantics the annotations cannot convey. It still does not say whether the call is atomic on failure or what the batch limit does when exceeded.

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: the batch limit leads, the defaFault/override behavior sits in the middle, and the return shape closes. No filler and the most decision-relevant fact 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 supplies the return contract (per-row results with rejection reasons) itself, and it covers the batch cap, dedupe default, and the override flag. For a two-parameter bulk mutation whose annotations already state the safety profile, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so contacts and update_existing are already documented, including the default value on update_existing. The description restates and slightly enriches the duplicate-vs-update meaning but adds no syntax, format, or validation detail beyond the schema, so the baseline 3 applies.

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

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

"Bulk-import up to 5,000 contacts in one call" gives a specific verb, resource, batch scope, and a hard limit, which implicitly separates it from the singular create_contact/update_contact siblings. It never names those siblings explicitly, so the differentiation must be inferred from the word "bulk".

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 explains the default duplicate-handling behavior and how to switch it with update_existing, which is useful operational context. It does not state when to choose this tool over create_contact (single) or update_contact, nor any prerequisites such as required fields or scopes.

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 useful output context (per-variant results, winner status) but says nothing about pagination behavior, ordering, or what an unselected test looks like.

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 that front-loads the verb and resource before the return-content detail. No filler, though it is sparse enough that more useful context could have been added at little cost.

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, no-required-parameter list tool whose annotations cover the safety profile and whose schema fully documents all three parameters, the description is sufficient. It hints at the returned fields and there is no output schema requiring separate explanation.

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

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

Schema description coverage is 100%, with the type enum and its campaign/subject semantics fully documented in the schema itself. The description adds no parameter meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource (list A/B tests) and adds what the listing contains: per-variant results and winner-selection status. It is clearly distinguishable from the write-side siblings create_ab_test and select_ab_test_winner, though it does not explicitly name them.

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. The only usage signal is the imperative 'List', and the agent must infer that this is the read counterpart to create_ab_test/select_ab_test_winner.

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 mark the operation as read-only, idempotent, and non-destructive. The description adds a critical privacy guarantee — that key secrets are never returned — which goes beyond the annotations and clarifies the tool's output limitations.

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 provide all necessary information without redundancy. The key detail about secrets is stated separately for emphasis.

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 operation with no parameters and no output schema, the description adequately covers what the tool does, what it returns (metadata), and what it excludes (secrets). The annotations cover the safety profile, so no further context is needed.

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 accepts zero parameters, so the input schema is fully covered. The description provides no additional parameter details, which is appropriate given the empty schema. Baseline score of 4 for zero-parameter tools 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 clearly identifies the tool's action ('List'), the resource ('API keys on the account'), and the specific aspects included ('scopes and last-used time'). This unambiguously distinguishes it from sibling list tools focused on other resource types.

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 choose this tool over alternatives, nor any stated exclusions. However, the scope is clear from the name and description, so usage 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, idempotentHint, and destructiveHint, covering safety. The description adds context about returned fields (trigger type and active state) and example workflow types, but does not disclose pagination behavior, ordering, or other behavioral traits beyond what annotations and schema already imply.

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 well-structured sentence that conveys the core purpose and key output attributes without redundancy or filler. It is front-loaded and efficient.

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 list tool with no output schema, the description adequately states what is listed and what fields are returned. It does not explicitly mention pagination or the array return shape, but the schema’s page/limit parameters and the simple nature of the listing keep it sufficiently complete.

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

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

Schema description coverage is 100% for all three parameters, so the schema already fully documents page, limit, and status. The description does not add any extra parameter meaning, resulting in the baseline score.

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 identifies the tool as listing automation workflows and specifies the resource and scope with examples (welcome series, re-engagement, drip sequences). It does not explicitly distinguish from siblings like get_automation, so it misses the top score for 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?

The description provides no guidance on when to use this tool versus alternatives such as get_automation or list_ab_tests. No exclusions or preferred contexts are stated, leaving the agent to infer usage from the tool name and schema alone.

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 agent knows it is a safe read operation. The description adds return field context but does not disclose pagination behavior, rate limits, or ordering. This is consistent with the annotation baseline.

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 primary action and scope, and no filler. The second sentence adds a useful use case without restating schema details. Every word 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 complete schema and safety annotations, the description is nearly complete. It lacks explicit mention of pagination defaults or sorting, but these are inferable from the schema parameters. The description adequately covers the tool's purpose and typical usage.

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?

All three parameters are fully described in the schema (100% coverage), but the description adds meaning by explaining why to use the status filter (find drafts ready to send or campaigns still sending). This goes beyond the enum values and gives practical semantic value.

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

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

The description clearly states the tool lists email marketing campaigns with specific returned fields (status, audience size, headline metrics). This distinguishes it from sibling tools like get_campaign (single item), create_campaign, or send_campaign, leaving no ambiguity about its purpose.

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

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

It provides concrete usage context by suggesting filtering by status to find drafts or in-flight campaigns. It does not explicitly name alternatives (e.g., 'use get_campaign for a single campaign'), but given sibling names and this description, the intended use case is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that it returns subscription status and engagement metrics, which is useful context beyond annotations, but does not disclose pagination behavior or potential rate limits. This is acceptable given 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 two sentences, front-loaded with the core purpose, and every sentence adds value. No fluff or redundancy.

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

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

For a simple list tool with good schema coverage and idempotent/readOnly annotations, the description covers the key aspects: what it returns, how to filter, and a practical use case. No output schema exists, but the description mentions the fields (subscription status, engagement metrics) which partially covers return info. It is slightly lacking in discussing pagination or total counts but that is addressed by schema parameters.

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

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

All four parameters are fully documented in the schema (100% coverage), so the description adds little beyond the schema. The description does not elaborate on parameter usage, but the schema already includes descriptions for each. The baseline of 3 is appropriate because the description does not contradict or add much value.

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

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

The description clearly states the tool lists contacts and includes specific details about subscription status and engagement metrics, which distinguishes it from generic list tools. It doesn't explicitly compare to siblings, but the context of filtering by status for unsubscribed/bounced addresses is specific enough.

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

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

The description provides a clear when-to-use context: 'Filter by status to find unsubscribed or bounced addresses that should be excluded from sends.' It does not mention alternatives but the sibling list is large and this tool is uniquely about contacts, so the guidance is adequate.

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. The description adds value by specifying that results include verification status and DNS records, and by framing the typical invocation scenario. No contradictions.

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 sentences: the first states purpose and output, the second gives a concrete use case. No redundant words, every sentence serves a purpose.

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 adequately covers what the tool returns (domains with verification status and DNS records) and when to use it. It lacks explicit mention of the response format (e.g., array), but for a simple list tool this is acceptable, especially given no output schema. Sibling context 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% (both page and limit are described in the input schema with defaults). The description does not add any additional parameter meaning beyond what the schema already provides. Baseline 3 applies.

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

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

The description clearly states the verb 'List' and the resource 'sending domains', specifying the included fields (verification status, DKIM/SPF/DMARC records). It also provides a specific use case (check when a send fails with unverified-sender error), which distinguishes it from siblings like check_dmarc or verify_domain.

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 includes explicit guidance: 'Check here first when a send fails with an unverified-sender error.' This gives a clear context for use. While it doesn't list alternatives or exclusions, the context is strong enough for an agent to decide.

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, covering the safe read-only nature. The description adds some functional context (mailbox folder, optional search) but does not describe return shape, pagination behavior, or sorting. This is adequate but not enriched 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 concise sentences with no filler. The first sentence states the core function, and the second provides a direct pointer to an alternative tool. Every word 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 listing tool with three optional parameters and strong annotations, the description covers the key context: what is listed, where it is listed from, optional search, and when to use a different tool. No output schema exists, but the tool's behavior is straightforward enough that this is acceptable.

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

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

Schema description coverage is 100%, and each parameter already has a meaningful description. The tool description adds minimal semantic value beyond the schema, mentioning full-text search and mailbox folder but not providing new parameter-level detail. Baseline 3 is appropriate.

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

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

The description clearly states the tool 'List emails from a mailbox folder with optional full-text search across subject and body', using a specific verb and resource. It distinguishes itself from the sibling tool list_campaigns by explicitly directing marketing sends elsewhere.

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 explicit usage context: 'Use this for reading the unified inbox; use list_campaigns for marketing sends.' This names an alternative and clarifies when not to use this tool, giving clear guidance beyond what the schema alone provides.

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 value by disclosing that results include embed status and conversion counts, which gives context beyond the annotations. It does not contradict annotations and provides useful return-field information.

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 conveys essential information without any filler. Every word contributes to the meaning, making it highly concise and well-structured.

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

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

Given the simple listing purpose, the combination of schema (which documents all parameters), annotations (which cover safety traits), and description (which mentions key return fields) is nearly complete. There is no output schema, but the description partially informs what the response contains. It could benefit from noting pagination behavior or that it returns an array, but this 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?

All three parameters (page, limit, status) have descriptions in the schema, achieving 100% schema coverage. The description adds no additional parameter-level meaning beyond 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?

Description uses a specific verb ("List"), a specific resource ("signup forms"), and specifies exactly what is included ("embed status and conversion counts"). This clearly distinguishes it from siblings like get_form (single form) and list_form_submissions (submissions), making its purpose 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 implies usage by stating what the tool does, but it does not explicitly state when to use it versus alternatives, nor does it mention any exclusions. Since sibling tools like get_form could be confused for this tool, the absence of explicit guidance is a gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about unified-inbox and detected intent, indicating the tool provides an overview. It does not contradict annotations. However, it does not detail pagination behavior or access scope, but with strong annotation coverage, this is a minor 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?

The description is two sentences, front-loading the core purpose and then providing usage differentiation. Every sentence adds value; no filler or redundancy.

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

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

With 6 parameters and no output schema, the description sufficiently explains the tool's purpose and filtering options. It mentions return fields (status and intent) but lacks explicit return format or pagination details. Given the complexity, it is mostly complete for an AI agent to use effectively.

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?

All 6 parameters are fully described in the input schema (100% coverage). The tool description does not add new meaning beyond what the schema already provides, so baseline 3 is appropriate. No additional semantic benefit is gained from the description.

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

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

The description clearly states the tool lists unified-inbox conversations (threads) with status and detected intent, and distinguishes from sibling tool 'list_emails' by specifying it is for individual messages in a folder. The verb 'List' plus the resource 'conversations' is specific and 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 explicit usage guidance: 'Use this for triage; use list_emails for individual messages in a folder.' This directly tells when to use this tool and when to use an alternative, making the selection clear for an AI agent.

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, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the 'sync status' context but does not disclose pagination behavior or return format, which are only implied by the schema. With annotations covering the safety aspects, this is a minor 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?

The description is a single, front-loaded sentence that clearly states the tool's action and scope with no wasted 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?

The tool is simple, with a small schema and strong annotations. The description covers the core function and the extra 'sync status' detail. While there is no output schema, the description sufficiently indicates what the response will contain. No major missing context.

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?

Both page and limit have detailed descriptions in the input schema, giving 100% coverage. The description does not add any parameter-specific 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?

The description uses a specific verb ('List') with a clear resource ('connected third-party integrations') and a specific detail ('and their sync status'). It clearly distinguishes from siblings like get_integration and toggle_integration.

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 does not explicitly state when to use this tool vs alternatives such as get_integration or toggle_integration. Usage is implied by the name and description, but no exclusions or alternative guidance is 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 the tool as read-only, non-destructive, and idempotent, so the description does not need to restate this. However, it adds no additional behavioral detail such as pagination behavior, result format, or rate limits. The description is consistent with annotations, so no contradiction 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, concise sentence that front-loads the action and resource without any redundant words or filler. It is well-structured and efficient.

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

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

The tool is simple with optional pagination and filtering parameters, but since there is no output schema, the description carries the burden of explaining return values. It implies a list via 'browse', but does not clarify whether it returns full items, summaries, or includes metadata. Overall it is adequate but not comprehensive.

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 input schema provides 100% coverage with descriptions for all four parameters (page, limit, search, category). The description itself adds no extra parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Browse' and clearly identifies the resource as the MisarMail template marketplace. It naturally distinguishes itself from the sibling tool get_marketplace_item, which implies retrieving a single item rather than browsing a collection.

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

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

The description provides general context (browse the marketplace) but does not explicitly state when to use this tool over alternatives like get_marketplace_item or list_templates. Usage is implied rather than directly specified, with no exclusions or alternative recommendations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's role is reduced. It adds context about the sandbox intercept mechanism, but does not disclose new behavioral traits beyond what annotations provide. No contradictions.

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 action. Every word adds value: 'List emails captured by sandbox mode' and then the explanatory context. No wasted words or redundancy.

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

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

Given no parameters, no output schema, and a simple list operation, the description is fully complete. It explains what the tool returns (emails captured by sandbox) and why it matters (for verifying templates/automations without delivery).

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 input schema has zero parameters, and schema description coverage is 100%. Baseline for 0 params is 4. The description does not need to add param info; it explains the tool's purpose sufficiently without parameter details.

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 'List' and resource 'emails captured by sandbox mode', distinguishing it from sibling tools like 'list_emails' and 'clear_sandbox'. It explains the sandbox mechanism, making the purpose immediately understandable.

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

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

The description provides clear context: 'use it to verify templates and automations without emailing anyone.' It implies this is for testing, not for production sends, but does not explicitly name alternative tools. The usage guidance is strong but lacks direct sibling differentiation.

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, covering the safety profile. The description adds that templates include variable placeholders, but no further behavioral details (e.g., pagination or filtering behavior) are disclosed. This is modest but not contradictory.

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 sentence with no filler, front-loaded with the action and resource. The trailing purpose clause is meaningful and earns its place without bloat.

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 three optional parameters and thorough annotations, the description sufficiently conveys purpose and return contents. The schema handles parameter details, and no output schema exists to require further documentation. It feels complete for a simple listing 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 parameter descriptions for page, type, and limit. The description adds no parameter-specific detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

Description opens with 'List saved email templates,' a specific verb and resource. The add-on 'with their variable placeholders' clarifies the output and distinguishes this from siblings like list_emails or list_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 'so you can pick one for a campaign or transactional send' provides clear context for when to use the tool. It does not explicitly provide negative guidance or name alternatives, but the context is sufficient for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds useful context about returning HTML and subject and previewing personalisation, but does not go beyond that to discuss authentication, rate limits, or edge-case behavior. This is adequate but not rich.

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

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

Two concise sentences, front-loaded with the action and output, with no redundant filler. 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 simple two-parameter preview tool with strong annotations, the description is nearly complete. It explains the purpose, output, and non-sending nature. The only minor gap is that 'sample variables' could be slightly ambiguous, but the schema clarifies the variable structure.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description mentions 'sample variables' and the output, but adds little semantic meaning beyond what the schema 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?

The description uses a specific verb ('Render') and resource ('a template'), and clearly states the output ('resulting HTML and subject'). It also distinguishes itself from sending tools by framing the action as a preview before sending.

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 explicitly says to use this tool 'to preview personalisation before sending anything,' providing clear usage context. It does not name alternative tools or explicit exclusions, but the guidance is sufficient for typical selection.

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 indicate a non-read-only, non-destructive operation with potential side effects (openWorldHint). The description adds context that sender/threading are auto-derived, but does not detail what happens with body content, authentication, or response behavior. This adds some value beyond annotations but leaves gaps.

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, concise sentence that front-loads the purpose and adds meaningful context. Every word earns its place, with no redundancy or filler.

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

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

Given the simple tool (3 params, no output schema, no nested objects) and full schema coverage, the description is adequate. It explains the crucial threading derivation but omits details like whether only one body type is needed, what happens without a body, or any constraints. For the complexity, this is reasonably complete.

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

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

Schema coverage is 100%, so baseline is 3. The description clarifies that threading headers are derived and 'only the body is required,' but this slightly conflicts with the schema requiring email_id. It adds some meaning but introduces ambiguity about required fields, so it does not fully elevate above baseline.

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

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

The description clearly states the action ('Reply to an existing email thread') with a specific verb and resource, distinguishing it from sending new emails (e.g., send_email, send_campaign) and other email operations. The mention of derived sender/threading info further clarifies its scope.

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 when to use this tool (when replying to an existing thread) and provides context about automatic threading, but it does not explicitly name alternatives or specify when not to use it. This is a clear context without exclusions, fitting a score of 4.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds only 'Returns prioritized findings,' which modestly informs outcome but does not disclose any additional behavioral traits such as execution time, rate limits, or prerequisite conditions. Given the rich annotations, the description provides acceptable but minimal added transparency.

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

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

The description is extremely concise: two sentences totaling 23 words, with no redundancy. The first sentence immediately conveys the broad scope, and the second sentence succinctly describes the output format. Every word is purposeful.

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 tool with no input parameters, the description covers the areas inspected (authentication, reputation, hygiene, content, blocklist) and states it returns prioritized findings. It is nearly complete but lacks mention of any prerequisites (e.g., domain verification) or error conditions, leaving minor gaps. Still highly functional for an agent.

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

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

There are zero parameters, and the schema coverage is 100%. According to the guidelines, with 0 parameters the baseline is 4. The description does not need to add parameter meaning since none exist, and it correctly omits any parameter-related 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?

The description clearly states a specific verb ("run") and resource ("deliverability audit"), and enumerates the components (SPF/DKIM/DMARC authentication, domain reputation, list hygiene, content signals, blocklist) that distinguish it from sibling tools like check_dmarc, validate_email, or get_deliverability_score, which are narrower in scope.

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 does not provide any guidance on when to use this comprehensive audit versus the many sibling tools. For example, it does not say 'use this for a full assessment' or contrast it with simpler checks like get_deliverability_score. The context signals include sibling names, but the description itself offers no comparative 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=false, openWorldHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description still adds real value by specifying the concrete effect — a real send to the held-back audience segment — and reiterating irreversibility in user-facing terms. It stops short of explaining whether the test is closed, what happens to non-winners, or send-volume/rate implications.

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 with zero filler. The action is front-loaded and the risk warning follows immediately, which is the correct ordering for a destructive operation.

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

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

For an irreversible, open-world send operation with no output schema, the description adequately covers the core consequence an agent must understand before invoking. Minor gaps remain around preconditions (test state, whether a winner must already be selected) and what happens to contacts not in the hold-back group.

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

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

Schema description coverage is 100%, so the schema already documents test_id, winner_variant, and the metric enum with its 'default opens' behavior. The description adds no additional parameter meaning, making the baseline of 3 appropriate.

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

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

The description states a specific verb+resource pair ('Select the winning variant') and immediately extends it with the consequential second action ('send it to the remaining audience'). This is clearly distinguishable from siblings such as create_ab_test and list_ab_tests, which only create or enumerate tests rather than finalize them.

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

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

Usage is implied: an agent can infer this is the step taken once a winner has been determined. However, there is no explicit guidance on prerequisites (must the test be running? must a winner be statistically determined?), no named alternatives (e.g., send_campaign for normal sends), and 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 destructiveHint=true and readOnlyHint=false, but the description adds crucial context: it delivers real email, cannot be undone once sending starts, and recommends pre-confirmation. This goes beyond the annotations, though it could also mention rate limits 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?

Two sentences, each value-dense. The first states the action and the second provides risk warning and a safety tip. No fluff or redundancy; perfectly 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?

Given the tool's simplicity (2 params, no output schema) and the strong annotations, the description is largely complete. It covers the key behavioral risk and a usage guideline. Slight gaps: no mention of what happens after sending (e.g., confirmation response) or potential errors, but these are minor given the context.

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 documents both parameters well. The description reinforces the function of 'scheduled_at' (scheduling future time) but does not add details like timezone handling or validation rules. Baseline 3 is appropriate since the schema is sufficient.

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 clear verb ('Send') and resource ('campaign'), explicitly states the action (send now or schedule), and distinguishes itself from siblings like 'send_email' and 'create_campaign' by focusing on the execution of a campaign. It also highlights the irreversible nature of the action.

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 when to use this tool (when ready to send a campaign) and explicitly advises confirming the audience with 'get_campaign' first. It does not explicitly state when NOT to use it or list alternative tools, but the guidance to confirm audience is clear and practical.

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?

No annotations, so description must carry the load. It discloses the verification requirement Link and mentions return of message ID/queue status. Missing rate limits and explicit side effects, but the essential behavior (send, verify sender, queue) is 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?

Two sentences, front-loaded with the essential purpose mud plus the key prerequisite and outcome. No fluff.

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?

Rich schema covers parameter details; description adds the verified-sender requirement and return value (message ID/queue). Could mention rate limits or failure formats, but given the schema's depth, coverage is sufficient for invocation.

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

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

Schema already documents all 12 parameters with meaningful descriptions (format, max sizes, constraints). The description adds only the 'from' verification linkage, which is also in the schema. At 100% coverage, description adds minimal extra value, so baseline 3.

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

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

Clear verb+resource: 'Send a transactional email'. The qualifier 'transactional' distinguishes from campaign-send siblings like send_campaign. Mentions the source (verified MisarMail account), tying directly to the 'from' constraint.

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 actionable prerequisite guidance: 'use list_domains to check which sender domains are available'. No explicit when-not-to-use, but the verification check addresses the main failure mode. Could mention alternatives (e.g., template-based sends) but not necessary.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety is partly covered. The description adds real behavioral value by disclosing the side effect of activation: contacts start being enrolled and emails are sent on a schedule. It stops short of explaining what pausing does to in-flight enrollments or sends.

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 filler, with the core verb/resource front-loaded and the consequence following. 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 two-parameter state toggle with full schema coverage and rich annotations and no output schema, the description is nearly sufficient. The one gap is pause-side behavior (whether pausing stops in-flight sends/enrollments), which matters for a tool that triggers real email delivery.

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 (active, automation_id) are documented in the schema, including the true/false semantics. The description adds nothing 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 states a specific verb pair (activate/pause) and resource (automation), and it clarifies the consequence of activation. It implicitly distinguishes itself from get_automation/list_automations/create_automation by being the state-change operation, though it never names those siblings.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as create_automation or get_automation to check state first. The name of the action implies its use, but there is nothing explicit.

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

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

The description adds real behavioral context beyond the annotations: disabling halts all syncing and credentials are preserved, which is exactly the kind of side-effect detail an agent needs before a mutation. Annotations already establish idempotency and non-destructiveness, so this supplementary context earns credit without carrying the full burden.

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

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

Two short sentences, action stated first, consequence second. Every clause earns its place 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 two-parameter boolean toggle with full schema coverage and annotations covering safety/idempotency, the description supplies the key side-effect information. An output schema is absent, so explaining return values is unnecessary; only a minor gap remains around what 'enabled' returns or error conditions.

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 (enabled as true/false, integration_id as the ID). The description's mention of enable/disable maps to the enabled flag but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (enable or disable) and resource (an integration), making the operation unambiguous. It does not explicitly contrast with siblings like toggle_automation or get_integration, but the name and phrasing are distinct enough for an agent to disambiguate.

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 usage through the stated consequence (disabling stops syncing), which helps an agent reason about when to call it, but it offers no explicit when-to-use/when-not conditions or named alternatives. Usage is inferable rather than guided.

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 description need not disclose the mutation or idempotency profile. It adds meaningful value by explaining that setting status to unsubscribed immediately excludes the contact from every future campaign — a semantic consequence not captured by the annotations. It does not, however, clarify what happens to existing field values not supplied, nor confirm that the operation is safe/reversible.

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

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

Three sentences, front-loaded with the core action, then the critical warning about unsubscribed, then the unsupported-fields caveat. Every clause carries information an agent needs, with no 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?

Given a mutation tool with annotations covering the safety profile and 100% schema coverage, the description is nearly complete: it states the identifier, the update semantics, the destructive side-effect of unsubscribing, and the unsupported fields. It falls short only by not mentioning how partial updates behave (whether omitted fields are preserved) or the return shape, though 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%, and the schema itself documents all five parameters including the status enum. The description adds the important constraint that tags, phone, company, and job title are unsupported, which is genuinely useful since those are common CRM fields an agent might attempt to pass. For the parameters present, though, it adds no syntax or format detail beyond the schema.

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

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

States a specific verb (update) and resource (existing contact), names the identifying key (by email address), and explicitly delineates unsupported fields (tags, phone, company, job title). This differentiates it from create_contact and other sibling tools the agent might confuse it with.

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 clearly frames the use case (updating an existing contact by email, changing subscription status) and provides an implicit exclusion by noting what the API does not support. However, it does not explicitly contrast with alternatives like create_contact or import_contacts, nor does it state prerequisites such as whether the contact must already exist.

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. The description reinforces safety by stating 'Reads only: it never changes the plan or takes payment.' It also clarifies the side effect of open=true on local installs, which goes beyond annotations. That extra behavioral detail is useful, though not extensive.

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

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

Three sentences, front-loaded with the core purpose, then usage guidance, then behavioral notes. No wasted words, though slightly more verbose than necessary for a simple read tool.

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

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

Given a 2-parameter read-only tool with rich annotations and no output schema, the description covers what the tool shows and its behavioral constraints. The output format is not described, but that's acceptable without an output schema. Complete enough for correct invocation.

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

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

Schema coverage is 100%, so the schema already fully documents both parameters. The description adds minor context about open=true opening a browser link on local installs, but the plan parameter's default behavior is left to the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource: shows the MisarMail plan, quota remaining, and upgrade unlockables. Clearly distinguishable from siblings like get_analytics or get_warmup_status, which cover different resources.

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 'Call it any time — not only after hitting a limit,' giving clear context for use. No named alternatives or exclusions, but the open-ended guidance is sufficient for a read-only info tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safe read-only nature is known. The description adds value by detailing what the validation covers (syntax, MX, disposable, role-account), which is not in the annotations. No contradiction with 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 two sentences: the first defines purpose and scope, the second provides usage context. Every sentence is informative with no filler words or repetition.

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

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

Given the tool's simplicity (one param), the schema covers the parameter, annotations cover safety, and the description explains validation logic. The only missing piece is the return format (e.g., boolean vs. structured result), but that is a minor gap given the tool's nature. Overall, it is sufficiently complete for an agent to invoke correctly.

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

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

The schema has 100% coverage for the single parameter 'email' with description 'Email address to validate'. The tool description does not add any extra parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Validate' and the resource 'email address', and enumerates specific checks (syntax, MX records, disposable-domain, role-account detection). This makes it distinct from sibling tools like check_dmarc or verify_domain, which focus on different aspects.

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 scenarios: 'before sending' and 'Use this to protect sender reputation on imported lists.' It does not explicitly mention when not to use or alternatives, but the context is clear enough for an agent to decide. The usage guidance is practical and specific.

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 useful behavioral context beyond annotations: it mentions the 'mark it verified' side effect (consistent with readOnlyHint=false) and explains that retries are safe due to DNS propagation. This complements the idempotentHint=true annotation without contradicting any annotation.

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

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

The description is two sentences long, front-loaded with the core purpose, and every sentence adds value. It efficiently conveys the action, condition, and retry guidance without any waste.

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

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

Given the simple nature of the tool (one parameter, clear annotations, no output schema), the description is nearly complete. It explains what happens on success ('mark it verified') and the retry rationale, though it does not detail the behavior when DNS does not resolve. This is a minor gap for a tool of this complexity.

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

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

The schema fully documents the only parameter (domain_id) with a clear description ('Domain ID returned by add_domain'). The tool description does not add additional 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?

The description clearly states the action ('Re-check a domain's DNS records'), the resource (domain's DNS records), and the outcome ('mark it verified if they resolve'). It differentiates from siblings like add_domain (domain creation) and check_dmarc (DMARC-specific check) by focusing on domain verification.

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

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

The description provides clear context for when to use the tool: re-checking DNS records after a domain has been added, with a note on DNS propagation time. It implies this is a follow-up to add_domain but does not explicitly name alternatives or exclusions, so it stops short of a 5.

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