Lob MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description adds real behavioral context beyond that — the operation is only valid pre-send, it fails once the window has passed, and it avoids billing. It does not say whether the postcard object is returned or whether a cancelled postcard can be recreated, 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?

One front-loaded sentence carries the purpose, precondition, failure mode, and billing consequence; the trailing API endpoint line is a compact and useful mapping. 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?

For a single-parameter destructive tool with no output schema, the description covers purpose, precondition, and failure well. It leaves the return payload and any idempotency/retry behavior unstated, which is a minor but real 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?

There is a single parameter and the schema already documents it at 100% coverage, including the psc_ prefix format. The description adds nothing about the id beyond restating that it identifies the postcard, 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 (cancel) and resource (postcard) plus the exact scope constraint (before send_date) and the outcome (never mailed, not billed). No sibling tool performs cancellation, so it is unambiguously distinguishable from the create/get/list family.

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 for when the tool applies (before send_date) and an explicit failure condition (send window passed), which tells the agent when not to attempt it. It names no alternative tool, but none exists among the siblings, so the only gap is the absence of a stated workaround.

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 supply only destructiveHint=true, so the description carries most of the burden and does it well: it discloses the non-sending behavior, the return identifier format, and the underlying endpoint. It does not address whether the record is validated/verified, whether creation is idempotent, or what errors arise, which keeps it from 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?

Three compact sentences, front-loaded with the purpose and the key negative constraint, then the return value, then the API route. Nothing is redundant or 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 output schema, the description correctly compensates by explaining the returned adr_ identifier and its downstream use. It is nearly complete for a 9-parameter creation tool, though it omits validation behavior and failure modes.

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 78%, so the schema already documents name, address_line1, state, country default, etc. The description adds no parameter-level syntax, defaults, or format rules 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?

States a specific verb and resource ('Create a reusable saved address record') and immediately scopes it against the obvious misreading with '(does NOT send any mail)'. Names the concrete artifact it produces (adr_… id) and the API route, so it is cleanly distinguishable from lob_create_letter/postcard.

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 forward-looking usage ('usable as `to`/`from` in mail tools') and an explicit exclusion ('does NOT send any mail'), which routes the agent away from the mail-sending siblings. It stops short of naming alternatives like lob_verify_us_address for agents who only need validation rather than persistence.

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 destructiveHint=true; the description adds the critical economics (charges the account, real mail), the test-key escape hatch, and the cancellation window ('Cancelable only before send_date'). These are exactly the behavioral traits the hint cannot convey.

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 money warning is front-loaded in caps, followed by tightly packed parameter facts and the underlying endpoint. No sentence 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?

For a 9-parameter mutation with nested objects and no output schema, the description covers cost, cancellation, and input shapes well. It omits any mention of what is returned (e.g. the letter id used later with lob_get_letter/lob_cancel_postcard-style flows), a minor gap given no output schema.

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 the schema already documents every parameter. The description largely restates it (adr_/inline address forms, HTML/URL/tmpl_ for file, color required) rather than adding new syntax or defaults, 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 and resource ('SENDS A REAL LETTER', 'POST /v1/letters') and makes the scope unmistakable. It is trivially distinguishable from siblings like lob_create_postcard and lob_create_self_mailer, which are different physical products.

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 actionable guidance: use a test_ key to avoid real mail/charges, and the letter is cancelable only before send_date. It does not explicitly name an alternative (e.g. postcards) or state when a letter is preferred over one, but the context for correct invocation is clear.

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 supply destructiveHint=true; the description goes well beyond by disclosing that this sends physical mail, charges the Lob account, that a test_ key avoids both, and the exact cancellation cutoff (send_date). These are the financial and irreversibility facts an agent most needs.

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 dense sentences with the money warning front-loaded in bold/emoji, followed by the two least-obvious parameter behaviors and the endpoint. 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?

