postbox-tools

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

Annotations only declare readOnlyHint=true, so the description carries the extra burden and does: it discloses the capability boundary that a static file analysis cannot verify SPF, blacklists or reverse DNS. That is a concrete behavioral limitation an agent would otherwise assume works, and it materially affects tool selection.

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 sentences, zero filler: the capability is front-loaded, then the limitation and the alternative. Every clause earns its place.

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 analysis tool with no output schema, the definition covers input, capability, limitations and the alternative route. The remaining gap is that it never hints at what the analysis returns (scores, checks performed), which would help an agent decide whether the result answers its question.

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?

Only one parameter with 100% schema description coverage, so the schema already documents format and expected source. The description's parenthetical ('full headers + body') reinforces the required input shape but adds no syntax beyond the schema; baseline is 3, with a slight bump for echoing the required input expectation in prose.

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 ('run a deliverability/content analysis') on a specific resource ('raw RFC 822 email (.eml source: full headers + body)'), and explicitly names the sibling (create_mailtest) that provides the authoritative alternative. An agent can distinguish this from check_blacklist or check_spoofability 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 'IMPORTANT LIMITS' sentence gives an explicit when-not condition (no live SMTP session, so SPF/blacklist/reverse-DNS can't be verified from a file) and routes the agent to the correct alternative for the authoritative score. This is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context: which blacklists are queried, the count (24 IP lists), the no-DNS-resolution behavior, and that results are per-list listing status.

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

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

Three tightly packed sentences with zero filler; the resource scope and input-mode distinction are front-loaded before the return behavior.

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 single-param, read-only lookup with no output schema, the description covers what is queried, how the target is interpreted, and the shape of the result. 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% and the single param is well documented, so baseline is 3. The description adds meaning beyond the schema by specifying what each target type is checked against and clarifying that no resolution occurs, which affects how the agent should supply the value.

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 (check) and resource (domain/IP against blacklists), and explicitly distinguishes the two input modes with named example lists. An agent can immediately tell this is a blacklist lookup, distinct from siblings like whois_lookup or check_spoofability.

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

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

Gives clear context on how the target is interpreted ('Checks the exact target given: domains are not resolved to IPs'), which is a real usage constraint. However, it offers no explicit when-to-use vs. alternatives guidance relative to sibling tools such as check_spoofability.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real context beyond that: it discloses the data sources inspected (public DNS, SPF/DMARC, alignment) and that it performs 'live lookalike domain' checks, implying outbound lookups, plus it previews the return shape (A-F grade with findings).

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 tightly packed sentences: the grading action and evidence sources come first, the return value second. No filler, no repetition 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?

For a single-parameter read-only check with no output schema, the description supplies the missing return information (A-F grade plus findings) and the evidence sources. It omits only operational details such as lookup latency or rate limits, which is a minor gap.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents 'domain' fully with an example. The description adds no format or syntax detail beyond what the schema provides, making the baseline 3 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?

States a specific verb ('Grade') and a precise resource (a domain's exposure to email spoofing/BEC), and even names the evidence sources it draws on (SPF, DMARC policy strength, alignment, live lookalike domains). It is clearly distinct from analyze_eml or whois_lookup by its method, but it never explicitly contrasts itself with those siblings.

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 context of use is strongly implied by the purpose (assess a domain before trusting it, or audit your own), but there is no explicit when-to-use statement and no alternative tools named or excluded. Adequate but leaves routing to inference.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the interesting behavioral detail: it creates a throwaway address, requires a real human send action, and defers results to another tool. It does not disclose address lifetime/expiry or whether prior setup is needed, which keeps it short of a 5.

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 sentences, front-loaded with the action, with the parenthetical audit checklist earning its length by telling the agent what the score covers. The clause structure is dense but not padded.

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

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

With no parameters and no output schema, the description supplies everything an agent needs: what gets created, that a human must send an email, and which sibling returns the score. Nothing required for correct invocation is missing.

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

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

The tool takes no parameters, so the baseline is 4; the schema is trivially complete. The description adds the useful note that an address is returned for the user to mail, which is the only input-like detail that matters here.

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 (create) plus resource (disposable test address) and scopes it to a concrete deliverability audit, enumerating exactly what is checked. It also names get_mailtest_result, so an agent can separate this setup tool from the scoring tool without opening either 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?

Gives the exact workflow: create here, have the USER send an email to the returned address, then call get_mailtest_result. That routing to a sibling is strong, though it does not say when to prefer this full audit over lighter siblings like check_blacklist or check_spoofability.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the meaningful context that the result reflects sending reputation, but omits rate limits, data source, and whether lookups fail for unresolvable or newly-registered 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?

One front-loaded sentence stating the resource and return fields, with the motivating context in a compact parenthetical. Nothing is wasted, though the sentence could carry a bit more routing value without bloat.

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 single-parameter read-only lookup with annotations covering safety and no output schema, the description adequately conveys what is returned (registration date, age) and why it matters. Only the overlap with whois_lookup and failure modes are 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?

There is a single 'domain' parameter with 100% schema description coverage ('Domain, e.g. example.com'), so the schema fully carries parameter meaning. The description adds no format, TLD, or input-validation guidance beyond it, making the baseline 3 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 ('Get') and resource ('a domain's registration date and age'), so the agent knows exactly what comes back. It doesn't explicitly distinguish itself from the sibling whois_lookup, which likely overlaps in scope, so it falls short of 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?

The parenthetical about young domains having weak sending reputation implies a use case (email deliverability/sender reputation checks), but there is no explicit when-to-use, when-not-to-use, or named alternative such as whois_lookup. Usage is only inferable.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds genuine behavioral context beyond the annotation: the result only exists after the user has sent mail to the disposable address, which implies a pending/empty state an agent must account for. It does not describe propagation delay or error behavior, so not a 5.

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 action and result shape, with the precondition attached at the end. No filler and nothing redundant.

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

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

For a single-parameter read tool with no output schema, the description names what comes back (score and breakdown) and the prerequisite for the call. It stops short of describing the breakdown structure or a not-ready response, which is the only remaining gap.

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 sole parameter id is already documented as 'the test id returned by create_mailtest'. The description only reinforces that provenance, adding no new format or usage detail, so the baseline 3 applies.

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

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

States a specific verb (fetch) and resource (score and breakdown of a mail test) and ties it to the producing sibling create_mailtest, so an agent can distinguish it from check_blacklist, check_spoofability, and the other diagnostic siblings 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?

Gives a clear timing precondition: only call once the user has sent their email to the disposable address. It does not name an alternative tool or state what to do if the test is not yet complete, so it stops short of full when/when-not guidance.

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

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

Goes well past the readOnlyHint annotation: it discloses that fetching is server-side and SSRF-hardened with private ranges blocked, HTTPS-only, and per-hop validation, and it enumerates the per-hop artifacts returned (status, IP, TLS, timing) plus phishing flags. This is unusually rich behavioral context for a read-only tool.

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 the core action in the first clause, followed by output contents and safety notes. The parenthetical lists are dense but every item carries information; only marginal trimming is possible.

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

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

With no output schema, the description compensates by enumerating the returned fields, and it covers the safety profile and the SSRF posture. For a single-parameter read tool, an agent has everything needed to call it correctly.

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

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

There is only one parameter and schema description coverage is 100%, so the schema already documents the url field. The description adds the notion that a URL is resolved server-side but no format or syntax detail 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?

States a precise verb and resource: 'Follow a URL server-side through every HTTP redirect hop to its real final destination'. The scope is unmistakable and cannot be confused with siblings like whois_lookup or analyze_eml, which operate on different inputs.

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 phishing/deliverability framing implies when the tool is useful, but there is no explicit statement of when to use it versus an alternative, nor any prerequisites or exclusions. Usage must be inferred from the described output rather than stated.

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

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

The readOnlyHint annotation already establishes this as a safe read, so the description is not carrying the safety burden. It does add useful scope by naming the returned record fields, but it says nothing about lookup failures, redacted registries, or rate limits, which are common WHOIS behaviors.

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 dense sentence with the resource front-loaded and no filler; every listed field earns its place given there is no output schema. The fragmentary phrasing is terse rather than wasteful.

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 single-parameter, annotation-covered tool with no output schema, enumerating the returned fields is exactly the missing piece an agent needs. The only gap is that it does not note failure modes or how it differs from get_domain_age.

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?

There is a single parameter with 100% schema description coverage ('Domain, e.g. example.com'), so the schema fully documents it. The description adds no format or normalization detail beyond the schema, making the baseline 3 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?

States a specific verb and resource (WHOIS lookup for a domain) and enumerates the fields returned, which lets an agent distinguish it from a bare domain-age check. It does not explicitly contrast itself with the overlapping sibling get_domain_age, so it falls short of the top tier.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_domain_age, which returns a subset of this data. The agent must infer from the field list alone that this is the broader lookup.

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