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?

It discloses reversibility and non-destructiveness ('REVERSIBLE', 'content is unchanged'), idempotency ('Safe to repeat'), and that it requires an API key. It also clarifies side effects ('does not mark read, reply, or notify'). This exceeds the annotations, which already claim destructiveHint=false and idempotentHint=true but do not mention the API key requirement or the one-message-per-call constraint. No contradiction with annotations found.

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 series of seven sentences, each adding distinct information: purpose, usage, safety, side effects, idempotency, requirement, and scope. It is more verbose than the ideal two-sentence example, but every sentence contributes to the agent's understanding without redundancy. The front-loaded opening states the core purpose immediately.

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

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

For a tool with a single parameter, no output schema, and minimal annotation coverage, this description is exceptionally complete. It covers the outcome (move to archive), behavior (non-destructive, reversible, no side actions), constraints (requires API key, exactly one message), and repeatability. An agent has all necessary context to invoke the tool correctly.

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

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

The parameter 'id' is fully documented in the schema (100% coverage) with the description 'Email ID to archive'. The tool description adds no specific elaboration about the parameter itself, though the note 'Affects exactly one message per call' indirectly confirms it refers to a single email. Given the schema covers the parameter adequately, a 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 begins with 'Move one email out of the inbox and into the archive', a specific verb+resource that clearly defines the action. It distinguishes from siblings by specifying what it does not do (does not mark read, reply, or notify sender), making it unique from tools like send_email or reply_to_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 provides explicit 'when to use' guidance: 'Use it to clear handled mail from the working inbox.' While it doesn't explicitly name alternative tools or say when not to use it, the behavioral limits (no reply, no notify) imply it is not for those actions. The use case is clear enough for an agent to decide when to apply 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 and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about what is checked (account, base URL) and implies a stored key, 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, with the first stating the specific checks and the second giving a clear usage directive. Every word adds value; 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?

For a simple, parameterless status check with no output schema, the description fully conveys what the tool does and reports. It also includes practical guidance on when to use it, making the entry self-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?

The tool has zero parameters, so the schema trivially covers 100%. Per rubric, a descriptor with no parameters starts at baseline 4, and the description appropriately confirms no arguments are needed.

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 authentication status, identifies the stored MisarMail account, and shows the targeted API base URL. This specific verb+resource combination distinguishes it from sibling tools like login/logout and get_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 instruction 'Run this first when a tool reports an auth error' provides a clear and explicit when-to-use scenario. It lacks explicit mention of when not to use or alternatives, but the context is strong enough for a diagnostic 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 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 include destructiveHint=true and idempotentHint=true. The description adds valuable context: it is irreversible ('cannot be undone'), all-or-nothing ('no filter'), requires an API key, and precisely scopes destruction to only intercepted test mail. It also reassures that an empty sandbox is harmless, which aligns with the idempotency hint.

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 five sentences long but every sentence earns its place: the purpose, scope boundaries, reversibility, parameter behavior, and safe-use caution. It front-loads the core action and logically expands from there, with no filler.

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

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

For a parameterless destructive tool with no output schema, the description is highly complete. It covers what is deleted, what is NOT deleted, reversibility, authentication, idempotency behavior, and a clear warning to read data beforehand. No significant gaps remain.

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

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

The schema has zero parameters, and the description explicitly confirms this: 'Takes no parameters and offers no filter.' It further elaborates the semantic consequence ('all or nothing'), adding meaning beyond the empty schema properties.

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

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

The description opens with the direct verb 'Delete' and identifies the precise resource: 'every email captured in the sandbox.' It clearly distinguishes this from sibling tools by emphasizing the sandbox scope and stating it affects only intercepted test mail, never campaigns, inboxes, contacts, or templates.

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 when to use this tool (to clear intercepted test emails) and provides clear caution: 'Read anything you still need from the sandbox before calling this.' It also notes that clearing an empty sandbox is harmless, offering safe usage context. It does not explicitly name alternative tools like list_sandbox_sends or archive_email, but the scope exclusion 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 provide idempotentHint=true and destructiveHint=false, so the description need not restate those. The description adds value by stating the return value (MX record) and the overall behavior (configuring routing). However, it does not disclose side effects like overwriting existing routing or DNS requirements, so transparency is adequate but not enhanced.

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 wasted words. The first sentence immediately states the purpose and outcome, the second sentence declares the return value. Highly 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?

With 100% schema coverage, annotations, and no output schema, the description covers the core purpose and return value. It is nearly complete, though it could mention prerequisites like domain verification. Given the context signals, this is a strong description.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The description's text ('Configure inbound email routing for a subdomain') aligns with the schema but does not add new meaning beyond what the parameter descriptions already provide. 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 verb 'Configure' and the resource 'inbound email routing for a subdomain', and specifies the outcome 'replies land in the MisarMail unified inbox' and the return value 'MX record'. This distinguishes it from siblings like add_domain, verify_domain, and 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?

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites (e.g., domain must be added via add_domain or verified via verify_domain), nor does it indicate when not to use it. The agent has no explicit context for decision-making.

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 provide readOnlyHint=false and destructiveHint=false, which are consistent with a creation tool. The description adds value by disclosing the two-phase behavior (sample sent first, winner later) and implicitly that the tool does not automatically select the winner. 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 no wasted words. The first sentence states the purpose, the second describes the process. Information is front-loaded 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?