For a 9-parameter nested-object mutation with no output schema, the description covers the highest-risk facts and the trickiest inputs. Secondary params (size, mail_type, merge_variables, description) are left entirely to the schema, which is acceptable given full coverage but leaves no extra operational 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 the schema already documents every parameter including the anyOf address forms. The description restates key semantics (`to`/`from` accept adr_ ids or inline objects; `front`/`back` accept HTML, URL, or tmpl_) in condensed form but adds no syntax details the schema lacks.

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 ('SENDS A REAL POSTCARD', POST /v1/postcards) and immediately flags the real-money consequence. It is clearly distinguishable from sibling creation tools like lob_create_letter and lob_create_address.

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 actionable conditional guidance: use a test_ key to avoid real mail/charges, and the send is cancelable only before send_date. It does not, however, route the agent to alternatives (e.g. lob_create_letter for letters, lob_cancel_postcard for cancellation), so context is clear but not fully comparative.

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 non-mutating nature is covered by structured data. The description adds the raw endpoint path, which is mild extra context, but says nothing about not-found/error behavior or what a returned record contains.

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, front-loaded with the action and scope, with the endpoint as supporting detail. Nothing is redundant or 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?

For a one-parameter read tool with readOnlyHint already declared, this is close to sufficient, but with no output schema the description gives no sense of the returned record's shape or the failure mode for an unknown id.

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 the schema already documents the single parameter, including the adr_ prefix convention. The description's "by id" adds no meaning beyond the schema, so the baseline of 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 and resource ("Retrieve a single saved address record by id") and even cites the underlying endpoint GET /v1/addresses/{id}. The word "single" implicitly separates it from lob_list_addresses, though no sibling is named 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?

Usage is only implied: fetch by id when you already have one. There is no explicit "use this instead of lob_list_addresses when..." guidance, nor any note about what to do when the id is unknown.

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 returned fields (amount, status, check number) and the underlying endpoint, which is useful given there is no output schema. It still omits failure behavior (404 on nonexistent check) and whether the response is eventually consistent or refreshed.

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 short sentences, front-loaded with the action and resource, with the endpoint mapping tacked on usefully for error interpretation. Nothing is wasted, though the API path borders on 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?

For a single-parameter read tool with annotations covering the safety profile, the definition is nearly sufficient: identity, returned content, and the REST mapping are all present. Only error/exception behavior 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?

Only one parameter, and schema description coverage is 100% with the format hint 'chk_…' already in the schema. The description's 'by id' adds nothing beyond the schema, 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 and resource ('Retrieve a single check by id') and scopes it to a single record, which implicitly separates it from lob_list_checks. It does not explicitly name any sibling, but the singular retrieval semantics are unambiguous.

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: the agent must already hold a check id (chk_…) to call it. There is no explicit statement of when to use this versus lob_list_checks or other get_* tools, and no mention of error conditions such as a missing/unknown id.

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 value beyond that by disclosing what the response contains (status, PDF url, tracking), which is real behavioral context for a read 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?

Two tight sentences, front-loaded with purpose and backed by the API path. Every element is relevant, though the endpoint reference is marginally redundant for a well-named tool.

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-resource read with one fully documented parameter and no output schema, the description does the needed work by naming the returned fields. It is nearly complete; only absence of any error/not-found behavior keeps it from a 5.

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 coverage is 100% with the description already spelling out the id format (ltr_…). The description's 'by id' adds nothing beyond the schema, so the baseline of 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 and resource ('Retrieve a single letter by id') and even cites the underlying API call, making the singular lookup distinct from lob_list_letters in spirit. It stops short of explicitly naming the sibling alternatives, so differentiation is implicit rather than stated.

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: the 'by id' phrasing and the GET endpoint signal you call it when you already hold a letter id. There is no explicit when-to-use vs when-to-list guidance and no exclusions or prerequisites surfaced.

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 usefully discloses the returned payload shape (status, PDF url, expected delivery) but says nothing about authentication requirements, 404/not-found behavior, or how pending postcards differ.

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, front-loaded with the operation and its return payload, followed by the underlying endpoint for reference. 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?

