Read-only Postfix troubleshooting MCP server that diagnoses why mail is stuck and prescribes provider-specific recovery steps.
Run a one-call doctor diagnosis combining queue, qshape, log stats, DNS checks, and prioritized findings with next steps.
Check DNS authentication: MX, SPF (syntax, lookup limit, IP authorization), DKIM selector keys, DMARC, and PTR/FCrDNS.
Inspect delivery-relevant non-default Postfix config (relayhost, TLS, SASL, limits, queue lifetimes) with secrets redacted.
Summarize the queue: counts per queue, top recipient/sender domains, grouped delay reasons, oldest message.
List queued messages filtered by queue, recipient domain, sender, reason text, category, or minimum age.
Build a qshape-style matrix by recipient or sender domain across message-age buckets.
Aggregate the mail log over a time window: totals, per-domain outcomes, still-failing domains, deferral/bounce causes, DKIM selectors seen.
Trace a single message (by queue ID or email) through the log to its final status.
Track per-destination deferral rates over time with an improving/worsening/flat direction.
Look up recovery playbooks for Gmail, Microsoft, and Yahoo by ID, pasted SMTP reply, or by scanning the server's current failures.
List postsleuth's failure reason categories and their hints.
Provides Gmail/Google Workspace delivery troubleshooting: recognizes Gmail SMTP deferrals and rejections such as 421 4.7.28 rate limits and 5.7.26–5.7.32 SPF/DKIM/DMARC failures, and returns Postfix-specific recovery playbooks, retry guidance, and links to Google's official documentation.
Why isn't Postfix delivering? postsleuth reads the queue (postqueue -j), the mail log and DNS, groups every stuck message by why it is stuck, and tells you what to do next. It works as a CLI and as an MCP server, so an AI agent can investigate a mail server without being able to touch it.
Demo uses generated snapshot data (testdata/gen.py) via --queue-file / --log.
go install github.com/Blackman99/postsleuth/cmd/postsleuth@latestor grab a binary for Linux, macOS or Windows from Releases.
Related MCP server: WolfTech DNS MCP Server
postsleuth doctor # queue + qshape + log + SPF/DKIM/DMARC/PTR, with next steps
postsleuth queue --domain .outlook.com
postsleuth shape --by sender # who filled the deferred queue
postsleuth trend --domain gmail.com # deferral rate over time — getting better?
postsleuth playbook # Gmail 4.7.28, Outlook S3150, Yahoo [TSS04]…: the provider's way back
postsleuth message F543B5DFCE # one queued message: route, DKIM, headers, redacted
postsleuth trace bob@example.org # one message, start to finish (from the log)
postsleuth dns example.com --ip 203.0.113.7When Gmail, Microsoft or Yahoo is the one refusing you, playbook (and the PLAYBOOK section of doctor) names the provider code, says whether Postfix's retries can succeed, and gives ordered recovery steps written for Postfix with links to the provider's own pages: 18 playbooks, from Gmail's 4.7.28 rate limit and 5.7.26 DMARC failures to Outlook.com's S3150 block list (SNDS, JMRP) and Yahoo's [TSS09]. postsleuth playbook --reply "…" looks up a single reply.
When one message is the question, message QUEUE_ID reads its envelope and headers with postcat -e -h -q (never the body) and shows which queue it sits in and since when, each recipient's status and delay reason, the Received: route with TLS, whether its DKIM signature aligns with From:, and header problems that get mail refused, such as bulk mail without RFC 8058 one-click unsubscribe. Output is redacted by default: domains stay, local parts become [user-1]@example.com, the subject and display names are hidden, credential headers are removed. --unredacted exists on the CLI only.
Postfix in a container or on another box: --wrap "docker exec -i mailserver" or run it over ssh.
{"mcpServers": {"postsleuth": {"command": "postsleuth", "args": ["mcp"]}}}All tools are read-only, and postfix_queue_message is always redacted. Requeue, flush, hold and delete exist only when the server is started with --allow-mutations, and each call still needs confirm: true.
Check the DNS records receivers use to accept or reject your mail: MX, SPF (syntax, 10-lookup limit, whether the sending IP is authorised), DKIM selector keys (presence, key size), DMARC policy and reporting, PTR with forward confirmation (FCrDNS) against myhostname.
| Name | Required | Description | Default |
|---|---|---|---|
| ips | No | sending IPs to check SPF authorisation and PTR/FCrDNS for (default: smtp_bind_address or myhostname's public A/AAAA) | |
| domain | No | sending domain (default: myorigin/mydomain from postconf) | |
| selectors | No | DKIM selectors (default: taken from opendkim log lines, else common names are probed) |
| Name | Required | Description |
|---|---|---|
| checks | Yes | |
| domain | Yes | |
| sending_ips | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds real context beyond them: it performs live DNS queries, reads local postconf values (myorigin/mydomain, smtp_bind_address, myhostname) and opendkim log lines to derive defaults, and probes common DKIM selector names as a fallback. It stops short of disclosing timeout or rate-limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with a tight enumerated list where every clause names a distinct check performed (SPF 10-lookup limit, DKIM key size, DMARC reporting). Dense but no filler; slightly long for one sentence but nothing is wasted.
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?
An output schema exists, so return values need not be described, and the annotations cover the safety profile. The description thoroughly scopes what is checked; the only gap is routing guidance against sibling diagnostic tools.
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 all three parameters documented, so the schema already carries the semantics; the description adds only the 'against myhostname' context. Baseline 3 is appropriate – no additional syntax or format guidance is provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete verb (check) and resource (DNS records receivers use to accept/reject mail) and enumerates the exact record families inspected: MX, SPF, DKIM, DMARC, PTR/FCrDNS. This is clearly distinct from every sibling, which are postfix config/queue/log tools – an agent can route to it without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the diagnostic framing (mail deliverability/authentication troubleshooting) but the description never states when to choose this over siblings like postfix_doctor, nor any exclusions or prerequisites. Adequate but leaves the when-to-use decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delivery-relevant non-default Postfix settings from postconf -n (relayhost, TLS policy, SASL, concurrency/rate limits, queue lifetimes, domains, milters). Secret-looking values are redacted.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| note | Yes | |
| settings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: only non-default settings are returned (postconf -n semantics) and secret-looking values are redacted, which matters for interpreting results. It does not mention rate limits or caching, which is minor for a local read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence: source of truth first, then the included categories in a compact parenthetical, then the redaction caveat. No filler, no repetition of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero inputs and an output schema present, the description needn't document return structure. It covers source, scope, categories, and the redaction caveat, leaving only usage routing unaddressed; the definition is essentially complete for a parameterless 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?
The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-argument tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (retrieve) and resource (Postfix settings from postconf -n) and scopes it precisely to non-default, delivery-relevant settings, enumerating the categories (relayhost, TLS, SASL, limits, queue lifetimes, domains, milters). This is clearly distinguishable from the diagnostic and queue-focused siblings without opening their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no indication of when to prefer this over postfix_doctor or the queue/log tools, and no prerequisites stated. The scope phrase 'delivery-relevant' hints at a use case but the agent must infer all routing decisions itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-call diagnosis of a Postfix server: queue summary, qshape of the deferred queue, log outcomes for the window, DNS authentication checks, and a list of findings with next steps.
| Name | Required | Description | Default |
|---|---|---|---|
| ips | No | sending IPs | |
| since | No | log window (default 24h) | |
| domain | No | sending domain for DNS checks | |
| skip_dns | No | do not run DNS checks |
| Name | Required | Description |
|---|---|---|
| dns | No | |
| log | No | |
| queue | No | |
| shape | No | |
| trend | No | |
| config | No | |
| findings | Yes | |
| identity | Yes | |
| problems | Yes | |
| warnings | Yes | |
| dns_error | No | |
| log_error | No | |
| queue_error | No | |
| generated_at | Yes | |
| provider_playbooks | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, non-open-world), so the description's job is to add operational context. It does disclose that output includes 'findings with next steps' and that DNS checks are part of the run, but it does not say the tool performs live DNS lookups, how expensive/slow an aggregated sweep is, what happens when ips/domain are omitted, or why idempotentHint is false (time-windowed results).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that names the tool's scope before enumerating components. Dense but every clause maps to real output; slightly long as an itemized list jammed into one sentence, but 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?
An output schema exists, so return values need not be explained. However, for a zero-required-parameter aggregator sitting among ten overlapping siblings, the definition is silent on what runs by default and how it relates to the individual tools, leaving the agent to guess selection policy.
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 parameters are already documented. The description only faintly reinforces them ('log outcomes for the window' hints at since, 'DNS authentication checks' hints at domain/skip_dns) without adding syntax, defaults, or interaction rules between ips and domain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('One-call diagnosis of a Postfix server') and enumerates exactly which artifacts are produced: queue summary, qshape, log outcomes, DNS auth checks, findings. This is far more concrete than siblings like postfix_queue_summary or postfix_log_stats, though it never names those siblings to establish the bundling relationship explicitly.
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?
'One-call' implies this is a broad sweep versus the narrower sibling tools, but that inference is left to the agent. There is no explicit when-to-use/when-not, no statement that this supersedes calling postfix_queue_shape + mail_dns_check separately, and no guidance on cost/latency tradeoffs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate the Postfix mail log over a time window: totals (received, sent, deferred attempts, bounced, expired, smtpd rejects), per-domain outcomes, domains still failing, grouped deferral reasons and bounce causes with category and hint, and DKIM selectors seen in signing logs.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | max entries per list (default 15) | |
| since | No | time window, e.g. 1h, 24h (default), 7d, or all | |
| domain | No | only this recipient domain (leading dot = include subdomains) |
| Name | Required | Description |
|---|---|---|
| since | Yes | |
| stats | Yes | |
| source | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=false, so the safety profile is covered. The description adds useful detail about what is summarized, including per-domain outcomes, failing domains, deferral/bounce groupings, and DKIM selectors. It does not add further behavioral context such as logging assumptions or performance limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence, front-loaded with the core action and scope. The enumerated outputs are useful for tool selection, though the list is long enough to be slightly burdensome.
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?
An output schema exists, so return values need not be fully explained. Combined with annotations and fully described parameters, the description is sufficiently complete for an agent to invoke the tool correctly, though it lacks explicit sibling routing guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented with their meanings and examples. The description reinforces the time-window concept but does not add syntax or edge-case semantics beyond the schema. A baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: aggregate the Postfix mail log over a time window. It also enumerates the main metric families produced. It is clear what the tool does, though it does not explicitly differentiate itself from aggregate-oriented siblings such as postfix_log_trend or postfix_reason_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a summary/overview use case by saying it aggregates over a time window, but it does not say when to choose this over postfix_log_trace, postfix_log_trend, or postfix_reason_categories. No exclusions or alternative-selection guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Follow one message through the log by queue ID or email address: every line for each matching queue ID (smtpd, cleanup, qmgr, smtp/local, bounce notifications) and its final status.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | max messages (default 20, newest kept) | |
| query | Yes | a queue ID (e.g. 4F2A1C3B9) or an email address | |
| since | No | time window (default 7d) |
| Name | Required | Description |
|---|---|---|
| source | Yes | |
| messages | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuine behavioral context by disclosing that output is the full line-by-line flow across pipeline stages (smtpd, cleanup, qmgr, smtp/local, bounce notifications) ending in a final status. It doesn't cover ambiguity handling when an email matches multiple queue IDs, which is the main remaining behavioral gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence: the verb and target come first, then the input forms, then the output scope. The parenthetical listing the pipeline stages earns its place by telling the agent which log components are traversed, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be explained, and all three parameters are documented in the schema. The description covers purpose, inputs and output scope for a read-only tool; only the multi-match / result-grouping behavior for email queries is left unstated.
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 limit, query and since are all documented in the schema. The description only restates that query accepts a queue ID or email address, adding no format or semantics beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a precise verb ('Follow') and resource ('one message through the log') plus the inputs that select it (queue ID or email address). The scope statement 'one message ... every line for each matching queue ID' clearly separates it from aggregate siblings like postfix_log_stats, postfix_log_trend and postfix_queue_summary without having to open any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (single-message forensics rather than aggregate statistics) and tells the agent what the query accepts, but never states when to prefer this over the log_stats/log_trend siblings or when-not to use it. Usage is inferable but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-destination deferral rate over time buckets from the mail log: sent/deferred counts and rate per bucket, plus a direction (improving / worsening / flat / insufficient_data) comparing the early vs late half of the window. Use to see whether Gmail/Outlook/etc. is getting better or worse.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | max destinations (default 15) | |
| since | No | time window, e.g. 1h, 24h (default), 7d, or all | |
| bucket | No | bucket size, e.g. 15m, 1h, 4h, 12h, 1d (default: auto from window) | |
| domain | No | only this recipient domain (leading dot = include subdomains) |
| Name | Required | Description |
|---|---|---|
| since | Yes | |
| trend | Yes | |
| source | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=false, so the safety profile is covered. The description adds useful context about what is computed (buckets, direction semantics) but discloses no operational traits such as cost, rate limits, or behavior on missing data. A 3 is appropriate with annotations carrying the safety burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, front-loaded with the core output shape before the usage hint. Every clause carries information, though the direction-value enumeration makes it slightly heavier than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only analytics tool with 100% schema coverage and an output schema, the description covers purpose, output content, and the direction interpretation well. It is complete enough to invoke correctly, with only marginal room for clarifying edge behavior.
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 all four optional params (top, since, bucket, domain) documented in the schema itself. The description alludes to windows and buckets but adds no format or default detail beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: computes per-destination deferral rate over time buckets from the mail log, returning sent/deferred counts, rate, and a direction verdict. This clearly separates it from siblings like postfix_log_stats or postfix_queue_summary, though it doesn't name those siblings explicitly.
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 usage context: 'Use to see whether Gmail/Outlook/etc. is getting better or worse.' That is a concrete when-to-use scenario. It stops short of naming alternatives (e.g. postfix_log_stats) or stating exclusions, so it lands at 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recovery playbooks for the big mailbox providers: Gmail / Google Workspace (421 4.7.28 rate limit, 5.7.26-5.7.32 SPF/DKIM/DMARC, PTR, TLS, reputation), Microsoft Outlook.com / Microsoft 365 (S3150 block list with SNDS/JMRP, 5.7.606-649 banned IP, 5.7.511, 4.7.650, SC/DY/OU/RP codes, 5.7.515, 5.7.705-750) and Yahoo / AOL ([TSS04]/[TS*] deferrals, [TSS09], [BL21]/[BL23], 5.7.9). Each playbook says what the code means, whether Postfix will retry or retrying is pointless, ordered steps (Postfix-specific, e.g. a dedicated transport with destination_concurrency_limit = 1 for Gmail 4.7.28; never flush the queue at a throttling receiver), and the provider's official pages. Modes: with no arguments, scans the queue and the mail log (since, default 24h) and returns the playbooks for what is failing here with evidence counts and affected domains; with reply, looks up one pasted SMTP reply without reading the server; with id, returns one playbook. Read-only: it never contacts the providers or changes the queue.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | return this one playbook, e.g. gmail-4.7.28, microsoft-s3150, yahoo-deferred (see available) | |
| reply | No | one SMTP reply or delay reason to look up, as it appears in the log or postqueue (e.g. 'host gmail-smtp-in.l.google.com[...] said: 421-4.7.28 ...'); when set the queue and log are not read | |
| since | No | log window when scanning the server, e.g. 1h, 24h (default), 7d, or all | |
| domain | No | recipient domain of reply, used to recognise the provider when the reply names no host (e.g. outlook.com) | |
| provider | No | only this provider when scanning the server: gmail, microsoft or yahoo |
| Name | Required | Description |
|---|---|---|
| mode | Yes | server (queue and log were scanned), reply (one reply was looked up) or id (one playbook by id) |
| lookup | No | mode reply: provider, code, whether Postfix retries, category, and the playbook (null if none applies) |
| server | No | mode server: playbooks for what is failing, with evidence counts, codes seen and affected domains, most deliveries affected first |
| playbook | No | mode id: the playbook |
| available | No | every built-in playbook id; included when nothing matched |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with substantive detail: it never contacts providers, never changes the queue, and reply-mode does not read the server. It also discloses the default log window (24h) and what a scan returns (evidence counts, affected domains).
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-loaded with purpose and provider coverage, then modes, then the read-only guarantee. The enumeration of error codes is dense but is the actual substance of the tool rather than filler; a bulleted mode list would read slightly better than the single running paragraph.
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?
Output schema exists, so return value shape needn't be explained; annotations cover safety. What remains—modes, defaults, evidence produced by a scan, and the no-side-effect guarantee—is all present. Nothing an agent needs to invoke 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 coverage is 100% with good per-parameter examples, so the baseline is 3; the description adds interaction semantics the schema cannot express well—that passing 'reply' suppresses the queue/log read, and that 'since' only applies when scanning. Otherwise it mostly mirrors the schema's parameter intent.
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 resource (recovery playbooks for Gmail/Microsoft/Yahoo SMTP failures) with the exact error codes covered, so an agent can immediately tell it apart from postfix_log_stats or postfix_queue_summary. The three operating modes are named up front.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing: no arguments scans queue+log, 'reply' looks up a pasted SMTP reply without reading the server, 'id' returns a single playbook. This effectively states when to use each mode and what the alternative costs, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List queued messages (queue ID, queue, arrival time, size, sender, recipients with delay reasons), filtered by queue, recipient domain, sender, reason text, reason category or minimum age.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | max messages returned (default 50) | |
| queue | No | queue name filter, e.g. deferred | |
| domain | No | recipient domain; a leading dot matches subdomains too | |
| sender | No | substring of the envelope sender | |
| min_age | No | only messages older than this, e.g. 2h or 3d | |
| category | No | reason category id, e.g. rate_limit, auth, ptr, timeout | |
| reason_contains | No | case-insensitive substring of the delay reason |
| Name | Required | Description |
|---|---|---|
| matched | Yes | |
| messages | Yes | |
| returned | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing what each result row contains (delay reasons per recipient) and the filterable dimensions, but says nothing about ordering, the default 50-message cap behavior, or how results are truncated.
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?
One sentence, front-loaded with the verb and resource, then the output shape, then the filters. No filler, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be explained, yet the description still sketches them helpfully. All 7 optional parameters are covered by schema descriptions, so an agent has what it needs; only ordering/pagination semantics are unstated.
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 every one of the 7 parameters is already documented, including the leading-dot subdomain rule and the '2h or 3d' age format. The description's filter enumeration largely restates the schema; baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('List') plus resource ('queued messages') with the returned fields enumerated (queue ID, queue, arrival time, size, sender, recipients with delay reasons) and the full filter set named. An agent can tell this is per-message inspection rather than the aggregate siblings postfix_queue_summary/postfix_queue_shape without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The filter list implies when this tool applies (targeted queue inspection), but there is no explicit when-to-use statement, no exclusion, and no pointer to postfix_queue_summary or postfix_queue_shape for the aggregate view. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One queued message, from its queue file (postcat -e -h; the body is never read): which queue it is in, arrival time and size, every envelope recipient with its state (pending / delivered / canceled) and, for pending ones, the delay reason with category, hint and provider playbook; the Received route oldest first (hosts, IPs, TLS, per-hop delay); DKIM signatures and whether they align with the From: domain; the primary headers; and notes (missing Message-ID/Date, unaligned DKIM, bulk mail without one-click unsubscribe, null sender, on hold). Always redacted: local parts become [user-N] (domains kept), display names, subjects and free-text headers are hidden, credential-like headers removed.
| Name | Required | Description | Default |
|---|---|---|---|
| queue_id | Yes | one Postfix queue ID, e.g. 4F2A1C3B9D (short) or 4bNqJx2rG9z1Hk (long), from postfix_queue_list |
| Name | Required | Description |
|---|---|---|
| age | No | |
| dkim | Yes | |
| hops | Yes | |
| notes | Yes | |
| queue | Yes | |
| sender | Yes | |
| source | Yes | |
| headers | Yes | |
| queue_id | Yes | |
| redacted | Yes | |
| recipients | Yes | |
| age_seconds | No | |
| from_domain | No | |
| arrival_time | No | |
| message_size | Yes | |
| sender_domain | Yes | |
| recipient_domains | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds substantial context beyond them: the data source (postcat -e -h), the fact that the body is never read, and a detailed redaction policy covering local parts, display names, subjects, free-text headers, and credential-like headers. This is exactly the behavioral disclosure an agent needs before handling sensitive mail data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core identity ('One queued message, from its queue file') and every subsequent clause describes a real content category or behavioral constraint. It is dense but not wasteful; the long enumeration is justified by the tool's detail-oriented purpose, though it could be slightly tighter given an output schema exists.
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 complex single-message inspection tool with one required parameter and an output schema, the description is complete: it covers source, content scope, redaction behavior, and notable edge-case notes (missing Message-ID/Date, unaligned DKIM, null sender, on hold). An agent has everything needed to call it correctly and interpret the privacy model.
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 queue_id parameter is already documented with short/long examples and its source (postfix_queue_list). The description adds no additional syntax or format meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as 'one queued message' and enumerates the specific contents (envelope recipients, Received route, DKIM, headers, notes), which strongly distinguishes it from list/summary siblings. It lacks an explicit verb or sibling name in the description itself, but the scope is unmistakable.
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: this is the deep-inspection tool for a single queue ID, and the schema notes the ID comes from postfix_queue_list. However, the description never states when to choose this over postfix_queue_shape, postfix_queue_summary, or postfix_log_trace, nor does it mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
qshape-style matrix of a queue: rows are recipient (or sender) domains, columns are message age buckets in minutes (5,10,20,...,1280+). Shows which destination is backing up and since when.
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | recipient (default) or sender domain | |
| top | No | max domains (default 20) | |
| queue | No | queue to shape (default deferred; 'all' for every queue) |
| Name | Required | Description |
|---|---|---|
| by | Yes | |
| rows | Yes | |
| text | Yes | |
| queue | Yes | |
| total | Yes | |
| buckets | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the output shape (domains as rows, age buckets as columns) and the diagnostic purpose, but says nothing about cost, queue-state requirements, or that deferred queues are the default focus.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler, and the matrix layout is stated before the diagnostic payoff. Every clause carries information; only the omitted sibling routing keeps it from being fully front-loaded for selection.
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 an output schema present, the description needn't explain return values, and the annotations cover the read-only nature. Its coverage of what the tool computes and when it's useful is adequate for a zero-required-parameter read tool, though an indication of how it differs from postfix_queue_summary would complete it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (by, top, queue) are already documented in the schema. The description corroborates the recipient/sender distinction for 'by' and the age-bucket dimension, but adds no syntax or default information beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the specific resource (a queue) and the operation (producing a qshape-style domain×age-bucket matrix), plus the diagnostic intent ('which destination is backing up and since when'). It is distinguishable from postfix_queue_list/summary by its explicit focus on age buckets, but it never names a sibling to route against.
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 by the outcome phrase 'Shows which destination is backing up and since when', which tells the agent the diagnostic question this answers. There is no explicit when-to-use vs. postfix_queue_summary or postfix_queue_list, and no stated prerequisites, so it stays at implied guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarise the Postfix queue (postqueue -j): counts per queue, top recipient and sender domains, delay reasons grouped and classified with hints, oldest message.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | max entries per list (default 10) | |
| queue | No | only this queue: active, deferred, hold, incoming, maildrop or corrupt (default all) |
| Name | Required | Description |
|---|---|---|
| bytes | Yes | |
| reasons | Yes | |
| by_queue | Yes | |
| messages | Yes | |
| oldest_age | No | |
| recipients | Yes | |
| forced_expire | Yes | |
| oldest_queue_id | No | |
| oldest_age_seconds | No | |
| top_sender_domains | Yes | |
| top_recipient_domains | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context that this is derived from postqueue -j and that delay reasons come pre-grouped with hints, but it says nothing about cost, failure when the queue is unavailable, or why idempotentHint is false for a read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence, front-loaded with the verb and resource, followed by the concrete outputs. Every clause carries information; nothing is redundant with the title or restates the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the description covers inputs-implied scope and the data source. The remaining gap is routing: with ten siblings, several queue-related, the definition doesn't state where this fits versus postfix_queue_list or postfix_queue_shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (top, queue) are already fully documented in the schema; baseline 3 applies. The description only incidentally gestures at them ("counts per queue", "top recipient and sender domains") and adds no syntax, enum values, or default behavior beyond what the schema states.
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?
Specific verb+resource ("Summarise the Postfix queue") with the underlying source (postqueue -j) and an enumeration of the aggregates returned: per-queue counts, top sender/recipient domains, grouped delay reasons, oldest message. It does not, however, contrast itself with close siblings like postfix_queue_list or postfix_queue_shape, which an agent will need to disambiguate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is the at-a-glance overview versus the list/shape/trace siblings, but the description never says when to pick it, when not to, or which sibling to use instead. No prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the failure categories postsleuth assigns to delay/bounce reasons, with the hint for each.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| categories | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the data is categorized reason hints rather than raw events, but says nothing about ordering, localization, or whether the set is static versus deployment-dependent.
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?
One sentence, front-loaded with the verb and resource, with the qualifier 'with the hint for each' earning its place by clarifying the payload granularity. Nothing is wasted.
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?
An output schema exists, so return values need not be explained and no input parameters exist either. What remains missing is only a note on how the categories relate to the sibling log/queue tools that surface those categories in the first place.
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 are no argument semantics to document. The baseline for a zero-parameter tool is 4; the description correctly implies no input is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and a specific resource (failure categories postsleuth assigns to delay/bounce reasons, with hints). The resource is clearly distinct from the queue/log/config/DNS siblings. It stops short of explicitly contrasting itself with any sibling, so a 4 rather than a 5.
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 only implied: an agent can infer this is the reference lookup to call when it needs to interpret a delay/bounce category. There is no explicit when-to-use, no when-not-to-use, and no named alternative among the many postfix_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.2postfix_queue_messagev0.2.1postfix_doctor12 fields changedOutput schema / properties / findings / items / properties / playbookAdded value: +{
+ "type": "string"
+}Output schema / properties / findings / items / properties / referencesAdded value: +{
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "title": {
+ "type": "string"
+ },
+ "url": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "title",
+ "url"
+ ],
+ "type": "object"
+ },
+ "type": [
+ "null",
+ "array"
+ ]
+}Output schema / properties / findings / items / properties / stepsAdded value: +{
+ "items": {
+ "type": "string"
+ },
+ "type": [
+ "null",
+ "array"
+ ]
+}Output schema / properties / log / properties / stats / properties / bounce_causes / items / properties / playbookAdded value: +{
+ "type": "string"
+}Output schema / properties / log / properties / stats / properties / bounce_causes / items / properties / providerAdded value: +{
+ "type": "string"
+}Output schema / properties / log / properties / stats / properties / deferral_reasons / items / properties / playbookAdded value: +{
+ "type": "string"
+}Output schema / properties / log / properties / stats / properties / deferral_reasons / items / properties / providerAdded value: +{
+ "type": "string"
+}Output schema / properties / log / properties / stats / properties / smtpd_rejects / items / properties / playbookAdded value: +{
+ "type": "string"
+}Output schema / properties / log / properties / stats / properties / smtpd_rejects / items / properties / providerAdded value: +{
+ "type": "string"
+}Output schema / properties / provider_playbooksAdded value: +{
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "bounces": {
+ "type": "integer"
+ },
+ "code_notes": {
+ "items": {
+ "type": "string"
+ },
+ "type": [
+ "null",
+ "array"
+ ]
+ },
+ "codes_seen": {
+ "items": {
+ "type": "string"
+ },
+ "type": [
+ "null",
+ "array"
+ ]
+ },
+ "deferred_attempts": {
+ "type": "integer"
+ },
+ "domains": {
+ "items": {
+ "type": "string"
+ },
+ "type": [
+ "null",
+ "array"
+ ]
+ },
+ "example": {
+ "type": "string"
+ },
+ "playbook": {
+ "additionalProperties": false,
+ "properties": {
+ "code_notes": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "codes": {
+ "type": "string"
+ },
+ "id": {
+ "type": "string"
+ },
+ "meaning": {
+ "type": "string"
+ },
+ "provider": {
+ "type": "string"
+ },
+ "references": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "title": {
+ "type": "string"
+ },
+ "url": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "title",
+ "url"
+ ],
+ "type": "object"
+ },
+ "type": [
+ "null",
+ "array"
+ ]
+ },
+ "steps": {
+ "items": {
+ "type": "string"
+ },
+ "type": [
+ "null",
+ "array"
+ ]
+ },
+ "title": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "provider",
+ "codes",
+ "title",
+ "meaning",
+ "steps",
+ "references"
+ ],
+ "type": "object"
+ },
+ "queued_recipients": {
+ "type": "integer"
+ },
+ "temporary": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "playbook",
+ "codes_seen",
+ "temporary",
+ "deferred_attempts",
+ "bounces",
+ "queued_recipients",
+ "domains",
+ "example"
+ ],
+ "type": "object"
+ },
+ "type": [
+ "null",
+ "array"
+ ]
+}Output schema / properties / queue / properties / reasons / items / properties / playbookAdded value: +{
+ "type": "string"
+}Output schema / properties / queue / properties / reasons / items / properties / providerAdded value: +{
+ "type": "string"
+}postfix_log_stats6 fields changedOutput schema / properties / stats / properties / bounce_causes / items / properties / playbookAdded value: +{
+ "type": "string"
+}Output schema / properties / stats / properties / bounce_causes / items / properties / providerAdded value: +{
+ "type": "string"
+}Output schema / properties / stats / properties / deferral_reasons / items / properties / playbookAdded value: +{
+ "type": "string"
+}Output schema / properties / stats / properties / deferral_reasons / items / properties / providerAdded value: +{
+ "type": "string"
+}Output schema / properties / stats / properties / smtpd_rejects / items / properties / playbookAdded value: +{
+ "type": "string"
+}Output schema / properties / stats / properties / smtpd_rejects / items / properties / providerAdded value: +{
+ "type": "string"
+}postfix_provider_playbookpostfix_queue_summary2 fields changedOutput schema / properties / reasons / items / properties / playbookAdded value: +{
+ "type": "string"
+}Output schema / properties / reasons / items / properties / providerAdded value: +{
+ "type": "string"
+}v0.1.0mail_dns_checkpostfix_configpostfix_doctorpostfix_log_statspostfix_log_tracepostfix_log_trendpostfix_queue_listpostfix_queue_shapepostfix_queue_summarypostfix_reason_categoriesScored across 12 tools
Queue tools split cleanly by granularity (summary/counts, shape/age matrix, list/filtered rows, message/full detail), and log tools split cleanly by axis (stats/aggregate, trace/single message, trend/time buckets). The only mild overlaps are postfix_doctor, which bundles summary + log stats + DNS into one call, and postfix_queue_summary vs postfix_log_stats, which both report deferral reasons with hints; descriptions make the intended use distinct enough to avoid misselection.
Eleven tools follow a clean postfix_<component>_<action-or-object> snake_case pattern (queue_summary, log_trace, queue_message, config). The single mail_dns_check breaks the postfix_ prefix, a minor inconsistency but still readable and semantically sensible.
12 tools is well within the ideal band for a Postfix diagnostics server, and each tool earns its place by covering a distinct facet (queue, log, DNS, config, provider playbooks, reference data). No filler or redundant variants.
The read-only diagnostic surface is thorough: queue inspection across four granularities, log aggregation/tracing/trending, DNS authentication checks, config review, and provider-specific recovery playbooks. The main gap is actionability — no tools to retry, flush, hold, or remove queued messages — though the server explicitly frames itself as read-only, so this is a minor, workable gap.
Free, read-only email and DNS checks: SPF, DKIM, DMARC, MX, DNS records, blocklists, domain health.
Check a domain's DMARC, SPF and DKIM, build SPF records, explain bounces, read DMARC reports.
Free, no login: verify an email address, check SPF/DKIM/DMARC, explain SMTP errors, build SPF/DMARC.
AI-operated. Free SPF (RFC 7208 count), DMARC, MTA-STS, DMARC rua/ruf readers. Paid audit $29.