No output schema is provided, and the description does not mention the return value (e.g., test ID). Prerequisites like campaign existence are not mentioned. The description explains the process but omits key context about what the tool actually 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 description coverage is 100% with clear parameter descriptions. The description adds minimal value beyond the schema, only hinting at the process. Baseline 3 is appropriate as the schema already documents the parameters well.

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

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

The description clearly states the verb 'Create' and the resource 'A/B test on a campaign', and explains the two-phase process (sample then winner). It distinguishes from sibling tools like 'select_ab_test_winner' and 'list_ab_tests' by describing the creation 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 the tool is used to start an A/B test and mentions the process flow, but it does not explicitly state when to use this tool versus alternatives (e.g., using 'select_ab_test_winner' later). No exclusions or prerequisites are given.

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

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

Annotations indicate a write operation (readOnlyHint=false) but provide no other behavioral clues. The description adds critical behavior: 'Created paused by default'. This is a key trait that influences when and how the tool should be used. It doesn't disclose return value or error cases, but the paused behavior is significant and well-stated.

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 with no wasted words. The first sentence states the purpose, the second adds the critical behavioral note. Front-loaded and efficient – 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 tool with 5 parameters, 2 required, nested objects, and no output schema, the description covers the primary purpose and the important paused-by-default behavior. However, it lacks mention of the return value (likely the created automation ID) and doesn't clarify that steps are optional despite being referenced as a core component. Still, the schema fills many gaps, making this description adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it simply restates 'trigger and an ordered list of steps' which is already present in the schema descriptions. It provides no examples, clarifies optional fields (steps is not required but is implied), or explains trigger_config. No extra semantic value is added.

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 ('Create an automation workflow') and specifies the key components ('from a trigger and an ordered list of steps'). It distinguishes the tool from siblings like toggle_automation by noting that the automation is created paused by default, requiring a separate activation 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 explicitly tells the agent when to use this tool (to create an automation workflow) and what to do afterwards ('call toggle_automation to activate once the steps are reviewed'). It also implies a workflow: create, review, then activate. This provides clear context for usage compared to 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?

The description discloses a critical behavior: 'Creating never sends' and that the campaign is created as a draft. This adds context beyond the annotations (which only indicate non-read-only, non-idempotent, non-destructive) and clarifies the lack of immediate sending side effects.

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—and clearly conveys the core purpose and the key behavior (no sending). It avoids superfluous words and is well-structured for quick understanding.

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 operation with no output schema, the description adequately explains that it creates a draft and does not send, but it omits details about the return value (e.g., campaign ID) and any expected side effects. Given the tool's simplicity, this is acceptable but not highly 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 per-parameter descriptions covering all 11 parameters (100% coverage), and the overall description does not add granular details about parameters. It only generically refers to 'content and audience,' which is already implied by the schema. Thus, it adds minimal value 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 clearly states 'Create a new email marketing campaign as a draft' and explicitly distinguishes it from sending by noting 'Creating never sends — call send_campaign separately.' This makes the purpose unambiguous and differentiates it from the sibling tool send_campaign.

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

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

It provides clear guidance to call send_campaign separately once content and audience are confirmed, implying the intended workflow. However, it does not explicitly mention when not to use other related tools (e.g., list_campaigns, update_campaign), but given the context, the guidance is sufficient.

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

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

The description implies a write operation ('Add') and mentions a side effect ('records consent'), but does not describe the return value or error behavior. The annotations (readOnlyHint: false) confirm mutation, but idempotency and reversibility are not addressed.

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 concise sentences, front-loaded with the primary action, and includes essential context without unnecessary verbosity.

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

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

The description covers the core action, relevant constraints (consent requirement), and legal implications. Combined with the complete parameter schema and annotations, the context is sufficient for correct 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 9 parameters have descriptions with types and constraints (e.g., max lengths for phone, source, company, job_title, last_name, first_name). The descriptions are clear enough for an agent to understand each parameter's purpose.

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 'Add a single contact' with a specific verb and resource, and distinguishes it from sibling tools like update_contact and list_contacts.

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

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

The description provides explicit usage guidance: 'only add addresses that opted in' and warns about sender reputation and legal compliance (CAN-SPAM/GDPR), which helps the agent decide when to use the 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 description discloses that subscribers flow into your contact list, which is an important side effect beyond the immediate creation. Annotations confirm readOnlyHint=false and destructiveHint=false, so the description aligns and adds value by clarifying the side effect. However, it does not mention other potential behaviors like whether it's idempotent, if landing pages have usage limits, or what happens on failure (e.g., duplicate name). With annotations already signaling a write operation, the description does enough to satisfy the bar.

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, efficient and front-loaded: the first sentence states the core action and resource, the second provides the key outcome and side effect. Every sentence adds unique value with no filler.

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

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