No output schema exists, so the description carries the return-value burden, and it does so by listing status, PDF url, and expected delivery. Given a single well-documented parameter and readOnly annotation, it is nearly complete, missing only error/not-found 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% and the schema already documents the sole 'id' parameter with its psc_ prefix. The description restates the same input without adding format, constraint, or lookup semantics 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?

Specific verb+resource ('Retrieve a single postcard by id'), and the word 'single' distinguishes it from lob_list_postcards. It also names the returned fields (status, PDF url, expected delivery), so an agent knows exactly what it gets.

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

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

Usage is implied rather than stated: 'by id' plus 'single' signals this is the fetch-by-identifier path versus lob_list_postcards, but there is no explicit when-to-use/when-not guidance or named alternative.

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, so the bar is lower. The description usefully adds the sort order (newest first), but says nothing about pagination behavior beyond what the schema already encodes, nor about rate limits or auth expectations. Moderately helpful against annotation coverage.

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 short clauses, zero filler, with the resource and ordering front-loaded. The API endpoint reference is compact and unambiguous.

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 simple read-only list tool with a fully documented three-parameter schema and no output schema (so return values need not be explained), the description covers purpose and ordering adequately. Only the absence of usage routing and pagination context keeps it from a 5.

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 the three cursor/limit parameters are fully documented in the schema, so the baseline of 3 applies. The description adds no additional parameter meaning (e.g., how cursors interoperate with the ordering it mentions).

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 ("List saved address records") plus the ordering (newest first), so the agent knows exactly what this returns. It does not explicitly contrast with lob_get_address or lob_create_address, but the plural-list framing distinguishes it implicitly from 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?

There is no when-to-use guidance, no statement of when to prefer this over lob_get_address, and no mention of prerequisites or scope limitations. The use case for listing is only implied by the verb itself.

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 reinforces this by naming it a list operation and adds useful traits: sort order and the exact Lob endpoint. It says nothing about pagination behavior beyond what the cursor params already imply.

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 short sentences, front-loaded with the operation and refined by ordering and endpoint. 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?

For a simple read-only list tool with full schema coverage and annotations covering safety, the description is nearly complete. The absence of an output schema is slightly offset by the endpoint reference, though no return-shape hint is given.

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 cursor/limit parameters are already documented in the schema. The description adds no parameter 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 and resource ('List sent/scheduled checks'), plus the sort order ('newest first') and the underlying endpoint. An agent can distinguish it from lob_get_check (singular) by name, though it never explicitly contrasts itself with sibling list tools like lob_list_letters.

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 mention of when to prefer lob_get_check or any alternative, and no preconditions (e.g. auth, filtering). Usage is only implied by the verb 'List'.

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 the deterministic ordering ('newest first') and the raw endpoint, but says nothing about pagination behavior or rate limits. With annotations carrying the read-only signal, this is adequate but not rich.

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 short sentences with zero filler; the resource and scope come first and the endpoint detail trails it. 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 simple read-only list with no output schema, the description covers what it returns, in what order, and the underlying endpoint, while the schema fully documents the three paging parameters. Missing only paging workflow detail, 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?

Schema description coverage is 100%, so after/limit/before are fully documented in the schema. The description adds no extra parameter meaning (no note that after/before are mutually exclusive or how to seed pagination), 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 ('List') and resource ('letters') with the scope 'sent/scheduled' and the ordering 'newest first', plus the backing endpoint GET /v1/letters. It is clearly distinguishable from lob_get_letter, though it does not name sibling list tools such as lob_list_postcards.

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 scope phrase 'sent/scheduled letters' implies which letters are returned and implicitly excludes drafts, but there is no explicit when-to-use statement, no mention of when to prefer lob_get_letter, and no guidance on paging through results.

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 is a safe read, and the description adds the sort order and the HTTP endpoint. It says nothing about pagination traversal behavior or rate limits, so the added behavioral value beyond annotations is modest.

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 short sentences with zero filler; the scope and ordering are front-loaded and the endpoint reference is compact.

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?

