Check Mail Domains

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

Annotations already establish readOnly=true and destructive=false, so the safety profile is covered; the description adds real value beyond them by stating that checks are re-run on every call (no caching, so results are live but slow) and that the address belongs to the node and is shared by every app on it, which warns the agent that findings may not be app-specific. It does not cover authentication requirements or any rate limits against the external blocklist/DNS lookups.

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 purpose is front-loaded in the first clause, which is good, but the body is two long run-on sentences that pack the entire record-type inventory into prose with no structure. Every item listed is informative, yet the enumeration of SPF/DKIM/DMARC/MX/rDNS/TLS/blocklists/reports would read far better as a list, and some wording ('the address on Spamhaus, Barracuda...') is awkward.

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

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

For a multi-check diagnostic with no output schema and no annotations covering return shape, the description does enumerate what is inspected, which lets an agent infer the result set. It still leaves the five undocumented parameters unexplained and never indicates how findings are reported (per-domain sections, pass/fail vs raw records), which matters because there is no output schema to fall back on.

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 only 29%: only domain and selector are documented in the schema, and the description at most alludes to selectors ('the selectors seen signing') and the default domain set. workspaceSlug, appSlug, serviceName, env and region get no explanation in either place — notably env, whose enum meaning is never clarified, and region, which is unrelated to the DNS checks described. The description therefore does not compensate for the coverage gap.

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

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

The description names a concrete verb and resource: it discovers the service's sending domains (Postfix log/myorigin or Stalwart's domain list) and runs DNS/SPF/DKIM/DMARC/MX, rDNS, TLS, blocklist and DMARC-report checks against them. That is far more specific than the name or title alone. It does not, however, distinguish itself from the sibling checkDns or checkDomains tools, so an agent cannot tell from the text alone which one to reach for.

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

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

Usage is implied rather than stated — the described checks (SPF, DKIM, DMARC, blocklists, TLS) make clear this is a mail-deliverability diagnostic for a service. There is no explicit when-to-use, no exclusion against checkDns/checkDomains, and no note on prerequisites such as whether the service must be running or the mail feature enabled. 'Runs the checks on every call' is the one concrete operational caveat.

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