There is no output schema, so the description compensates by noting the return of a public URL, which is adequate for a creation tool. However, it does not mention any required permissions, error scenarios (e.g., duplicate name), or behavior of related contacts. Given the moderate complexity (6 parameters) and good schema coverage, the description is sufficient but leaves some questions unanswered.

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 itself documents all parameters thoroughly. The description only adds value by explaining the output ('Returns the public URL') and the side effect ('subscribers flow straight into your contact list'), but does not elaborate on any parameter meaning beyond what is in the schema. Baseline of 3 is appropriate as the description does not need to repeat schema info but also does not add depth.

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 action ('Create a hosted landing page with an email capture form' ) and a unique resource type ('hosted landing page'). It mentions a key outcome ('subscribers flow into your contact list'), which adds specificity. However, among siblings there are 'create_form' and 'create_campaign', and the description doesn't explicitly distinguish this landing page tool from those form or campaign creation tools.

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

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

No guidance is given about when to use this tool versus siblings like 'create_form' (for standalone forms) or 'create_campaign'. It does not state prerequisites (e.g., a verified domain) or when not to use it. The context is implied by the name and description, but explicit exclusions or alternatives are 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 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 indicate readOnlyHint is false and destructiveHint is false, suggesting this is a non-destructive but potentially state-changing operation (generation). The description does not add behavioral details beyond what annotations imply, such as rate limits, token consumption, or whether output is persisted. Without richer annotation context, a moderate score is appropriate.

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 ('Generate AI subject-line variants') and immediately providing context for downstream use. Every word is functional, and there is 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 tool has four parameters, one required, no output schema, and annotations that are present but minimal, the description adequately covers the key use case and suggests integration with 'create_ab_test'. It could be more complete by noting the default tone is 'professional' (implied by schema default), but overall it provides sufficient context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by clarifying that 'topic' is the core input ('what the email is about') and that 'tone' and 'audience' are optional tunings, which aligns with the schema. It reinforces the purpose of 'count' as variant generation quantity but doesn't add novel semantics beyond the schema's own descriptions.

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

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

The description clearly states the tool generates AI subject-line variants for a campaign topic, with optional tone and audience tuning. It distinguishes itself from siblings like 'create_ab_test' by positioning its output as input for that tool, though it could more explicitly differentiate from other generation or suggestion 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 provides clear when-to-use context by stating the output is good input for 'create_ab_test', which suggests a specific workflow. However, it does not mention when not to use this tool or indicate alternatives for other subject line generation methods.

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 readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable context beyond them: 'Reads only; reading a workflow does not enrol anyone or trigger a step.' It also warns about inactive automations and notes the API key requirement, enriching the agent's understanding of side effects and state.

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

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

The description is compact and front-loaded: the first sentence states the return value, the second provides usage context, and the third covers safety and state. Every sentence adds distinct value 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 absence of an output schema, the description thoroughly explains what is returned (trigger, steps, settings, enrolment counts), when to use it, side-effect safety, and the inactive-state caveat. This is complete for a single-resource read tool with strong 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?

Schema description coverage is 100% and the single parameter automation_id is already documented as 'Automation ID (UUID)'. The description does not add further parameter-level detail, so it meets the baseline for high schema coverage but does not exceed 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 tool's function: 'Get one automation workflow in full: its trigger, every step with its settings, and current enrolment counts.' It also distinguishes itself from siblings by explicitly referencing list_automations for listing and toggle_automation for start/pause, making its unique scope clear.

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 when-to-use guidance: 'Use it to understand exactly what an automation will do to contacts before activating it.' It also names alternatives: 'For the list of automations, use list_automations; to start or pause one, toggle_automation.' This fully addresses selection among sibling tools.

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

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

Annotations already 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 readOnly, idempotent, and non-destructive, and the description reinforces this with 'Reads only; the form is not modified and no submission is created.' It adds extra context beyond annotations by requiring an API key and clarifying that returning embed code does not publish anything.

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?

Every sentence earns its place: returns, use cases, alternatives, safety, auth, and embed code nuance. The main action is front-loaded, and the description is compact 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?

With no output schema, the description effectively explains what is returned: fields, embed code, and redirect destination. It also covers side effects (none), auth requirements, and sibling tool relationships, making it complete for a simple read tool.

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

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

Schema description coverage is 100% for form_id, so the schema already fully documents the only parameter. The description adds context about what the returned form contains but does not add parameter-specific semantics 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 states a specific verb and resource: 'Get one signup form in full' and details what is included—fields, embed code, and redirect behavior. It also distinguishes itself from sibling tools by explicitly naming get_form_submissions and 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?

It gives explicit use cases: need the embed snippet or need to know its fields before interpreting submissions. It also tells the agent when NOT to use it by directing to get_form_submissions for submitted data and list_forms for the list of forms, making alternatives 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?