Adequate for a simple list endpoint whose parameters are fully described in the schema and whose safety profile is covered by annotations. However, with no output schema and no mention of pagination semantics or result shape, an agent gets only minimal context.

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 all three parameters (after, before, limit) are fully documented in the schema. The description adds no parameter meaning, so the baseline of 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 (List) and resource (sent/scheduled postcards) and adds ordering ('newest first') plus the underlying Lob endpoint. The resource name alone distinguishes it from lob_list_letters and lob_list_self_mailers, but it offers no further differentiation or scope detail.

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 mention of alternatives such as lob_get_postcard for a single record, and no exclusions or prerequisites. Usage is only implied by the resource name.

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, so the description only needs to add context. It contributes the sort order ('newest first') and the underlying endpoint, but says nothing about pagination semantics or result caps beyond what the schema states.

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 short sentences, front-loaded with the operation and result ordering. Every clause carries information and nothing is 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?

There is no output schema, so the description could describe the returned self-mailer objects or how next_url drives the cursors. As written it is minimally adequate for a simple read-only list tool whose annotations already cover the safety profile.

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 after/before/limit are fully documented in the schema itself. The description adds no parameter meaning, which is the expected baseline 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?

Specific verb ('List') plus resource ('sent/scheduled self-mailers') with an added ordering guarantee ('newest first'). The resource name is enough to separate it from lob_list_letters and lob_list_postcards, though it never explicitly contrasts 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 guidance on when to use this versus the other eleven list/get siblings, no mention of filtering options, and no indication of what to do about paging beyond the raw cursor parameters.

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 safe-read profile is covered. The description adds the endpoint and the nature of the resource but says nothing about pagination behavior, result ordering, or what a next_url/previous_url contract implies beyond what the schema cursors already show.

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, both front-loaded and free of padding; the resource definition comes first and the endpoint follows. Nothing here 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?

For a simple read-only listing tool this is mostly adequate, but with no output schema the description never indicates what the response contains (template objects, pagination envelope), leaving the agent to infer the return 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 description coverage is 100% — all three cursor/limit parameters are documented in the schema itself with defaults and ranges. The description adds no parameter-level detail, so 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?

States a specific verb (list) and resource (saved HTML templates), plus what they are used for (postcard/letter artwork). That distinguishes it from the other lob_list_* siblings by resource, though it doesn't explicitly call out the contrast.

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 — retrieve templates to reference for postcard/letter artwork — but there is no explicit when-to-use, no prerequisites, and no mention of when to prefer another tool over this one.

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?

'Non-mutating' largely restates the readOnlyHint=true annotation, though it is a mild reinforcement. The addition of the underlying endpoint POST /v1/us_autocompletions is genuinely new information and hints that the request is a POST despite being a read. No return-shape or cardinality detail is given, but annotations already carry the safety profile.

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 short clauses, each earning its place: purpose first, then the non-mutation note, then the endpoint. No filler and well front-loaded.

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 simple, single-purpose read tool with full schema coverage and readOnlyHint annotations, the description is nearly sufficient; it does not mention the suggestion-list return shape, but with no output schema that is a minor gap rather than a blocking one.

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 four parameters (including the required address_prefix with its example) are already documented in the schema. The description's mention of 'partial primary line' only mirrors that, adding no new semantics; 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 ('Suggest') and resource ('complete US addresses from a partial primary line'), which is clear and non-tautological. It does not explicitly distinguish itself from the closest siblings, verify_us_address or us_zip_lookup, so an agent must infer the autocomplete-vs-verify distinction.

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?

