MisarMail MCP Server
Server Quality Checklist
Latest release: v5.1.1
- Disambiguation4/5
Most tools are clearly separated by resource+action pairs, and descriptions explicitly differentiate near-neighbours like list_emails vs list_inbox_conversations and list_templates vs list_marketplace_items. A few analytics/reporting and deliverability tools sit close enough to cause occasional misselection, but the boundaries are mostly clear.
Naming Consistency4/5The overwhelming pattern is verb_noun snake_case, e.g. list_campaigns, get_campaign, create_campaign, send_campaign, toggle_automation, making tool names predictable. Minor outliers like login, logout, upgrade, and auth_status break the pattern slightly but are not confusing.
Tool Count2/557 tools is far beyond the 3-15 sweet spot and above the 25+ threshold for a single MCP server. Even for a broad email marketing platform, this creates a heavy navigation burden and many could be consolidated or split into focused servers.
Completeness4/5The toolkit covers the major email platform workflows: sending and receiving mail, campaigns, contacts, templates, automations, A/B tests, analytics, deliverability, domains, forms, landing pages, integrations, sandbox, and auth. Gaps exist for lifecycle operations such as no update/delete for campaigns or templates and no delete_contact/remove_domain, but agents can generally work around these.
Average 4.4/5 across 57 of 57 tools scored. Lowest: 3.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 26 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only and idempotent with destructiveHint=false. The description adds the report type list and date-range scoping but does not disclose output structure, pagination, or rate limits. This is adequate given annotation coverage, 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence plus a list, front-loaded with the core purpose. No wasted words or redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema coverage and annotations indicating a safe read operation, the description covers the essentials. However, it omits what the returned report contains or how to interpret it, and does not mention relationships to sibling analytics tools. This leaves some gaps for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all three parameters with descriptions (100% coverage). The description repeats the report type enum values without adding significant new semantics beyond clarifying the send_time_heatmap report. Baseline applies since the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a structured analytics report over a date range, listing four specific report types. This provides a specific verb ('generate') and resource ('structured analytics report') with scope, and the report types help distinguish it from sibling tools like get_analytics, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_analytics or run_deliverability_audit. It only describes what the tool does, not the context in which it should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only/idempotent safety profile, and the description adds meaningful behavior: data comes from tracked conversions and includes specific metrics (revenue per campaign/contact, AOV). It does not detail return format or pagination, but the description adds enough beyond annotations to be transparent about scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the core purpose and key output dimensions without any filler. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description lists the main output elements and data source, providing reasonable clarity for a 2-parameter read-only tool. It could mention default time range (already in schema) or whether results are aggregated vs. list-level, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—both `period` and `campaign_id` are described with enums and meanings. The description does not add additional parameter-level details, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific function: attributing ecommerce revenue to email, with explicit outputs (revenue per campaign, per contact, AOV). The verb 'Attribute' is slightly unusual for a retrieval tool, but the intent is unambiguous and it differentiates from broader analytics tools like get_analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied—this tool is for viewing revenue attribution from email campaigns—but there is no explicit 'when to use' vs. alternatives, nor any exclusionary guidance relative to siblings like get_analytics or generate_report. The description relies on the agent inferring its purpose from the name and context signals.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context: sender address and threading headers are derived from the original message. However, the statement 'only the body is required' is slightly misleading because email_id is a required parameter. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action. The second sentence is efficient but introduces a minor ambiguity around required parameters, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with only three parameters and no output schema, the description covers purpose and the key derivation behavior. It is sufficiently complete, though it could clarify the required email_id and what outcome to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good parameter descriptions. The description adds marginal conceptual context about the body being the main content, but does not significantly expand on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Reply') and resource ('existing email thread'), and distinguishes it from send_email by noting threading headers are derived from the original. This makes the tool's purpose unambiguous and differentiates it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (replying to an existing thread) and provides context that only the body is needed, but it does not explicitly name alternatives or state when not to use it. The sibling context (send_email) provides implicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey write operation (readOnlyHint false) and non-idempotency. The description adds useful behavior about variable substitution at send time and previewability via render_template. However, it does not disclose what happens on duplicate template names or whether the template is immediately available, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, two sentences, and front-loads the core purpose. Every sentence adds value, with no fluff or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 6 parameters, the description covers the essential purpose and a key behavior (variable substitution). It also references render_template for preview, tying it to the tool ecosystem. Lacking any mention of return values or error cases is a minor gap for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage with descriptions for all six parameters. The description reinforces the {{variable}} syntax but does not add new per-parameter meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' and identifies the resource as 'a reusable email template.' It also distinguishes from siblings by noting variable substitution and pointing to render_template for preview, clearly separating creation from listing or rendering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It instructs to use {{variable}} placeholders for personalization and notes they are substituted at send time, providing context for when to use this tool. It mentions render_template as a preview alternative, but does not explicitly exclude other tools like create_campaign or list_templates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false. The description adds that it uses AI and can be tuned by tone/audience, but does not disclose non-determinism, rate limits, or side effects. This is acceptable given annotations, 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, direct, no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and complete schema, the description covers purpose and primary usage, but lacks explicit return format. Still adequate for selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 parameters with descriptions. The description highlights 'optionally tuned to a tone and audience' which reinforces the tone and audience parameters, but adds no new syntax details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Generate' with a clear resource 'subject-line variants' and context 'for a campaign topic.' It also explicitly connects to a sibling tool 'create_ab_test', distinguishing its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states 'Good input for create_ab_test,' which signals a primary use case. It does not explicitly list alternatives or exclusions, but the context is clear enough for an AI agent to infer 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.
- Behavior3/5
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 known. The description adds that the tool returns subscription status and engagement metrics, and it mentions filtering by status. It does not describe pagination behavior, rate limits, or response format, but with annotations covering the read-only nature, the added context 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: the first states the core action and scope, and the second gives a concrete use case. There is no redundant information, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a low-complexity listing tool with four optional parameters and no output schema. The description covers the main functionality and a specific use case. It could be slightly more explicit about what engagement metrics are returned, but for a list operation with good schema coverage and read-only annotations, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all four parameters (page, limit, search, status) already documented. The description reinforces the purpose of the status filter by mentioning 'unsubscribed or bounced' but does not add substantial meaning beyond the schema. The schema already describes each parameter sufficiently, so the description adds only marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List contacts'—a specific verb and resource—and further specifies that it returns subscription status and engagement metrics. This clearly differentiates it from sibling tools like create_contact, update_contact, import_contacts, and get_contact_score, which involve different operations on contacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage context: 'Filter by status to find unsubscribed or bounced addresses that should be excluded from sends.' This tells the agent when to use the tool and the purpose of the status filter. However, it does not explicitly state when not to use it or mention alternatives for other contact-related tasks, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral trait not captured by annotations: a sample percentage is sent first and the winner is sent to the remainder only after selection. This is useful context for an agent. However, it leaves ambiguous whether winner selection is automatic or requires a separate tool call, which is a minor transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose and no redundant filler. Every word contributes to understanding the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core process but does not mention what the tool returns (e.g., an A/B test ID) or explicitly direct the caller to use select_ab_test_winner for winner selection. Given there is no output schema, this missing information leaves some ambiguity about the full workflow and how to proceed after creation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While parameter schema coverage is 100%, the description adds meaning by explaining the role of sample_percentage and the staged send behavior. It also confirms the variants requirement ('two or more variants'). This goes beyond the basic schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create an A/B test on a campaign with two or more variants.' It uses a specific verb and resource, and distinguishes it from sibling tools like select_ab_test_winner by focusing on creation rather than winner selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the name and lifecycle mention ('the winner goes to the remainder once selected'), but it does not explicitly state when to use this tool versus alternatives. There is no direct reference to select_ab_test_winner for the subsequent step, leaving the workflow partially implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the key behavior that creation does not send, which is valuable beyond the minimal annotations. However, this claim ('never sends') may contradict the scheduled_at parameter, which is described in the schema as scheduling the send. The description does not mention scheduled_at or any exceptions, making the behavioral disclosure slightly misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and each sentence provides essential information. No word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 11 parameters and no output schema, yet the description does not mention what the response contains (e.g., campaign ID) or any prerequisites like verified sender. The draft/send distinction is covered, but a create operation with this complexity would benefit from more context about return values or setup requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters have detailed descriptions in the schema. The description itself adds no parameter-level semantics, so it meets the baseline of 3 but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create'), the resource ('new email marketing campaign'), and the state ('as a draft'). It explicitly distinguishes from send_campaign by noting that creation never sends, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to call send_campaign separately after content and audience are confirmed, providing a clear when-to-use and when-to-use-alternative. The statement 'Creating never sends' establishes the boundary between creation and sending.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a concrete behavioral consequence: setting status to 'unsubscribed' immediately excludes the contact from every future campaign. This goes beyond the annotations, which already indicate idempotent and non-destructive, by explaining a customer-facing 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with a front-loaded main action and a key consequence. No redundant filler or repetition of schema details, every clause serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters and no output schema. The description does not state what the tool returns (e.g., updated contact object vs. success indicator) or how partial updates are handled. While the schema covers parameter details, the missing return semantics leave a gap for the agent to know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying that 'email' is the identifier and by giving the status parameter real-world consequences for 'unsubscribed'. This adds value over the schema's basic field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Update an existing contact by email address' with a specific verb and resource. It also highlights a key sub-feature (changing subscription status). It distinguishes from sibling tools like create_contact or import_contacts by emphasizing 'existing'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing contact' implies it is used for updating rather than creating, but the description does not explicitly state when to use this tool instead of alternatives. It offers no exclusions or cross-references to sibling tools like create_contact or import_contacts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as idempotent and non-destructive. The description adds the key behavioral trait that it consumes AI credits, which goes beyond annotations and helps the agent understand side effects. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose and adds a relevant cost warning. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is fairly complete: it states purpose, scope, and cost. It does not explicitly explain the return format, but the phrase 'label intent and priority' suggests the outcome. Given low complexity and good annotations, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with `email_ids` described as 'Email IDs to categorise (max 50 per call)'. The description's mention of 'batch' and 'triaged' adds slight context but does not significantly improve parameter understanding beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource: 'Run AI categorisation over a batch of inbox emails to label intent and priority.' It distinguishes itself from sibling email tools (send, archive, reply) by focusing on AI triage and labeling. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: 'Consumes AI credits — pass only the emails you actually need triaged.' This tells the agent when to use the tool (for triage) and provides a cost-based caution, though it does not explicitly name alternatives or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as idempotent and non-destructive, and the description usefully adds that it returns the MX record to publish. It does not contradict annotations and adds a key behavioral detail beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action, purpose, and return value without wasted words. It is concise and well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a configuration tool with three parameters, no output schema, and idempotent/non-destructive annotations, the description covers the core purpose and return value. It could mention prerequisites like domain verification, but the schema and annotations already provide sufficient operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with examples for domain and subdomain, and a clear description for the optional webhook_url. The tool description adds no extra parameter-level meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Configure') and names the exact resource ('inbound email routing for a subdomain'), with the clear outcome that replies land in the MisarMail unified inbox. This distinguishes it from sibling domain tools like add_domain 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating the purpose: configuring routing for replies to land in the unified inbox. It does not explicitly name alternatives or exclusions, but the intent is unambiguous enough for an agent to know when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the key behavioral detail that the automation is created paused by default and requires an explicit toggle to activate, which is beyond what annotations declare. It doesn't mention error handling or prerequisites, but annotations already indicate this is a mutation (readOnlyHint=false) and not destructive, so the added value is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and resource, and each sentence contributes essential information: the creation purpose and the paused-by-default/activation behavior. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested objects and no output schema, the description covers the essential creation flow and the next step. It doesn't mention that 'steps' is optional per the schema, but the schema itself communicates that. Overall, it's adequately complete 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 5 parameters, including nested step objects and enums. The description only rephrases the concept of trigger and steps without adding new parameter-level details, so it meets the baseline but does not go further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'create' and clearly identifies the resource as an 'automation workflow' composed of a trigger and ordered steps. This distinguishes it from sibling tools like get_automation or toggle_automation, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly directs the agent to use toggle_automation to activate the workflow after reviewing steps, providing a clear follow-up action. While it doesn't list when not to use this tool, the reference to toggle_automation gives adequate usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate readOnlyHint=false, etc., which is minimal. The description adds valuable behavioral context: it returns the public URL and explicitly mentions that subscribers flow into your contact list, a side effect beyond simple creation. This goes beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose and followed by key output and side-effect information. Every word adds value; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with no output schema, the description covers the primary return value (public URL) and the key side effect (subscribers to contact list). It is complete enough for an agent to anticipate the behavior, though it does not detail error cases or prerequisites, which are not critical for a simple create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds general context about email capture and contact list, which relates to tags and cta_text, but it does not specifically enhance understanding of any parameter beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a hosted landing page with an email capture form, which is a specific verb+resource combo. It distinguishes this from sibling tools like create_form and create_campaign by specifying 'hosted landing page' and the email capture function. Returns the public URL adds clarity about the output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use: when you want a hosted landing page that captures emails and sends subscribers to your contact list. It does not explicitly name alternatives or exclusions, but the use case is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not restate safety. It adds value by disclosing the return content (specific metrics and time buckets), which goes beyond annotations. No contradictions 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the main purpose, then lists metrics and options efficiently. Every detail earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only analytics query with good annotations and full schema coverage, the description conveys the key parameters and output dimensions (metrics, time grouping, scope). It does not describe the exact response shape, but no output schema exists and this is not critical for such a straightforward query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented. The description adds contextual meaning by mapping 'account or one campaign' to campaign_id and 'grouped by day/week/month' to group_by, but this is a modest improvement over the schema's own descriptions. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource: 'delivery and engagement analytics'. It enumerates the exact metrics (sent, delivered, opened, clicked, bounced, complained) and scoping options (account or campaign, grouped by day/week/month), making it distinct from sibling tools like get_deliverability_score or get_revenue_attribution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys the tool's scope ('for the account or one campaign') and grouping options, implying when it is appropriate to use. However, it does not explicitly name alternative tools or state when not to use it, so it lacks the exclusion guidance needed for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the dual-mode behavior (single contact vs. lowest-engagement list when contact_id is omitted) and the specific outputs (score, tier, churn risk). 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one efficient sentence, front-loaded with the primary action, and each clause earns its place. It communicates both invocation modes and the usage context without any waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter, good annotations, and no output schema, the description is quite complete: it names the returned fields, the conditional behavior, and the intended use case. It does not specify response format or limits on the list mode, but these are not essential for a low-complexity read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the single parameter contact_id is described in the schema. The description echoes the schema's note about omitting contact_id, adding no new semantic detail beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'Get engagement score, engagement tier, and churn risk for one contact' and clearly distinguishes the alternative mode when contact_id is omitted. This is a specific verb+resource with two explicit behaviors, making it distinct 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes the explicit usage context 'Use before a re-engagement campaign,' which tells the agent when this tool is appropriate. It does not name alternatives or exclusion criteria, but the clear when-to-use guidance is sufficient for a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: it discloses that existing addresses are updated rather than duplicated, and that per-row results are returned for rejected rows. This is significant because annotations are all false and provide no safety/intent hints. While not exhaustive, it meaningfully informs the agent of side effects and output expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the primary purpose, and each sentence earns its place: action, update behavior, and output. No filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description still explains the return value at a high level (per-row results with rejection reasons). It covers core invocation needs: bulk limit, update semantics, and feedback. It lacks some edge-case detail (e.g., behavior when update_existing=false), but is sufficient for an agent to select and call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both 'contacts' and 'update_existing' have descriptions), so the baseline is 3. The tool description reiterates the max-5000 limit and the update-existing behavior already present in the schema, adding no new parameter semantics beyond what is already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Bulk-import up to 5,000 contacts in one call,' which is a specific verb+resource statement that clearly distinguishes this tool from the sibling single-contact tools like create_contact and update_contact. The scope (bulk, max 5000) is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The bulk-import framing conveys clear context for when to use this tool (large-scale contact imports). However, it does not explicitly name alternatives or state when not to use it (e.g., for single contacts). This is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by specifying what the list returns (status, audience size, headline metrics) and a practical filtering scenario, going slightly 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose and followed by a practical tip. Every word earns its place; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description is sufficient: it explains the output content, and the schema covers pagination/status filters. The only gap is no explicit mention of return format, but the low complexity and good annotations make this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all parameters. The description adds a use-case nuance for the 'status' filter but does not introduce additional format or syntax details beyond the schema, matching the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('email marketing campaigns') and states the returned data ('status, audience size, and headline metrics'). This clearly distinguishes the tool from siblings like get_campaign 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a concrete use case: filtering by status to find drafts ready to send or campaigns still sending. This implies when to use the tool, though it does not explicitly mention alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns 'status and detected intent', but does not disclose additional behavioral nuances such as pagination defaults, ordering, or rate limits. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: the first states the purpose, the second gives usage guidance. It is front-loaded and contains zero filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 optional parameters and no output schema, the description sufficiently conveys the tool's core role, the type of results (conversation status and intent), and a triage use case. It could mention alternatives like get_inbox_conversation_messages for deeper message retrieval, but this is not critical for selecting the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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), so the baseline is 3. The description does not add parameter-specific meaning beyond the schema, such as how 'q' interacts with threads or how 'intent' filtering behaves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('unified-inbox conversations (threads)'), and specifies the valuable data included ('status and detected intent'). It also differentiates from the sibling tool list_emails by noting that the latter handles individual messages in a folder.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs when to use this tool ('Use this for triage') and provides a direct alternative ('use list_emails for individual messages in a folder'). This gives the agent clear decision criteria beyond the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe, non-mutating operation. The description adds that it returns prioritized findings and covers multiple areas, but it does not disclose other behavioral traits such as potential latency or whether it invokes external services. No contradiction with annotations, though the added context is modest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that packs a complete scope into a compact list of audit areas. Every word contributes meaning, with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex with multiple audit dimensions, and the description lists them all, giving the agent a clear sense of what the operation covers. With no output schema, the description notes the return type ('prioritized findings'), which is helpful but somewhat generic; additional detail on the output format (e.g., list vs. score) would improve completeness. The zero-parameter interface and strong annotations reduce the burden, so a 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is trivially complete. The description appropriately doesn't mention parameters. Given that there are no parameters to explain, the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run a full deliverability audit' and enumerates the specific areas covered (authentication SPF/DKIM/DMARC, domain reputation, list hygiene, content signals, blocklist status). The verb 'run' plus the resource 'full deliverability audit' is specific and distinguishes it from narrower sibling tools like 'get_deliverability_score' or 'check_dmarc'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this when a comprehensive, multi-area deliverability audit is needed. It implies a broader assessment than the focused sibling tools, but it does not explicitly name alternatives or state when not to use it, so it lacks full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, idempotentHint=false, no safety details), so the description carries the transparency burden. It adds valuable context: the requirement that from.email must match a verified account, the availability of list_domains for checking, and the return behavior (message ID and queue status). It doesn't disclose rate limits or error cases, but it goes 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Exactly two sentences: the first states what the tool does, the second covers the critical prerequisite and return value. No filler or redundancy, with the key action front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool (12 params, nested objects, no output schema), but the schema is exceptionally rich with per-field limits and descriptions. The description adds the missing big-picture context: purpose, verification prerequisite, and return format. It lacks details on async queue behavior and error conditions, but the overall package is solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 adds minimal parameter-level meaning beyond the schema — the from.email verification constraint is already restated in the schema's 'from' property description. The description's mention of return values is useful but not parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource combination: 'Send a transactional email from a verified MisarMail account.' The phrase 'transactional email' clearly distinguishes this from sibling tools like send_campaign, and the verification constraint adds scope specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by emphasizing 'transactional' versus campaign/marketing emails and explicitly references list_domains as a prerequisite to check available sender domains. However, it doesn't explicitly name alternatives (e.g., 'for campaign emails, use send_campaign instead'), so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds the specific validation checks performed (syntax, MX, disposable, role). This is useful behavioral context beyond the annotations, though it stops short of describing output structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The primary action and scope are front-loaded, and the usage guidance is concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single parameter, comprehensive annotations, and no output schema, the description is complete enough: it states purpose, checks performed, and a use case. It doesn't describe return values, but that is not expected given the simple nature of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'email' parameter. The description does not add additional meaning beyond what the schema already states, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's action ('Validate an email address') and its specific scope ('syntax, MX records, disposable-domain and role-account detection'). It distinguishes itself from siblings like get_deliverability_score by focusing on individual address validation before sending.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit use case is provided: 'Use this to protect sender reputation on imported lists.' This gives clear context for when to invoke the tool, though it doesn't mention exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds meaningful context about DNS propagation time and the conditional verification behavior, which goes beyond the structured annotations. No contradiction with readOnlyHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the action and outcome, then adds the retry guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with strong annotations, the description is adequate. It covers the core action, the conditional outcome, and retry rationale. It does not describe return values, but no output schema exists and the tool's purpose is simple enough that this is not a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter domain_id is fully described in the schema as 'Domain ID returned by add_domain'. With 100% schema coverage, the description does not need to add parameter details, and it does not, which is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Re-check a domain's DNS records') and the outcome ('mark it verified if they resolve'), distinguishing it from sibling tools like add_domain and list_domains. It is specific about the resource and condition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it should be used to re-check DNS after adding a domain, and retries are safe due to DNS propagation delays. It does not explicitly name alternatives, but the guidance is sufficient for typical invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false). The description adds useful behavioral context: it returns DNS records and the domain is disabled until verification. This goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and includes the key consequence. 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description fully covers the core action, return value, and next-step dependency. It integrates well with sibling tools like verify_domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the 'domain' parameter with an example. The description clarifies this is a 'sending domain', which adds a small amount of context, but doesn't provide syntax or validation details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a sending domain and returns DNS records to publish. It distinguishes this from sibling tools like verify_domain (which verifies) and configure_inbound_domain (which handles inbound).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the prerequisite workflow: DNS records must be published and verify_domain must succeed before the domain can send. It references verify_domain explicitly, giving context for the correct sequence, though it doesn't list alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, lowering the bar. The description adds valuable behavioral context: 'live' lookup, alignment problems, and exact record to publish. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, 26 words, front-loaded with the main action and results. 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter and no output schema, the description must explain the return value; it does by mentioning alignment problems and the exact record to publish. It also covers the scope ('any domain') and the fact it's a live check, making it complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single 'domain' parameter is 100%, with the schema describing it as 'Domain to check, e.g. example.com'. The description adds a minor nuance that any domain works, but this is more usage guidance than parameter semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Check' with a clear resource ('live SPF, DKIM, and DMARC DNS records') and states the output ('report alignment problems with the exact record to publish'). It also explicitly mentions it works for any domain, distinguishing it from likely sibling tools like verify_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it checks DNS records for any domain and reports alignment issues. However, it does not explicitly name alternative tools or state when not to use this tool, falling short of a fully explicit usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive. The description adds the list of returned fields, going beyond the annotations by specifying what 'full details' includes. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and resource, and then a compact enumeration of the returned data. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with strong annotations, the description gives sufficient information about return contents. The absence of an output schema is compensated by the explicit list of fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for campaign_id with a clear type hint. The description adds no additional parameter syntax or constraints, so it doesn't improve on the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves full details for a single campaign, naming specific data categories (content, audience segment, schedule, delivery statistics). This distinguishes it from sibling tools like list_campaigns (which lists campaigns) and create/send_campaign.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific campaign's detailed information is needed, as opposed to list_campaigns for a summary. It doesn't explicitly name alternatives or exclusions, but the 'full details' and 'one campaign' phrasing provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about warm-up capacity risks but doesn't disclose further tool behaviors like data freshness, response format, or rate limits. Given the strong annotations, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently state purpose and a critical warning. No filler or repetition of structured data (annotations/schema) means every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only status tool with good annotations and no output schema, the description mentions the returned data (progress, remaining capacity) and the importance of checking it. This 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters, and the schema coverage is 100% (empty schema). It doesn't add parameter-related details, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description provides a specific verb ('Get') and resource ('IP/domain warm-up progress') alongside an additional key datum ('today's remaining send capacity'). It clearly distinguishes from sibling tools like get_deliverability_score, which focuses on overall deliverability, not warm-up status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The warning about exceeding warm-up capacity strongly implies when to use the tool (before sending on a new domain), providing clear context. It doesn't explicitly name alternatives or exclusion scenarios, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, establishing safety. The description adds value by disclosing the output content (Verification status and DNS records), which is not present in the schema. It does not go into pagination behavior, but that is covered by the parameter descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the primary action stated first and the usage tip second. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with high schema coverage and annotations, the description provides all necessary context: what is listed, what fields appear, and when to use it. The output schema is absent, but the description adequately conveys the return content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters (page and limit) with descriptions, so the baseline is 3. The description adds no additional parameter-specific context beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'sending domains' and specifies the exact fields returned ('verification status and their DKIM/SPF/DMARC records'). This clearly distinguishes it from other sibling tools such as add_domain and verify_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence provides an explicit trigger condition: 'Check here first when a send fails with an unverified-sender error.' This tells the agent when to use the tool, though it does not explicitly mention when not to use it or alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds search and folder behavior, but doesn't disclose additional details like pagination or return format. It aligns with annotations without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and usage, no wasted words. Every sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 3 optional parameters and no output schema, the description covers purpose, usage context, and search capability. Combined with annotations and schema, it is fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. The description adds that search covers subject and body, but this is already present in the schema, so no significant extra value is provided beyond baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists emails from a mailbox folder with optional full-text search, giving a specific verb and resource. It distinguishes itself from list_campaigns by mentioning marketing sends.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (reading the unified inbox) and names the alternative tool (list_campaigns for marketing sends), providing clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses the irreversible send to the remaining audience, adding context beyond the destructiveHint annotation. It specifies what the destructive action is ('real send to everyone who was held back') and states it cannot be undone, which is valuable behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and resource, then a critical warning. 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action, the audience affected, and the irreversible consequence. While it doesn't mention prerequisites or return values, the tool is simple and the annotations (destructiveHint, openWorldHint) supplement the context adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all parameters with descriptions (100% coverage), so baseline 3 applies. The description does not add additional parameter-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: selecting the winning variant and sending to the remaining audience. It uses a specific verb ('select') and identifies the resource (A/B test winner), distinguishing it from sibling tools like create_ab_test or list_ab_tests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this is the final step after an A/B test concludes, sending to the held-back audience. It doesn't explicitly name alternatives or exclusions, but sibling tools show no competing select-winner tool, so the usage is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds critical context: it sends real email to real recipients and cannot be undone once started. This goes beyond the annotation by explaining the consequence of the destructive action. It does not add details on permission requirements or delivery behavior, but the warning is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and scope. Every phrase earns its place—the warning and prerequisite add substantive value without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, the description covers the critical elements: action, scheduling, irreversibility, and a prerequisite check. It lacks mention of return values or how to verify delivery, but with sibling tools like get_campaign and list_campaigns available, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage of parameter descriptions, so the description adds no new parameter-level detail. The mention of 'scheduled_at' for future scheduling echoes the schema rather than enriching it. This meets the baseline for well-schemaed tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: sending a campaign immediately or scheduling it via scheduled_at. It distinguishes itself from siblings like send_email by specifying 'campaign' as the resource. The verb 'send' 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to confirm the audience with get_campaign before sending, providing a clear prerequisite and alternative tool. It also explains the scheduling option, covering the two main usage modes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context by specifying the return value (score, grade, factors) and that it operates at the account level, which is valuable 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary outcome, then adds a clear usage trigger. 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, straightforward read-only getter) and strong annotations, the description fully covers what the agent needs: it explains what the tool returns (score, grade, factors) and when to use it. No output schema exists, but the description sufficiently describes the return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool has zero parameters; the schema is empty. The description adds semantic meaning by explaining the output (score, letter grade, factors) and the account-level scope, which helps the agent understand the data returned even without parameters. A baseline of 4 is appropriate for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: getting the account deliverability score (0–100) and letter grade (A–F), plus the factors dragging it down. It uses a specific verb (get) and resource (deliverability score), and the 'Start here' instruction distinguishes it as the entry point for spam-related questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: 'Start here when asked why emails are landing in spam.' This is clear context, though it does not mention alternative tools (like run_deliverability_audit) or exclusions, so it slightly misses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a significant side effect: 'marks the email as read', which goes beyond the annotations (readOnlyHint=false does not specify the nature of the mutation). It also specifies return contents (headers, body, attachments metadata), which is critical since there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary action. The side effect is clearly separated and every sentence carries necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read operation with no output schema, the description adequately covers both the return value (headers, body, attachments metadata) and the behavioral side effect (marks as read). No major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full coverage with 'Email ID (UUID)' for the id parameter. The description adds no extra param details beyond 'single email by ID', which is already conveyed. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and resource ('a single email by ID') and lists included content (headers, body, attachments metadata). This clearly distinguishes it from siblings like list_emails, archive_email, and 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage: when you need the full content of a specific email by ID. It does not explicitly exclusions or alternatives, but the tool name and description make the use case unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful context beyond annotations by explaining that sandbox intercepts sends instead of delivering them, which clarifies the tool's behavior and purpose. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two short sentences—and front-loaded with the core action. Every word provides meaningful information without redundancy, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and simple read-only intent, the description is complete. It explains what sandbox mode is, what the tool does, and a concrete use case. The sibling list and annotations further contextualize it, so no additional details are needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description need not explain parameters. The baseline score of 4 applies because there are no parameters to document, and the description does not need to compensate for any schema coverage gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists emails captured by sandbox mode, using a specific verb and resource. It explicitly distinguishes this from regular email listing by mentioning 'sandbox mode' and explaining that sends are intercepted rather than delivered.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: to verify templates and automations without emailing anyone. It also explains the sandbox behavior, but it does not explicitly name alternative tools or exclusion criteria, so it stops short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds context by stating it returns HTML and subject, and that it's for previewing personalisation, which is useful beyond the annotations. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the action and output, the second gives the use case. Every word earns its place, 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only 2 params, no output schema, and strong annotations, the description fully covers the tool's behavior: what it does, what it returns, and when to use it. It is complete for a simple preview tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the schema already documents template_id and variables with an example. The description adds minimal parameter-specific meaning beyond 'sample variables,' so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders a template with sample variables and returns HTML and subject. This specific verb+resource+output distinguishes it from sibling tools like send_email or send_campaign, which are for sending, not previewing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to preview personalisation before sending anything,' which clearly indicates when to use this tool and implies not to use it for actual sending. This effectively guides an agent to choose this over send-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds the explicit side-effect of 'Set open=true to open the checkout page in the default browser', which goes beyond annotations. It could further clarify the return format, but this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loaded with the core purpose. Every sentence adds value, with no unnecessary detail or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two optional parameters and no output schema, the description adequately covers what it displays, when to call it, and the optional browser-opening side effect. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100% coverage). The description repeats the open behavior but adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Show') and resource ('current MisarMail plan, how much of each quota is left, and what upgrading unlocks'), clearly distinguishing it from sibling tools that focus on emails, campaigns, or integrations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call it any time — not only after hitting a limit', providing clear when-to-use guidance. Although no alternative tool is mentioned, no sibling seems to overlap with plan usage display.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: adding a contact records consent to email them, and misuse can damage sender reputation and breach CAN-SPAM/GDPR. This is a critical constraint that is not captured by readOnlyHint, openWorldHint, idempotentHint, or destructiveHint, and it directly informs the agent's decision making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of two concise sentences. The first sentence states the core function, and the second adds a crucial warning. No filler or redundancy; every word contributes to clarity and safety guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, nested objects), the schema handles parameter documentation well. The description covers the key usage context and the most critical behavioral caveat (consent). It does not mention duplicate handling or return value, but the idempotentHint annotation (false) and the absence of an output schema mean these are less critical for selection/correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description enriches the semantics of the 'email' parameter by clarifying that providing an email implies recorded consent, which is a legal implication not stated in the schema. Other parameters (tags, custom_fields, etc.) remain adequately described by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Add a single contact' which clearly states the specific verb, resource, and scope (single vs. bulk). This distinguishes the tool from siblings like import_contacts (bulk import) and update_contact (modification).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool: only for adding contacts who have opted in, with an explicit warning about sender reputation and legal compliance. It does not explicitly name alternative tools like import_contacts for bulk operations, so alternatives are not stated, but the single-contact scope implies this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Misar-AI/misarmail-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server