The description adds meaningful behavioral information beyond the annotations. While annotations already mark readOnlyHint and destructiveHint false, the description explicitly reassures 'Reads only; submissions are not deleted, and nobody is subscribed or emailed.' It also warns about PERSONAL DATA handling, requires an API key, and clarifies that an empty result is not an error. These details are not present in the annotations and significantly enhance the agent's understanding of side effects and prerequisites.

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 well-structured and mostly concise. It front-loads the core purpose, then adds usage guidance and safety notes. Some redundancy exists, e.g., 'Reads only; submissions are not deleted, and nobody is subscribed or emailed' repeats information already implied by the readOnlyHint and destructiveHint annotations map to 0 indices from structured data (though the phrasing adds clarity). The mention of 'Requires an API key' is extra but arguably outside the tool's direct scope believe it's useful). Overall, it is tight and purposeful, earning a 4 rather than a 5 due to slight 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 complexity (list with pagination) and rich schema, the description covers the essential aspects: what it does, what data it returns (values in each field), read-only safety, API key requirement, and the normal empty-result case. It doesn't specify the exact return structure (e.g., array format), but without an output schema, this is a minor gap. The description is sufficient for an agent to decide and use the tool correctly, so a 4 is justified.

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 already provides descriptions for all three parameters (form_id, page, limit) with high coverage (100%). The description adds no extra meaning to these parameters—it doesn't elaborate on pagination behavior, default values, or parameter formats. It does mention the form context via 'a signup form' and notes personal data is returned, but this is not parameter-specific. Given the schema fully covers parameter semantics, a 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 opens with a specific, action-oriented statement: 'List the submissions a signup form has received, including the values entered in each field.' This clearly defines the tool's primary function and scope (submissions per form), distinguishing it from related tools like get_form. It also specifies the type of data returned (values entered in each field), leaving no ambiguity about the tool's 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?

The description explicitly tells when to use the tool ('Use it to see who signed up and what they told you') and provides a direct alternative for a related use case: 'For the form's own definition, use get_form.' It also clarifies important usage nuances, such as 'Reads only; submissions are not deleted, and nobody is subscribed or emailed' and 'No submissions is a normal answer, not an error,' which help the agent decide when to invoke 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?

Beyond annotations, the description adds that it requires an API key, that message bodies are confidential, and that it returns the whole thread (potentially large output). These details about authentication, privacy, and performance are not covered by 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 concise, with no redundant information. It is well-structured: functionality first, usage context second, then side effects and requirements. Every sentence contributes 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?

It provides sufficient context: what it does, when to use, side effects, auth requirements, confidentiality, and output size. It adequately differentiates from siblings and covers the essential aspects for a read-only getter.

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 only parameter, conversation_id, is fully described in the schema ('Conversation ID (UUID)'), and the tool description does not add extra meaning. Since schema coverage is 100%, 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 clearly states the verb 'Get' and the resource 'every message in one inbox conversation', with details on ordering (oldest first) and content (sender, timestamp). It distinguishes from sibling tools like list_inbox_conversations by positioning it as the detail view for a single conversation.

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 explicitly says 'Use it to read a thread in full before replying or summarising', providing a specific scenario. It also clarifies it does not send, reply, or mark anything as read, differentiating it from mutating operations, and notes it is the 'detail view behind a conversation listing'.

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 mark readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower, but the description adds meaningful context: 'Reads only; it does not re-run a sync or change any setting. Requires an API key.' It also clarifies a subtle behavior about response semantics: permitted vs. successfully done, and points to the last sync result.

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 structured with a clear opening sentence stating what is returned, followed by usage context, then read-only and caveat notes. Every sentence earns its place; no filler or redundant restatement of the tool name.

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

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

For a single-parameter read tool with strong annotations and no output schema, the description fully covers intent, usage context, behavior, auth requirement, and limitations. The note about the difference between permissions and actual sync results adds important context for interpreting the response.

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

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

There is only one parameter (integration_id) and schema coverage is 100%, so the schema already documents it. The description refers to 'one integration' implicitly tying the parameter to selecting a specific integration, but it does not add meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get one integration, in full: its configuration, the scopes it was granted, and the result of its last sync.' It clearly distinguishes itself from sibling list_integrations by noting 'Covers a single integration — list_integrations gives the overview.'

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

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

Explicit guidance is provided: 'Use it to diagnose an integration that list_integrations shows as unhealthy, or to check which scopes were granted before relying on a capability.' It also names the alternative (list_integrations) and explains the singular vs. overview distinction.

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, but the description adds substantial context beyond that: it clarifies no installation or template creation occurs, requires an API key, and warns that listings are third-party claims not verified by MisarMail. These behavioral and trust details are valuable and not redundant 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 compact and well-structured: a clear opening sentence, followed by usage context, then safety and prerequisite warnings. Every sentence earns its place with no filler or repetition.

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

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

For a one-parameter read tool with good annotations and schema, the description fully covers the workflow (after list, before adoption), prerequisites (API key), return contents (preview, author, installation instructions), and a crucial trust caveat. No output schema is needed since the description specifies what is returned.

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 item_id ('Marketplace item ID'), so the schema already documents the parameter fully. The description adds no additional semantic detail about the parameter, so baseline 3 applies.

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

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

