MailVakt

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

Despite annotations already covering the safety profile, the description adds substantial behavioral context: idempotent semantics for repeated calls, the domains:write permission requirement, and an explicit list of things it does NOT do (no ownership verification, no DNS modification, no reports until DNS is published). This is exactly the kind of extra disclosure annotations cannot carry.

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

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

Four compact sentences, each carrying distinct information (purpose, return value, idempotency, permission, non-behaviors), with the primary purpose front-loaded in the first clause.

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

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

No output schema exists, yet the description summarizes the return value (the DMARC rua address and account entry), states idempotency, the permission needed, and the boundary conditions. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 100% with a single required domain parameter whose format and example are already documented in the schema. The description's 'Takes a domain' restates the schema without adding syntax, normalization, or validation detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add a domain to the signed-in user's MailVakt account') and narrows the scope to 'DMARC report collection', which cleanly separates it from read-oriented siblings like list_domains and configure-oriented ones like generate_dns_records.

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

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

Gives clear context for when to reach for it (adding a domain for DMARC report collection) and spells out the resulting precondition (the reporting address must be published in DNS before reports flow), plus the domains:write prerequisite. It does not name an alternative tool to use instead in any scenario, so it falls short of a full when/when-not/alternatives statement.

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

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

Annotations already cover the read-only and open-world safety profile. The description adds substantial behavioral context beyond annotations: exactly what results are returned (SPF, DKIM, DMARC, alignment, sending IP, specific blocklist checks, detected issues) and important limitations such as not independently verifying DKIM signatures or determining the receiving provider's exact spam-filter decision.

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

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

The description is front-loaded with purpose, then returns, then limitations, then the input constraint. Each sentence adds distinct value, and there is no redundant or filler text.

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

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

With no output schema, the description must explain return values, and it does so thoroughly. Annotations cover safety, the schema covers the parameter, and the description supplies sufficient scope and caveats for an agent to call this tool correctly.

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

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

Schema coverage is 100%, so the single parameter is well documented by the schema itself. The description still adds meaningful usage guidance by clarifying that only headers should be provided, not the message body, which helps the agent avoid supplying the wrong input.

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

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

The description states a specific verb and resource: analyze raw email headers supplied by the user. It clearly scopes the tool to authentication and delivery investigations, which distinguishes it from sibling domain-level tools like diagnose_domain and get_dmarc_summary.

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

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

It gives clear context for use: investigate authentication or delivery issues, and it specifies a constraint to provide headers only, not the message body. However, it does not explicitly name alternative tools or when not to use this one.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description reinforces this by stating it 'never changes DNS or guarantees inbox placement' and that it uses 'DNS and policy-file lookups.' It also discloses the caching behavior of fresh=true and the blocklist scope (not Spamhaus), adding real operational context beyond the annotations.

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

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

Two dense sentences with no filler: the audit scope is front-loaded, followed by parameter behavior, then return values and limitations. Every clause carries information an agent needs.

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

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

Even without an output schema, the description spells out the return payload (graded scorecard, findings, proposed DNS fixes, public report permalink) and the safety/limitation profile is covered by annotations plus explicit statements. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the default-all behavior of checks and what fresh does. The description's mention of 'optional checks and DKIM selectors, and fresh=true' largely restates the schema, so the baseline 3 applies.

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

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

