postfix_provider_playbook

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.