The description uses a specific verb+resource: 'Get one marketplace listing in full, with its preview, author, and installation instructions.' It clearly distinguishes from siblings like list_marketplace_items by specifying it retrieves a single item with full detail, and it positions itself as the read step before adopting.

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

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

Explicit when-to-use: 'Use it after list_marketplace_items to inspect a template before adopting it.' It also states what it is not for: 'this is the read step, and it does NOT install anything into the account or create a template.' This is strong guidance with alternatives and 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?

Despite strong annotations (readOnlyHint, idempotentHint, destructiveHint all safe), the description adds meaningful behavioral context: it explicitly confirms no billing state changes and no charges, notes the API key requirement, warns that revenue is in minor currency units unless stated, and clarifies that zero paid subscribers is a valid answer. This is genuinely useful beyond the annotations.

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

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

Four sentences, each earning its place: function summary, selection guidance, safety/read-only note, and currency/numeric caveat. No fluff, front-loaded with the core purpose, and efficiently 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?

With one optional param, no output schema, and rich sibling context, the description fully covers what an agent needs: what the tool returns, when to use it, when not to, read-only behavior, API key requirement, and a data-format caveat. Nothing important is missing for this low-complexity tool.

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

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

Schema coverage is 100% for the single optional period parameter, so the baseline is 3. The description adds the default ('default 30d' is also in the schema property description) and context that the period affects the trailing window, which the schema property description already covers. However, the description's focus on account-level totals and the inability to break down per campaign effectively frames the meaning of the period, adding semantic value. Slight bonus for clarifying how the parameter relates to the returned figures.

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') and resource ('newsletter monetization figures'), enumerates key metrics (paid subscribers, MRR, churn, revenue trend), and distinguishes itself from get_revenue_attribution. This goes well beyond a paraphrase of the title and gives a precise, specific 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?

Explicitly tells the agent when to use it ('how is the paid newsletter doing') and provides a concrete exclusion: because figures are account-level and not campaign-breakdownable, use get_revenue_attribution for per-campaign breakdowns. This is the clearest possible guidance 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 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 indicate readOnly=false and destructive=false, but the description adds context: it states that existing addresses are updated rather than duplicated and that per-row results are returned, revealing behavior beyond the annotations. This is valuable but does not cover all aspects (e.g., rate limits, transactionality).

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, directly states the key points (bulk limit, update semantics, per-row results) with no filler or redundancy. 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?

Given no output schema, the description adds essential context about return format (per-row results, rejection reasons). It does not mention prerequisites (e.g., required field email) but the schema covers that. For a bulk import tool, 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 description coverage is 100%, so both parameters are already documented. The description restates the max count and update behavior but does not add further detail beyond the schema. Baseline 3 is appropriate since schema carries the parameter burden.

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

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

The description clearly states the tool's function: bulk-import contacts with a defined limit (5,000) and update behavior. It also explicitly distinguishes from create_contact (single) and update_contact (single) by mentioning bulk import and update semantics.

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 bulk import ('up to 5,000 contacts') but does not explicitly contrast with single-contact tools like create_contact or update_contact. It lacks an explicit 'when to use this instead of alternatives' statement, though the bulk aspect provides implicit 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral context: reads are safe and have no effect, declaring a winner is irreversible and sends to the held-back audience, and early results on small samples should be treated with care. It also notes the API key requirement and that no winner means the test is still open.

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

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