States a specific verb (audit/diagnose) and resource (a domain's email authentication setup), then enumerates the exact checks performed (SPF, DKIM, DMARC, MX, alignment, BIMI, MTA-STS, TLS-RPT, blocklists). That breadth inherently separates it from narrower siblings like get_dmarc_summary or analyze_email_headers.

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

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

Gives a clear triggering context: 'when troubleshooting email authentication or spam delivery.' It stops short of naming alternatives or stating when-not to use it (e.g. vs. analyze_email_headers for a single message), so it is clear but not fully routing.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, and the description reinforces this with 'Does not publish records or change DNS'. It adds genuinely new context: public DNS/policy lookups that may be cached, and that provider values/reporting addresses may require user input.

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

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

Four tight sentences, front-loaded with purpose, then goal semantics, return contents, and behavioral caveats. No filler; each sentence carries distinct information.

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

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

With no output schema, the description compensates by enumerating the returned artifacts (SPF, DKIM, DMARC, MTA-STS, TLS-RPT proposals, or provider setup instructions). An agent has enough to decide and invoke correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description still adds value by stating baseline is the default when goal is omitted and that providers fall back to detection, which are not in the schema text.

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

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

Names a specific verb (Propose/generate) and resource (email-authentication DNS records and policy files) with clear scope. It is unambiguous against siblings like get_dmarc_summary or diagnose_domain, which read rather than generate.

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

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

Gives clear context: baseline (monitoring, p=none) vs enforce (quarantine/reject), with baseline as the default, and notes providers can be supplied or auto-detected. It does not explicitly route the agent away from siblings or state prerequisites, but the when-to-use context is solid.

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

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

With readOnlyHint=true already covering the safety profile, the description adds genuinely useful behavior: required scopes (domains:read, reports:read), the zero-totals outcome when no reports exist, and an error when the domain is not in the account. It stops short of disclosing pagination or any rate/volume limits.

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

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

Front-loads the action and scope, then the parameters, then returned data, then permissions and edge cases, in one tight block. Every sentence carries distinct information with no filler.

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

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

There is no output schema, so the description correctly summarizes the return payload (report and message totals, pass/fail counts, per-source alignment and receiver actions). Error and empty-result cases are also covered, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, and the description largely restates what the schema already provides (1-to-90-day window, default 7, domain belonging to the user). It adds no syntax, format, or edge-case detail beyond the structured fields, so the baseline 3 applies.

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

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

States a specific verb (summarize) and resource (received DMARC aggregate reports) scoped to a domain in the signed-in user's account. It is clearly distinguishable from siblings like add_domain, list_domains, and diagnose_domain because it explicitly reads existing reports rather than creating domains or diagnosing.

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

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

Gives a clear precondition (domain must already be in the user's MailVakt account) and a negative boundary ('Does not add domains or generate report traffic'), which implicitly steers the agent away from add_domain. It does not, however, name a specific alternative tool for the domain-not-found or domain-addition cases.

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

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

Annotations already cover safety (readOnly, non-destructive, closed-world), yet the description adds real behavioral context: the possible return states (pending/received/expired), what findings accompany a processed result, that processing failures surface as errors, and the access caveat that anyone with the test ID can retrieve it.

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

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

Four sentences, front-loaded with the purpose before the status/findings detail and the security caveat. Each sentence carries distinct information; slightly dense but nothing is redundant.

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

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

With no output schema, the description compensates by enumerating return states, the findings payload when processed, and error behavior, plus the access caveat — everything an agent needs to call and interpret this read tool.

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

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

Schema coverage is 100% and the single parameter's description already says it is 'the id returned by start_inbox_test.' The description repeats that provenance but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Read) and resource (MailVakt email-receipt test), and explicitly ties itself to the sibling that creates the resource ('the ID returned by start_inbox_test'), distinguishing it from start_inbox_test at a glance.

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

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

Explains how to obtain the ID (from start_inbox_test) and constrains use to IDs supplied by the user or created in this conversation, plus a scope exclusion ('Does not measure placement at other mailbox providers'). Clear context and an exclusion, though it doesn't spell out the full when-not workflow.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds context the annotations cannot carry: the required domains:read permission and the empty-list return when the account has no domains. It stops short of describing result ordering or pagination.

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

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

Three tight sentences: what it returns, what it requires, and when to use it. The most decision-relevant facts (scope, permission, empty-list behavior) are front-loaded and nothing is padding.

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

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

With no output schema, the description carries the return-value burden and does so: it names the domain list and the DMARC reporting address field, plus the empty-list edge case, and identifies the permission needed. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so there is no argument semantics to explain; the description correctly states 'Takes no input.' Baseline for zero-param tools applies.

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

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

States a specific verb (List) and resource (domains) scoped to the signed-in user's MailVakt account, and names the field of interest (DMARC reporting address). It also explicitly declares the boundary 'does not enumerate domains belonging to other users,' which separates it from any account-wide or sibling lookup.

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

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

Gives clear workflow guidance ('Use to find the account's available domains before requesting DMARC summaries') and one exclusion (other users' domains). It does not, however, name which sibling to call for a filtered or per-domain view, so the routing is implied rather than exhaustive.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description adds the crucial non-idempotency note ('Creates a new test on each call'), the expiry constraint, and the required external action before the result exists. It stops short of stating auth requirements, rate limits, or what happens if the test expires unread, but the added context is well beyond the annotations.

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

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

Four short sentences, front-loaded with the action and return values, followed by the workflow and then the scope exclusions. Every sentence carries distinct information with no repetition.

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

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

No output schema exists, so the description supplies the return shape (test ID, unique recipient address, expiry). Combined with the follow-up step and the explicit non-goals, an agent has everything needed to call it and act on the result.

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

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

Schema coverage is 100% and the single parameter's own description already explains it as the sending domain. The description only restates it as 'optional expected sender domain', adding no format or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create an email-receipt test in MailVakt') and immediately scopes what the artifact is (test ID, recipient address, expiry). It is distinguishable from siblings like get_inbox_test, which it names, and from domain/DNS tools in the sibling list.

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

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

Gives an explicit workflow: the user must send a test message to the returned address before expiry, then call get_inbox_test to read the result. It also states exclusions — no email is sent and no inbox-vs-spam placement is measured — so an agent knows when this tool is the wrong choice.

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