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 trace bob@example.org # one message, start to finish
postsleuth dns example.com --ip 203.0.113.7Postfix 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. 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 |
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 that multiple subsystems are queried (queue, logs, DNS) and that it returns actionable findings, but says nothing about cost, latency, DNS-check side effects, or what happens when data is missing. Useful but not rich behavioral context.
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 key differentiator ('One-call diagnosis') comes first, followed by a compact enumeration. No filler or redundant restatement 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 an output schema present, the description need not explain return values, and annotations cover safety, so what remains is adequately covered. The one gap is routing among nine granular siblings, which a sentence of when-to-use guidance would close.
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 parameter (ips, since, domain, skip_dns) is already documented in the schema. The description mentions 'the window' and 'DNS authentication checks' only obliquely and provides no syntax, defaults, or interaction guidance beyond that. Baseline 3 is appropriate 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 and resource ('One-call diagnosis of a Postfix server') and then enumerates the exact components it aggregates (queue summary, qshape of deferred queue, log outcomes, DNS auth checks, findings with next steps). Because those components map onto sibling tools, an agent can tell this is the umbrella/diagnostic tool rather than any single-queue or single-log tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'one-call diagnosis' implies this is the broad sweep to use instead of running the granular tools, but the description never states when to prefer it over siblings like postfix_queue_summary or postfix_log_stats, nor any exclusions or prerequisites. 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.
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 what is aggregated and that deferral entries carry a category and hint, but says nothing about cost on large windows, pagination, or how the non-idempotent aggregate behaves between calls.
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 sentence, front-loaded with verb and resource, with no filler or restatement of the name. The long enumerated clause is information-dense rather than padded, though it could be split for scanability.
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-value explanation is not required, yet the description still orients the agent on what categories come back. Nothing essential is missing for a read-only aggregation tool, though behavior on very large windows (cost, truncation) is unaddressed.
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 'top', 'since', and 'domain' (including the leading-dot subdomain rule) are already fully documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the work.
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 (Aggregate) and resource (Postfix mail log) with the scope (time window) and enumerates the exact output dimensions: totals, per-domain outcomes, failing domains, deferral/bounce groupings, DKIM selectors. An agent can distinguish this from siblings like postfix_log_trace, postfix_log_trend, and postfix_queue_summary 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?
The enumerated output categories imply the tool is for a summarized overview of recent log activity, but there is no explicit when-to-use guidance and no mention of which sibling to pick instead (e.g. log_trace for a single message, log_trend for time-series). Usage is inferable but not stated.
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.
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.
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 declare readOnlyHint=true, openWorldHint=false and idempotentHint=false, so the safety profile is covered. The description adds the underlying data source (postqueue -j) and notes delays are 'grouped and classified with hints', but says nothing about required permissions, cost on large queues, or sampling 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 dense sentence, front-loaded with the verb and resource, with the output detail packed into a comma-separated list. No filler or redundant restatement of the title.
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 described, yet the description still usefully previews what the aggregates are. For a low-complexity read-only tool with full schema coverage, the only minor gap is any note on access requirements for reading the queue.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters (top, queue) are fully documented in the schema, including defaults and the queue enum values. The description adds no parameter-level meaning beyond that, so the 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?
Specific verb+resource ('Summarise the Postfix queue') followed by a precise enumeration of outputs: per-queue counts, top recipient/sender domains, grouped delay reasons with hints, and oldest message. That enumeration makes it clearly distinct from siblings like postfix_queue_list and postfix_queue_shape without needing to name them.
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 statement of when to call this versus alternatives such as postfix_queue_list or postfix_queue_shape, and no mention that it works as a first-pass overview. Usage is only loosely inferable from the word 'Summarise', which is thin guidance given ten queue-related siblings.
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.1.0mail_dns_checkpostfix_configpostfix_doctorpostfix_log_statspostfix_log_tracepostfix_log_trendpostfix_queue_listpostfix_queue_shapepostfix_queue_summarypostfix_reason_categoriesScored across 10 tools
Most tools target distinct facets: queue_summary (counts), queue_shape (age matrix), queue_list (individual messages), log_stats (aggregate outcomes), log_trace (single-message), log_trend (per-destination trend), and mail_dns_check. The main overlap is that postfix_doctor is a one-call aggregate that duplicates much of queue_summary/log_stats/DNS, and log_stats vs log_trend share a time-window log surface, but descriptions make the boundaries workable.
Nine tools follow a consistent snake_case postfix_<subject>_<aspect> pattern (queue_list, log_trace, log_stats, reason_categories, etc.). Only mail_dns_check breaks the prefix, though it retains the same snake_case verb_noun style, making it a minor deviation rather than an inconsistency.
Ten tools is a well-scoped count for a Postfix diagnostics server, with each tool covering a distinct grain of analysis (DNS, config, queue, logs, categories, plus a doctor aggregate). No tool feels redundant padding.
The surface covers the key diagnostic lifecycle well: DNS/auth checks, config inspection, queue views at three grains, log aggregation/trace/trend, and failure categorization. The notable gap is that everything is read-only — no remediation actions such as queue flush, requeue, or delete — which an operator would likely want next.
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.
AI-operated. Free SPF (RFC 7208 count), DMARC, MTA-STS, DMARC rua/ruf readers. Paid audit $29.
Check SPF/DKIM/DMARC/BIMI, blacklists, SMTP/IMAP; DNS lookups; generate email DNS records.