The description is front-loaded with the core purpose and remains focused. Sentences like 'Reads only' and 'Requires an API key' slightly repeat information already implied by annotations or earlier text, but the extra caveats about small samples and winner selection earn their 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 adequately summarizes return content ('each variant's results and whether a winner has been picked yet') and provides safety and interpretation guidance. It does not detail response format or error cases, but for a simple list endpoint with optional pagination params, this 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?

Input schema coverage is 100% and all three parameters (page, type, limit) are already described clearly in the schema. The description does not add parameter-specific details, which is acceptable since the schema carries the full burden here.

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

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

Description opens with a specific verb and resource: 'List A/B tests on the account' and adds expected outputs: 'each variant's results and whether a winner has been picked yet.' This clearly distinguishes it from related siblings like create_ab_test 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?

It explicitly says when to use it: 'Use it to see which tests are still running and which are waiting on a decision.' It also warns that declaring a winner is a separate, irreversible action, providing an implicit when-not. It does not name the specific alternative tool, but the context is clear.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is already covered. The description adds meaningful behavioral context beyond annotations: it scopes to account-level keys, states the key requires an API key (auth context), and explicitly warns that secret values are never returned and that lost keys must be rotated rather than recovered—a genuinely useful safety/security caveat.

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 compact three-sentence block with clear front-loading: the first sentence establishes the verb and resource, the second adds the audit use-case and the key caveat about secrets, and the third clarifies read-only and auth context. Every sentence earns its place, though the second sentence could arguably be tightened without losing the important caveat.

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 0 params, a minimal schema, no output schema, and rich annotations covering safety, the description is fully adequate. It supplies security context (treat as sensitive), call-scope (account), and auth requirement (API key) that the schema and annotations do not. There's nothing missing for an agent to invoke and interpret this tool correctly.

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

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

The tool has 0 parameters, and schema description coverage is 100% (the schema is empty). With no params, the baseline is 4, and the description further clarifies the scope ('on the account') and the metadata-only nature of the result, adding meaning beyond the bare 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 lists API keys with scope and last-used metadata—a specific verb plus resource plus what's returned. The sibling space is large but all other tools are for email/campaign/contact/automation/domain operations, making this tool clearly distinct as the API-key listing operation.

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

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

The description explicitly frames when to use it—to audit access, spot unused/over-scoped/forgotten keys—and what it does not do (not returned secrets, no creation/revocation/rotation). It clearly distinguishes metadata listing from code actions and states the sensitive-security context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds that it requires an API key and that an automation may exist while inactive, so status should be read rather than assuming. This adds context beyond annotations, though it doesn't detail pagination 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?

The description is concise, front-loaded with the main purpose, and each sentence adds value. It covers usage, limitations, and safety in a compact form 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?

Given the tool's simplicity (3 optional params, no output schema), the description is complete enough. It explains the return content (status and enrolment counts), the limitation (no steps), and the read-only nature. It could mention pagination behavior but that is minor.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (page, limit, status) with descriptions. The description does not add extra meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists automation workflows with specific examples (welcome series, re-engagement, drip sequences) and includes status and enrolment counts. It distinguishes from siblings by noting that get_automation reveals individual steps, and it is clearly different from list_campaigns or list_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 says when to use it: to see what is running before adding another workflow that might overlap, and to find an automation id for get_automation or toggle_automation. It also notes that listing does not reveal steps, directing to get_automation for that, providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true, 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, idempotentHint, and destructiveHint, but the description adds valuable context: requires an API key, is read-only, and explains that zero conversion counts may indicate non-installation rather than poor performance. 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 concise and well-structured: the first sentence states the core purpose, the second provides usage context and differentiation, and the third adds an important interpretation caveat. Every sentence earns its place.

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

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

For a simple read-only list tool with three optional parameters and no output schema, the description is complete. It covers what is returned, how to use it, what it is not, authentication requirements, and a key interpretation cave about conversion counts.

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 clear description. The tool description does not add extra meaning to the parameters, 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 tool lists signup forms on the account with embed status and conversion counts. It distinguishes itself from get_form and get_form_submissions by explicitly scoping its output and 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?

Provides explicit when-to-use guidance: find a form id before get_form or get_form_submissions, and compare form performance. It also clarifies what it does not return (form submissions) and names the alternative 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=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?

The description goes well beyond the annotations by adding 'Requires an API key,' warning that 'an integration listed as connected can still be failing to sync,' and clarifying that 'an empty list means nothing is connected yet, which is not an error.' These are useful behavioral details not captured by readOnlyHint, idempotentHint, or destructiveHint.

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?

Every sentence earns its place: the first states purpose, the second gives usage context and alternatives, and the remaining sentences add important caveats about side effects, authentication, sync reliability, and empty results. It is dense but not bloated.

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

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

For a simple read-only list tool with no output schema and straightforward pagination params, the description covers what is returned, when to use it, follow-up tools, auth requirements, edge cases, and non-error conditions. Nothing important is missing.

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

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

Schema description coverage is 100% and both parameters (page, limit) are already described with defaults. The description does not add pagination semantics or defaults, so a 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 opens with a specific verb and resource: 'List every third-party integration connected to the account, with its sync status and when it last ran.' This clearly distinguishes it from siblings like get_integration and toggle_integration by defining both scope and output fields.

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

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

It explicitly states when to use this tool: 'Start here when a question involves external data,' and names exact alternatives: 'follow up with get_integration; to turn one on or off, use toggle_integration.' This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by emphasizing 'Reads only,' requiring an API key, noting that listings are third-party authored with variable quality, and clarifying that no installation occurs. It complements annotations without contradicting them, providing useful behavioral context beyond the structured metadata.

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 concise and each sentence contributes meaningful information: purpose, usage, constraints, disambiguation, and quality caveat. It is front-loaded with the main action, followed by usage guidance and clarification. There is no fluff or redundancy, making it 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?

For a simple listing tool with no output schema, the description covers the key aspects: it states the read-only nature, authentication requirement, and that results are third-party. It also guides next steps (inspect with get_marketplace_item). It could mention what fields are returned in the list, but given the sibling tool for details and the simplicity, it is sufficiently complete. Slight deduction for not describing the return format, but overall 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% coverage, meaning all four parameters (page, limit, search, category) already include descriptions in the schema. The description does not add any additional parameter-specific semantics; it only mentions 'search' and 'category' implicitly via the schema. Since the schema already handles parameter documentation, the description adds no extra value, 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 clearly states the tool's purpose: 'Browse the MisarMail marketplace for ready-made email and automation templates.' It uses a specific verb ('browse') and resource, and explicitly distinguishes itself from sibling tool list_templates by noting they return different things, making it 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 provides explicit when-to-use guidance: 'Use it to find a starting point instead of authoring from scratch.' It also states that it is browse-only and that nothing is installed or added to the account, and directs users to get_marketplace_item for deeper inspection. It explicitly names the alternative list_templates for account-owned templates, covering both usage and exclusions.

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

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

Annotations already declare readOnlyHint=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?

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds important traits: 'Requires an API key' states an auth need, 'Reads only; no template is created, edited, or sent' reinforces the safety profile, and 'a template rendered with a missing variable goes out with a visible gap' explains the consequence of missing placeholders. The empty-list note also gives edge-case behavior.

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

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

The description is well-structured and front-loaded: the first sentence states the core purpose, the second gives usage context and alternatives, and the third covers safety and edge cases. Each sentence earns its place with 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?

Despite no output schema, the description compensates by explaining what the return includes (variable placeholders), when to use it, what alternatives exist, auth requirements, and the empty-list case. For a simple read-only list tool with three optional params, this is fully complete.

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

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

The input schema covers all three parameters with descriptions (100% schema coverage), so the baseline is 3. The description does not add any extra parameter-level semantics beyond what the schema already provides, but it does not need to.

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 and resource: 'List the saved email templates on the account, with the variable placeholders each one expects.' It also explicitly distinguishes itself from a sibling tool by mentioning 'list_marketplace_items covers third-party ones instead,' ensuring the agent knows exactly which tool fits.

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 explicitly tells the agent when to use the tool: 'Use it to pick a template before composing a send, and to see which variables you must supply.' It also provides an alternative by pointing to list_marketplace_items for third-party templates, and clarifies that an empty list is not an error, giving the agent confidence in handling edge cases.

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 discloses meaningful behavioral details beyond the annotations: it opens the MisarMail authorization page, requires user interaction, and saves the API key to ~/.misarmail/config.json. The annotations already cover safety hints (not read-only, not destructive, idempotent, open-world), so the description adds value without contradicting them.

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

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

The description is two sentences long, front-loaded with the primary action, and every sentence adds useful context. It avoids fluff and clearly explains both the process and the outcome.

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 login tool with no output schema, the description explains the outcome (API key delivered and saved) and the interactive flow. It does not mention error cases or behavior when already authenticated, but the schema and annotations cover the key optional parameters and safety profile, making this complete enough 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?

Schema description coverage is 100%, so the parameters (port, force, app_url) are already well documented in the schema. The description does not add additional parameter-specific guidance, but it does mention the browser-based delivery and config file location, which indirectly relates to the flow. This meets the baseline for schema-covered 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 uses a specific verb ('Authenticate') and names the exact resource ('MisarMail account via browser'), making the tool's function immediately clear. It also distinguishes itself from sibling tools like auth_status and logout by describing the interactive browser-based authorization flow.

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 when to use the tool ('Authenticate with your MisarMail account via browser') and even contrasts it with the manual alternative ('no API key copy-paste needed'). It does not explicitly name sibling alternatives or exclusions, but the context is clear enough for an agent to select it over related auth tools.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds valuable context about the exact local file affected and crucially states that the server-side key is not revoked, a nuance not captured by annotations. This is informative and non-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 two concise sentences. The first sentence states the primary action and location; the second adds a critical caveat. Every word 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?

Given the tool's simplicity (no params, no output schema), the description is complete. It tells the user exactly what happens, where, and what does not happen, covering all necessary aspects for safe invocation.

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

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

There are zero parameters, so the baseline is 4. The description needs no parameter explanations, and the schema coverage is trivially 100%. No additional parameter semantics are required.

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 forgets the locally stored MisarMail API key, specifying the exact file path. It distinguishes itself from siblings like login and auth_status by describing the local logout action, and it clarifies what it does not do (server-side revocation).

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 when to use the tool (to log out locally) and explicitly directs users to an alternative action for server-side key revocation (delete it from mail.misar.io/developers). This provides clear usage context and an exclusion.

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 mark destructiveHint=true. The description adds context by stating 'triggers a real send' and 'cannot be undone', reinforcing the irreversible nature. It does not contradict annotations and provides meaningful behavioral insight 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?

Two sentences, front-loaded with the core action, no extraneous words. Every sentence earns its place by stating the action and its irreversible consequence.

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

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

The description covers the main action and consequence, but does not mention expected return values, prerequisites (e.g., test state), or error conditions. Given no output schema, slightly more detail on outcome would improve completeness.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (test_id, winner_variant, metric). The description adds no additional meaning or guidance for any parameter, achieving only the baseline.

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

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

The description clearly states the tool selects a winning variant and sends it to the remaining audience, using a specific verb and resource. It distinguishes from siblings like create_ab_test and list_ab_tests by focusing on the selection and execution 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 implies this is the final action in an A/B test (triggering a real send) and warns it cannot be undone, but it does not explicitly state when not to use it or suggest alternative tools for previewing or cancelling.

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?

The annotations already mark idempotentHint true and destructiveHint false, and the description adds substantial behavioral context beyond that: activating starts enrolling contacts and sends real emails without further confirmation, paused contacts are held rather than dropped, and the operation is safe to repeat. 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 appropriately sized and front-loaded with the core action. Each subsequent sentence adds high-value information: read the workflow first, activation sends real emails, pausing holds contacts, safe to repeat, and API key required. No filler or redundant content.

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

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

For a two-parameter toggle tool with strong annotations and no output schema, the description covers the prerequisite read, real-world consequences, idempotency, authentication, and the non-destructive nature of pausing. It is complete for the tool's 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?

Schema description coverage is 100%, so the baseline is 3. The description restates the active parameter semantics in prose ('ACTIVATING starts enrolling contacts... Pausing stops new enrolments') but does not add additional parameter-level detail 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 opens with 'Activate or pause one automation workflow,' a specific verb+resource pair that clearly states the tool's function. It distinguishes itself from the sibling toggle_integration by explicitly naming the automation workflow resource.

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 usage context, including the explicit prerequisite 'Read the workflow with get_automation first so you know what activating will actually send.' It also contrasts pausing with cancellation ('pausing is not a cancellation'), but it does not explicitly enumerate when not to use this tool versus other 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 provide idempotentHint=true and destructiveHint=false, but the description goes beyond: it discloses that disabling stops syncing (live behavior change), that the connection and scopes persist, that re-enabling resumes, and that repeats are safe. It also mentions the API key requirement, which is not in annotations. This adds significant behavioral context beyond the annotations.

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

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

The description is concise and well-structured. It leads with a clear one-sentence purpose, then explains behavioral changes, idempotency, and a prerequisite (list_integrations). Each sentence adds value, and there is no fluff. The structure is effective for an agent to quickly grasp the tool's effect.

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 complexity (two simple params, no output schema, annotations provide safety hints), the description is complete. It covers the behavioral impact (data flow stops), the non-destructive nature (credentials kept), idempotency (repeatable), auth requirement (API key), and a usage guideline (call list_integrations first). This is more than sufficient for an agent to use 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 input schema covers 100% of parameters with descriptions ('true to enable, false to disable' and 'Integration ID'). The description adds context about the meaning of enabled (on/off) and the effect on data flow, but it doesn't add syntax or additional format constraints beyond what schema provides. Baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The first sentence clearly states the verb ('turn') and resource ('third-party integration') with the scope (on or off). It immediately distinguishes itself from siblings by specifying toggling behavior rather than just listing or doing something else. The description adds nuance about live behavior that separates it from related tools like toggle_automation.

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 advises calling list_integrations first to avoid toggling blind, and explains the behavioral difference between disable and disconnect, which helps the agent decide when to use this tool. It also implies that this is not the tool for revoking credentials or permanent removal. This is clear 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?

The description discloses a key behavioral trait: setting status to unsubscribed immediately excludes the contact from future campaigns. This adds value beyond the annotations, which only indicate idempotentHint and non-destructive. It 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?

The description is two sentences, front-loaded with the main purpose, and includes a critical behavioral note. 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?

Given the tool has 9 parameters, 100% schema coverage, and no output schema, the description is sufficient. It explains the main action and a key side effect. It could mention that it replaces tags (as per schema) but that is already in the schema. Overall, complete enough.

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% description coverage for all parameters, so the description does not need to add much. It mentions 'including changing subscription status' which highlights the status parameter, but the schema already describes each parameter. 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 updates an existing contact by email address and can change subscription status. It distinguishes from create_contact and list_contacts by specifying 'existing contact' and the update 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 usage for updating contact details and subscription status, but does not explicitly mention when not to use it or alternatives. However, the context of updating an existing contact is clear, and the sibling tools like create_contact provide contrast.

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, openWorld, idempotent, and non-destructive. The description adds the key behavior of opening the checkout page in the browser when open=true, and clarifies that this is a general status/upgrade info tool. It does not contradict annotations and adds useful context about the optional side effect.

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 three sentences, front-loaded with the main purpose. Every sentence provides distinct value: what it shows, when to call it, and the key parameter behavior. 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 tool with 2 optional parameters, full schema coverage, strong annotations, and no output schema, the description is complete. It explains the primary purpose, usage timing, and the optional browser-opening behavior. 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter semantics beyond what the schema already provides. It mentions 'open=true' but that is exactly what the schema says. There is no bonus for repeating schema content.

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 'Show' and clearly states the resource (current MisarMail plan, quota usage, and what upgrading unlocks). It distinguishes the tool from siblings by focusing on plan and upgrade context, which is unique among the listed 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 gives explicit when-to-use guidance: 'Call it any time — not only after hitting a limit.' It does not mention alternatives or exclusions, but for this tool it is clear enough. A 5 would require explicit alternatives or when-not-to-use, so 4 is appropriate.

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