'useful for address entry' implies the usage context but gives no explicit when-to-use, when-not-to-use, or named alternative (e.g., verify_us_address for validation). The usage guidance is implied 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?

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Non-mutating'. It adds one genuinely useful piece of context: the underlying transport is POST /v1/us_zip_lookups, which stops an agent from misreading a POST as a write operation. Beyond that it says nothing about rate limits, auth, or error behaviour for invalid ZIPs.

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 short sentences with zero padding, and the core behaviour is front-loaded before the non-mutation note and endpoint reference. Every clause carries information.

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 steps in to say what comes back (cities and state), which is the key return-value fact for this tool. It is slightly thin on edge cases, such as invalid ZIPs or ZIPs mapping to multiple cities, but it is adequate for a one-parameter lookup.

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 ('A 5-digit US ZIP code, e.g. 94107'), so the schema already carries the semantics. The description adds nothing about the ZIP format or validation beyond what the schema provides, which is the expected baseline 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?

The description states a specific verb and resource: return the cities and state associated with a US ZIP code. That is unambiguous and instantly readable. It does not, however, distinguish itself from near-neighbours such as lob_us_autocomplete or lob_verify_us_address, which an agent may confuse for this lookup.

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 or when-not-to-use guidance and no mention of the sibling tools (lob_us_autocomplete, lob_verify_us_address) that overlap with this one. The agent must infer the use case from the name alone, which is the bare minimum rather than explicit routing.

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, but the description adds genuinely useful context beyond that: 'Non-mutating (no mail sent)' clarifies this is a pure verification with no side effects, and the underlying endpoint (POST /v1/intl_verifications) is disclosed. It doesn't cover rate limits or response behavior, but the safety profile is well conveyed.

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 short sentences, zero filler, with the scope constraint front-loaded and the API endpoint kept as trailing detail. 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 simple verification tool with no output schema, the description covers scope, the required key parameter, and the safety profile. It could say more about what standardization returns, but nothing needed 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 only 50%, and the description only restates what the schema already documents for country ('2-letter ISO code, required'). It adds no meaning for primary_line, city, state, postal_code, or secondary_line, so it does not compensate for the coverage gap.

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

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

States a specific verb+resource (validate & standardize an address) and immediately scopes it to non-US, which distinguishes it from the sibling lob_verify_us_address without the agent needing to open 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?

The 'non-US' constraint and the required country parameter implicitly route the agent to this tool over lob_verify_us_address, and the note that no mail is sent clarifies the use case. It never names the US sibling explicitly, so the routing is inferred 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?

readOnlyHint=true is already declared, but the description reinforces it in domain terms ('Non-mutating (no mail sent)') and, with no output schema present, usefully discloses what comes back: deliverability, corrected components, and a confidence score. It does not cover failure behavior for undeliverable addresses or rate limits, keeping 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?

Three tight sentences, front-loaded with purpose and followed immediately by the invocation fork and the safety/return note. The API endpoint mention is the only marginally expendable clause, and it costs almost nothing.

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 and six optional parameters, the description carries the key burdens well: it explains the input modes and summarizes the return payload. It stops short of covering what happens on an undeliverable result or authentication requirements, so it is strong but not exhaustive.

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 83%, so the baseline is 3, and the description adds genuine meaning beyond the schema by explaining the either/or relationship between freeform `address` and the structured `primary_line`/`city`/`state`/`zip_code` set. That resolves the ambiguity created by zero required parameters. It does not address `secondary_line`, which the schema documents.

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 pair ('Validate & standardize') and resource ('a US address'), plus the concrete outputs (deliverability, corrected components, confidence score). It is readily distinguishable from lob_verify_intl_address and lob_us_autocomplete by the explicit 'US' scope and validation framing.

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?

It clearly specifies how to invoke the tool with either a freeform `address` or structured fields, which is real invocation guidance. However, it never says when to prefer this over lob_us_autocomplete (type-ahead) or lob_verify_intl_address (non-US input), so sibling routing is left to inference.

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