Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PostGrid MCP Server verify this address: 100 Broadway, New York, NY 10013"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for PostGrid Print & Mail and Address Verification APIs. Send letters (standard, certified, certified with return receipt), mail MICR-encoded checks, manage contacts and templates, and verify US/Canadian addresses — all from Claude.
postgrid_create_contact — Create a mailing contact
postgrid_get_contact — Get contact details
postgrid_list_contacts — List contacts with search and pagination
postgrid_update_contact — Update contact fields
postgrid_delete_contact — Delete a contact
postgrid_verify_address — Verify and standardize an address (structured or freeform)
postgrid_verify_addresses_batch — Verify up to 2,000 addresses at once
postgrid_autocomplete_address — Autocomplete a partial address
postgrid_lookup_city_state — Look up city/state from a ZIP code
postgrid_create_letter — Send a letter (first class, standard, certified, or certified with return receipt)
postgrid_get_letter — Get letter status and tracking
postgrid_list_letters — List letters with search and pagination
postgrid_cancel_letter — Cancel a letter before it prints
postgrid_create_bank_account — Register a bank account for check payments
postgrid_get_bank_account — Get bank account details (numbers masked)
postgrid_list_bank_accounts — List bank accounts
postgrid_delete_bank_account — Delete a bank account
postgrid_create_cheque — Send a MICR-encoded check
postgrid_get_cheque — Get check status
postgrid_list_cheques — List checks with pagination
postgrid_cancel_cheque — Cancel a check before it prints
postgrid_create_template — Create an HTML template with Handlebars merge variables
postgrid_get_template — Get template details and HTML content
postgrid_list_templates — List templates
postgrid_update_template — Update template HTML or description
postgrid_delete_template — Delete a template
postgrid_upload_pdf — Upload a PDF to temporary storage (Cloudflare R2) and get a URL for PostGrid
postgrid_get_upload_url — Get a presigned PUT/GET URL pair for direct-to-R2 PDF upload (for Cowork/sandboxed environments)
postgrid_estimate_cost — Estimate mailing cost without an API call
postgrid_account_summary — Show API mode, connectivity, and rate table
Related MCP server: PostcardAI MCP Server
Sign up at postgrid.com and get your API keys from the dashboard:
Print & Mail API key — for contacts, letters, checks, templates
Address Verification API key — for address verification tools
Both test and live keys are supported. Test keys start with test_ and live keys start with live_.
git clone https://github.com/nathanieljones/postgrid-mcp-server.git
cd postgrid-mcp-server
npm installCreate a .env file (or set environment variables):
POSTGRID_PRINT_API_KEY=test_sk_...
POSTGRID_VERIFY_API_KEY=test_sk_...For live keys, you must also set:
POSTGRID_CONFIRM_LIVE_MODE=trueThis prevents accidental sends with real postage.
PDF upload (optional) — To use postgrid_upload_pdf, configure Cloudflare R2:
R2_ACCESS_KEY_ID=your_r2_access_key
R2_SECRET_ACCESS_KEY=your_r2_secret_key
R2_ENDPOINT=https://<account_id>.r2.cloudflarestorage.com
R2_BUCKET=postgrid-pdfsCreate an R2 bucket in your Cloudflare dashboard and add a lifecycle rule to auto-delete objects after 1 day.
Claude Code (~/.claude.json):
{
"mcpServers": {
"postgrid": {
"command": "node",
"args": ["/full/path/to/postgrid-mcp-server/dist/index.js"],
"env": {
"POSTGRID_PRINT_API_KEY": "test_sk_...",
"POSTGRID_VERIFY_API_KEY": "test_sk_...",
"R2_ACCESS_KEY_ID": "your_r2_access_key",
"R2_SECRET_ACCESS_KEY": "your_r2_secret_key",
"R2_ENDPOINT": "https://<account_id>.r2.cloudflarestorage.com",
"R2_BUCKET": "postgrid-pdfs"
}
}
}
}Claude Desktop / Cowork (claude_desktop_config.json):
{
"mcpServers": {
"postgrid": {
"command": "node",
"args": ["/full/path/to/postgrid-mcp-server/dist/index.js"],
"env": {
"POSTGRID_PRINT_API_KEY": "test_sk_...",
"POSTGRID_VERIFY_API_KEY": "test_sk_...",
"R2_ACCESS_KEY_ID": "your_r2_access_key",
"R2_SECRET_ACCESS_KEY": "your_r2_secret_key",
"R2_ENDPOINT": "https://<account_id>.r2.cloudflarestorage.com",
"R2_BUCKET": "postgrid-pdfs"
}
}
}
}Two-step confirmation — postgrid_create_letter and postgrid_create_cheque require two calls. The first returns a cost preview; the second (with confirmed: true) actually sends.
Live mode gate — Live API keys require POSTGRID_CONFIRM_LIVE_MODE=true in the environment. Without it, the server refuses to start with live keys.
Mode indicators — Every response is prefixed with [TEST] or [LIVE] so you always know which mode you're in.
Check safety thresholds — Checks over $10,000 show a warning. Checks over $100,000 are rejected.
Account number masking — Bank account and routing numbers are masked in all responses.
Idempotency — Create operations include unique idempotency keys so network retries don't produce duplicates.
Type | Class | B&W | Color |
Letter (1 page) | First Class | $1.14 | $1.29 |
Letter (1 page) | Standard | $0.76 | $0.91 |
Letter (1 page) | Certified | $5.00 | $5.15 |
Letter (1 page) | Certified + Return Receipt | $7.43 | $7.58 |
Extra page | — | +$0.07 | +$0.13 |
Check | First Class | $2.50 | — |
Use postgrid_estimate_cost to calculate costs before sending.
MIT
Show PostGrid account status: API mode (test/live), connectivity, and the rate table.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'Show' clearly implies a read-only operation, and listing the included fields adds genuine context. It does not explicitly state side effects or connectivity-failure behavior, but for a simple status tool the core behavior is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the tool's purpose and the three key content areas. Every word earns its place, with no fluff or repetition.
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 zero-parameter, low-complexity status tool, the description is complete. It tells the agent exactly what will be shown, and no output schema or parameter details are necessary to enable correct invocation.
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 has zero parameters, so the description has no parameter semantics to clarify. This matches the baseline of 4 for tools with no parameters; no additional parameter information is needed.
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 specific verb ('Show') and a specific resource ('PostGrid account status'), then enumerates exactly what the summary contains: API mode, connectivity, and rate table. This is precise and clearly distinguishes it from the entire sibling set, none of which are account-level status tools.
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 makes the tool's purpose obvious, so an agent can infer that it should be used when account-level status, environment mode, or rate information is needed. However, there is no explicit 'use this when' guidance or discussion of when not to use it, leaving usage to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Autocomplete a partial street address. Returns matching address suggestions.
| Name | Required | Description | Default |
|---|---|---|---|
| countryCode | No | Country code filter (default: 'US') | |
| partialAddress | Yes | Partial street address to autocomplete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It does state the core behavior — 'Returns matching address suggestions' — which signals a read-only lookup. However, it discloses nothing beyond that: no mention of a live external API dependency, no result-size or granularity limits, and no behavior when no matches are found.
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 totaling 11 words, with the primary verb and object front-loaded in the first sentence. Every word earns its place; there is no boilerplate, redundancy, or 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 low-complexity tool (2 parameters, no nested objects, no output schema, no annotations), the description covers the basic call shape and return behavior. But because there is no output schema, the vague 'matching address suggestions' leaves the return format unstated, and no guidance routes the agent among the overlapping address siblings. Adequate but with clear gaps.
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%: both partialAddress and countryCode are already described in the schema, including the default 'US' for countryCode. The description merely echoes the phrase 'partial street address' and adds no parameter-level meaning, so the high-coverage 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?
The description names a specific verb ('Autocomplete') and a specific resource ('partial street address'), and clarifies the output as 'matching address suggestions.' This is unambiguous and implicitly contrasts with the verification and lookup siblings. It stops short of a 5 because it does not explicitly name or differentiate against siblings like postgrid_verify_address or postgrid_lookup_city_state.
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 guidance on when to use this tool versus the closely related siblings postgrid_verify_address, postgrid_verify_addresses_batch, or postgrid_lookup_city_state. No preconditions, no exclusions, and no alternatives are mentioned; the only usage context is the implied scenario of having a partial address, which the tool name already conveys.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a check. Only works when the check status is 'ready' (before it enters printing).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Cheque ID to cancel |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the bare verb by disclosing the status precondition. With no annotations, however, it does not disclose whether cancellation is irreversible or what side effects occur, which would matter for an agent deciding to invoke a destructive operation.
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 the action first and the crucial precondition immediately after. Every word adds information and there is no repetition of schema details.
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 operation, the description plus schema is nearly complete. It lacks an explicit statement of what a successful cancellation returns or what error occurs for a non-ready check, but the core invocation context is covered.
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 schema already documents id as the 'Cheque ID to cancel' at 100% coverage, so the tool description adds no new parameter meaning. This is the baseline 3 for a fully self-describing 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?
States the operation ('Cancel') and the specific resource ('a check/cheque') with a concrete lifecycle qualifier, so it is unambiguous and distinguishable from the sibling postgrid_cancel_letter. No confusion about what entity is affected.
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?
Explicitly defines the only valid precondition: check status must be 'ready' before it enters printing. This tells an agent when to call and implies not to call for checks in later states, though it does not name a fallback or how to check status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a letter. Only works when the letter status is 'ready' (before it enters printing).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Letter ID to cancel |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the behavioral disclosure burden. It does disclose the critical precondition and timing constraint, which is valuable. However, it does not mention whether cancellation is irreversible, what happens if invoked on a non-ready letter, or any side effects beyond the cancellation itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The primary action is front-loaded, and the important status condition is stated immediately after. Every word 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 low-complexity tool with one fully documented parameter, the description provides the essential invocation detail: the ID and the status precondition. It does not describe the return value or error behavior, but those are less critical for selecting and invoking this simple cancel operation.
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 input schema has 100% description coverage: the single required parameter 'id' is described as 'Letter ID to cancel.' The tool description does not add meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Cancel a letter.' It also includes a meaningful precondition about status, which makes the tool's purpose unmistakable. Among the sibling tools, none handles letter cancellation, so it is naturally differentiated.
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 explicitly says when the tool works: only when the letter status is 'ready' and before printing begins. This gives an agent a clear eligibility condition, though it does not name alternative tools or explicitly state what to do when the status is not ready.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a bank account for check printing. WARNING: Bank account details (account/routing numbers) will transit through chat history. For security, consider creating bank accounts via the PostGrid dashboard instead.
| Name | Required | Description | Default |
|---|---|---|---|
| bankName | Yes | Name of the bank | |
| description | No | Internal description | |
| accountNumber | Yes | Bank account number | |
| routingNumber | Yes | Bank routing number (9 digits for US) | |
| signatureText | No | Signature as text (printed on checks) | |
| signatureImage | No | URL to signature image | |
| bankCountryCode | No | Bank country code (default: 'US') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It discloses an important security-related behavior: sensitive bank details will transit through chat history. However, it does not mention the created resource's persistence, the response shape, authentication requirements, or whether creation is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no waste. The core action is front-loaded, and the security warning is high-value operational guidance that 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?
Given seven parameters, no output schema, no annotations, and a privacy-sensitive mutation, the description is only minimally complete. It states the purpose and risk but omits what the response contains, how to retrieve the created bank account, and any prerequisites or timing expectations.
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 input schema provides 100% parameter coverage, including clear descriptions for all seven fields such as the 9-digit routing number and default country code. The description adds no parameter-specific detail, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Create a bank account'), identifies the resource, and adds the contextual purpose ('for check printing'). It is clearly distinguishable from sibling bank-account tools such as get, list, and delete bank accounts.
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 tool is for creating bank accounts to support check printing and explicitly points to a more secure alternative, the PostGrid dashboard. It does not enumerate when to avoid the tool or contrast it with bank-account siblings, but the routing guidance is practically useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Print and mail a MICR-encoded check via PostGrid. Amount is specified in dollars and converted to cents internally. Call without confirmed=true to preview; call with confirmed=true to send.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Recipient: contact ID or inline object as JSON string | |
| from | Yes | Sender: contact ID or inline object as JSON string | |
| memo | No | Check memo line (max 40 characters) | |
| amount | Yes | Check amount in dollars (e.g., 1500.00). Converted to cents internally. | |
| number | No | Check number (auto-increments if omitted) | |
| sendDate | No | Scheduled send date in YYYY-MM-DD format | |
| confirmed | No | Set to true to confirm and send. Without this, only a preview is returned. | |
| letterHTML | No | HTML content for an accompanying letter | |
| bankAccount | Yes | Bank account ID (e.g., 'bank_account_xxx') | |
| description | No | Internal description | |
| mailingClass | No | Mailing class: 'first_class' (default), 'standard_class' | |
| letterTemplate | No | Template ID for an accompanying letter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool prints and mails a physical check, that amount is converted from dollars to cents internally, and that confirmed=false yields a preview while confirmed=true sends. This sufficiently exposes the key side effects and the non-committal preview mode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero wasted words. It leads with the core purpose, then immediately provides the two most important behavioral instructions: the preview mode and the confirmed sending mode. Every sentence 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?
The description covers the essential behavioral distinction (preview vs. send) and amount handling, which is the most critical context for correct invocation. While there is no output schema and the description does not describe return values, the 100% schema coverage of all 12 parameters and the clear side-effect framing make it sufficiently complete for selection and correct calling.
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 all 12 parameters. The description adds no new parameter-level detail beyond what the schema states; it restates the amount conversion and confirmed behavior that are already present in the schema. This merits the baseline score of 3.
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 specific verb and resource: 'Print and mail a MICR-encoded check via PostGrid.' This clearly distinguishes the tool from siblings like postgrid_create_letter and postgrid_create_bank_account, and the mention of MICR encoding is a unique, concrete 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?
The description provides clear context for how to use the tool: call without confirmed=true to preview and with confirmed=true to send. It does not explicitly name alternatives or exclusions, but the preview-versus-send guidance is directly actionable and covers the main behavioral choice an agent must make.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a contact in PostGrid with a mailing address. Contacts can be used as recipients or senders for letters and checks.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City | |
| No | Email address | ||
| lastName | No | Contact last name | |
| firstName | No | Contact first name | |
| companyName | No | Company or organization name | |
| countryCode | No | Two-letter country code (default: 'US') | |
| description | No | Internal description/notes | |
| phoneNumber | No | Phone number | |
| postalOrZip | No | ZIP or postal code | |
| addressLine1 | Yes | Street address line 1 | |
| addressLine2 | No | Street address line 2 (apt, suite, etc.) | |
| provinceOrState | No | State or province code (e.g., 'TN', 'CA') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that a contact is created; it does not mention what the response contains, whether address verification occurs, whether duplicates are allowed, or any side effects. The schema confirms addressLine1 is required, but the description adds minimal behavioral context beyond the verb itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The core action is front-loaded, and the second sentence adds genuinely useful context about how contacts are used. Every word 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 flat 12-parameter create tool with no output schema and no annotations, the description is somewhat thin. It does not state what happens after creation (e.g., whether the returned contact ID should be used as recipientId/senderId elsewhere), nor does it clarify any validation behavior. It is sufficient for basic selection but not fully complete for reliable invocation and follow-up.
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 12 parameters are already documented in the input schema. The description adds only a general notion that the contact needs a mailing address, which matches addressLine1/addressLine2/city/provinceOrState/postalOrZip/countryCode. With full schema coverage, this is an adequate but baseline contribution.
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 action ('Create'), a specific resource ('a contact in PostGrid'), and the key requirement ('with a mailing address'). It also clarifies the downstream purpose of contacts ('recipients or senders for letters and checks'), which distinguishes it from letter/cheque creation tools.
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 when to use the tool: when you need a contact to act as a recipient or sender for letters or checks. However, it does not explicitly state when to prefer this over update_contact, list_contacts, or other contact-related siblings, nor does it mention prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a physical letter via PostGrid. Supports standard First Class, Certified Mail, and Certified Mail with Return Receipt. Call without confirmed=true to preview the send details; call with confirmed=true to actually send.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Recipient: contact ID (e.g., 'contact_xxx') or inline object as JSON string | |
| from | Yes | Sender: contact ID or inline object as JSON string | |
| html | No | Letter content as HTML (use this OR template OR uploadedPDF) | |
| color | No | Print in color (default: false) | |
| sendDate | No | Scheduled send date in YYYY-MM-DD format | |
| template | No | Template ID to use for letter content | |
| confirmed | No | Set to true to confirm and send. Without this, only a preview is returned. | |
| description | No | Internal description | |
| doubleSided | No | Print double-sided (default: false) | |
| uploadedPDF | No | URL of a PDF to use as letter content | |
| envelopeType | No | Envelope type (e.g., 'standard_window', 'standard_double_window') | |
| mailingClass | No | Mailing class: 'first_class' (default), 'standard_class', 'certified', 'certified_return_receipt' | |
| mergeVariables | No | Template merge variables as key-value pairs | |
| addressPlacement | No | Where to print the address: 'top_first_page' (overlays address on page 1) or 'insert_blank_page' (adds a separate address page, preserving your content). Automatically defaults to 'insert_blank_page' when uploadedPDF is provided, since PDFs are pre-formatted and the overlay would cover existing content. Defaults to 'top_first_page' for HTML/template content. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It usefully explains the two-phase preview/confirmed workflow, but it does not disclose that sending is a real-world, likely costly and irreversible action, nor does it describe what the preview returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words. It front-loads the core action, then explains the critical preview/confirmed workflow, making every sentence earned.
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?
The input schema is detailed, but there is no output schema and no annotations. The description covers the essential confirmation workflow but omits response shape, physical-mail side effects, and guidance on choosing among html, template, and uploadedPDF, leaving meaningful gaps for an autonomous agent.
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 baseline is 3. The description restates the confirmed behavior and mailing classes already described in the schema without adding new parameter-level meaning or clarifying contact IDs vs inline objects further.
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 uses a specific verb and resource: 'Send a physical letter via PostGrid.' It is clearly distinct from sibling tools like postgrid_cancel_letter, postgrid_get_letter, and postgrid_create_cheque, and it names supported mailing classes, leaving no ambiguity about what the tool does.
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 provides clear operational guidance: call without confirmed=true to preview, and with confirmed=true to actually send. It does not explicitly contrast this tool with alternatives or state when to choose it over related letter tools, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an HTML template with Handlebars merge variables (e.g., {{name}}, {{address}}). Templates can be reused across multiple letters.
| Name | Required | Description | Default |
|---|---|---|---|
| html | Yes | HTML content with optional {{mergeVariable}} placeholders | |
| description | No | Template description/name for easy identification |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the disclosure burden. It reveals that the template is persistent/reusable and that Handlebars variables are substituted, but it does not describe validation, return values, side effects, or failure behavior. 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 sentences, front-loaded with the action and resource, with no filler. The sentence about reuse earns its place by adding useful context.
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 two-parameter create operation with full schema coverage, the description is sufficiently complete to drive a correct invocation. It does not explain response/return data, but no output schema exists and that is less critical here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds concrete Handlebars variable examples, but the schema already documents the placeholder behavior; no additional parameter constraints or format rules are provided.
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 an HTML template', and adds Handlebars and letter-reuse context. This clearly distinguishes it from sibling tools like postgrid_create_letter, postgrid_update_template, and postgrid_get_template.
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 by noting templates can be reused across multiple letters, implying use when a reusable template is needed rather than a one-off letter. It does not explicitly mention alternatives such as update_template for editing existing templates, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a bank account. This cannot be undone. Checks already created using this account are not affected.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Bank account ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and handles it well by explicitly warning that the deletion 'cannot be undone' and clarifying that existing checks are unaffected. This gives an agent the key risk and side-effect information needed before invoking a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The core action is front-loaded, and the important irreversible and non-cascading consequences earn their 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 one-parameter destructive tool without an output schema, the description covers purpose, irreversibility, and the main side-effect on checks. It could add expected response or permission requirements, but nothing essential is missing for correct invocation.
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%: the single 'id' parameter is already documented as 'Bank account ID to delete.' The description adds no further parameter-level detail, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Delete a bank account.' This clearly distinguishes it from sibling deletion tools like postgrid_delete_contact and postgrid_delete_template by naming the exact resource type.
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 intended use is implied by the name and first sentence, but the description does not explicitly state when to prefer this over alternatives or provide exclusions. There are no alternative bank-account deletion tools among siblings, so the lack of contrast is less damaging, but no explicit guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a PostGrid contact. This action cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Contact ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It explicitly warns that the action cannot be undone, which is the most important behavioral trait for a destructive operation. It does not cover permissions or response behavior, but for a single-parameter delete this is adequate.
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 action is stated immediately, and the critical irreversibility warning is included 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?
The tool is simple: one required ID parameter, no output schema, and no nested objects. The description plus schema covers everything needed to select and invoke the tool correctly, including the destructive consequence.
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 schema already documents the 'id' parameter as 'Contact ID to delete'. The description adds no additional parameter meaning, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Delete') and resource ('a PostGrid contact'), and is clearly distinct from sibling tools like postgrid_update_contact or postgrid_get_contact. The irreversibility note further reinforces intent.
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?
Implies clear usage: use this when you need to remove a contact by its ID. It does not explicitly name alternatives or exclusions, but no competing contact-deletion sibling exists, so the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a template. This cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Template ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does add an important behavioral trait by stating 'This cannot be undone,' which signals that the operation is destructive and irreversible. However, it does not mention permissions, side effects, or what happens to resources that may reference the template.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The core purpose is front-loaded ('Delete a template'), and the irreversibility warning earns its place as essential risk 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?
For a simple one-parameter delete operation with no output schema, the description plus schema cover the essential invocation details: what action to perform and which ID to use. The irreversibility warning adds key context. It could be more complete with permission or side-effect information, but the low complexity makes this mostly sufficient.
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 input schema already provides 100% coverage with a clear description of the 'id' parameter as 'Template ID to delete'. The tool description adds no additional semantic detail beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and a specific resource ('template'), which clearly distinguishes this tool from sibling operations like update_template, get_template, create_template, and delete_contact. The action and target 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?
No explicit guidance is provided about when to use this tool versus alternatives such as update_template or get_template. The warning 'This cannot be undone' implies caution, but it does not state any conditions, prerequisites, or exclusions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate the cost of sending a letter or check without making an API call. Uses PostGrid's published rate table.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Type: 'letter' or 'cheque' | |
| color | No | Color printing (default: false, letters only) | |
| quantity | No | Number of items to send (default: 1) | |
| pageCount | No | Number of pages (default: 1, letters only) | |
| mailingClass | No | Mailing class: 'first_class', 'standard_class', 'certified', 'certified_return_receipt' (letters only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral transparency burden. It explicitly discloses that this tool makes no API call and relies on PostGrid's published rate table, signaling an offline, read-only calculation with no side effects. It does not mention the exact return shape, but the most important safety and execution traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the core purpose and adds the key behavioral detail ('without making an API call') before mentioning the rate table.
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 estimation tool, the description covers the main intent and execution model, but there is no output schema and no mention of what the tool actually returns (e.g., currency, amount, breakdown). The parameter constraints are documented in the schema, so the main missing piece is return-value 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?
The input schema already provides 100% parameter coverage with descriptions, defaults, and the enum for type, so the baseline is 3. The description adds no parameter-specific meaning; it even uses 'check' while the schema enum is 'cheque', which is a minor terminology mismatch. The schema itself remains the reliable source for parameter details.
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 uses a specific verb ('estimate') and a clear resource ('cost of sending a letter or check'), and distinguishes this tool from every sibling by specifying it works 'without making an API call'. This makes the tool's unique purpose immediately identifiable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: retrieving a cost estimate before actually sending a letter or check, without incurring an API call. It does not explicitly name sibling tools like postgrid_create_letter or postgrid_create_cheque as the alternatives for actual sending, but the context is clear enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get bank account details by ID. Account and routing numbers are masked for security.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Bank account ID (e.g., 'bank_account_xxx') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully reveals that account and routing numbers are masked for security, a behavioral trait not evident from the schema or tool name. This adds meaningful context beyond a simple 'get' statement.
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, front-loaded sentences with no redundant phrasing. The first sentence states the action and target, and the second adds a valuable security-relevant behavioral detail. Every word 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 one-parameter read operation with no output schema, the description adequately covers the core purpose and the key behavioral quirk (masking). It does not list response fields or error behavior, but those are less critical for a simple get-by-ID tool, and the schema already handles parameter documentation.
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 single id parameter is fully documented in the schema with an example format. The description's 'by ID' merely restates the parameter's purpose without adding new semantic detail such as ID format constraints or related object types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' with a specific resource 'bank account details' and qualifies it with 'by ID', which distinguishes it from sibling tools like list_bank_accounts. It is direct and unambiguous, though it does not explicitly name sibling alternatives.
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?
'By ID' implicitly conveys when to use this tool: when the agent has a specific bank account identifier. However, there is no explicit comparison to alternatives such as list_bank_accounts or guidance on when not to use it, leaving the usage context somewhat 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.
Get a check's details, status, and tracking information by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Cheque ID (e.g., 'cheque_xxx') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It does convey that the operation is a read/retrieval operation and lists what is returned (details, status, tracking), but it does not disclose possible errors, authorization needs, or that it has no side effects beyond what 'Get' implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It directly states the action, target, and return content in an efficient and scannable way.
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 one-parameter retrieval tool, the description conveys what the tool does and what information it returns, which is reasonably complete. It lacks an explicit mention of when to use it versus list_cheques, but the operation's purpose and input are sufficiently clear.
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% — the input schema already documents the id parameter with type and example. The description adds only 'by ID', which is consistent but does not provide meaningful additional semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get'), a resource ('a check/cheque'), and the scope ('details, status, and tracking information by ID'). It is easily distinguished from sibling tools like list_cheques, create_cheque, and cancel_cheque because it explicitly targets a single existing id.
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 'by ID' implies the tool is for retrieving one specific cheque, which gives some usage context. However, it does not explicitly say when to use this tool instead of list_cheques or cancel_cheque, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a PostGrid contact by ID. Returns contact details including name and address.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Contact ID (e.g., 'contact_xxx') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It does state the outcome ('Returns contact details including name and address') and the verb 'Get' implies a read operation. However, it does not explicitly confirm read-only/no-side-effect behavior, error handling, or authentication expectations, leaving the behavioral disclosure minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The operation is stated first, followed by the return-value summary. Every word 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 one-parameter getter with no output schema, the description covers the essential context: it retrieves by ID and returns contact details. The schema covers the parameter format, so nothing critical is missing for invoking the tool correctly. The lack of alternative routing is a minor gap, but not a completeness failure for this simple operation.
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 input schema already fully documents the only parameter, 'id', with an example format. The description adds no extra semantic detail beyond saying the lookup is by ID. With 100% schema coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get a PostGrid contact by ID.' It clearly distinguishes this single-resource retrieval from sibling tools like postgrid_create_contact, postgrid_list_contacts, postgrid_update_contact, and postgrid_delete_contact. It also states what is returned, removing ambiguity about the operation's purpose.
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 tool should be used when a contact ID is already known and the caller wants the contact's details. However, it does not explicitly say when to use this tool instead of alternatives, such as using postgrid_list_contacts when no ID is available or postgrid_create_contact when creating a new contact.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a letter's details, status, and tracking information by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Letter ID (e.g., 'letter_xxx') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. 'Get' conveys a read-only operation and the description names what the response contains (details, status, tracking), but it does not mention error behavior for unknown IDs, whether the letter PDF is included, or any other response traits. It is adequate but thin.
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 12-word sentence with zero filler. The verb is front-loaded, the resource is named immediately, and every clause earns its place by naming distinct information categories (details, status, tracking).
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 adequately covers what an agent needs to know before calling: what it does, how to identify the target, and what kind of data comes back. The only gap is absence of any error/edge-case expectations, which is minor for a simple GET-by-ID operation.
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 the single id parameter with an example format ('letter_xxx'). The description's 'by ID' adds no meaning beyond what the schema 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 states a specific verb ('Get'), a specific resource ('a letter'), and the specific data returned (details, status, tracking information), plus the retrieval method ('by ID'). This clearly distinguishes it from siblings like postgrid_list_letters (bulk listing), postgrid_cancel_letter (mutation), and postgrid_create_letter (creation).
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 'by ID' phrasing and the promise of details/status/tracking imply the use case: when you need a single letter's current state and have its ID. However, the description never explicitly contrasts with postgrid_list_letters (to find IDs first) or states when not to use this tool, so routing guidance 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.
Get a template by ID, including its HTML content.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Template ID (e.g., 'template_xxx') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It uses the verb 'Get,' which conveys a read-only operation, and it discloses that the response will include HTML content. However, it does not address error cases such as a nonexistent ID, or authentication 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?
One concise sentence with no filler; the action and object are front-loaded and the extra clause about HTML content is informative rather than 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 one-parameter read operation, the description covers the input (ID) and a key output detail (HTML content). It would be more complete if it explicitly described the rest of the returned template object, especially because no output schema is provided.
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%: the id property is already described with type and example 'template_xxx'. The tool description only repeats the notion of 'by ID' and adds no further parameter-level meaning.
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 the specific verb 'Get' and the resource 'a template by ID,' and adds that the result includes HTML content. This makes it easy to distinguish from listing, creating, updating, or deleting templates, all of which appear as 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 description only implies usage: call it when you have a template ID and need the template object. It does not explicitly contrast with list_templates for enumeration or update/delete for mutations, so an agent must infer the appropriate context from the sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a presigned URL to upload a PDF directly to cloud storage. Returns a PUT URL (for uploading) and a GET URL (for use as uploadedPDF in postgrid_create_letter). Workflow: (1) call this tool, (2) upload the PDF to the PUT URL via curl, (3) pass the GET URL to postgrid_create_letter. Use this from Cowork or sandboxed environments where file system access is unavailable.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It clearly discloses that the tool returns two URLs, explains their distinct purposes, and outlines the full upload workflow. It does not mention URL expiration or size limits, but for a zero-parameter presigned-URL tool the disclosed behavior is substantive and useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then gives a concise numbered workflow, and closes with the environment recommendation. Every sentence adds distinct value without 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?
Even without an output schema, the description fully explains what the tool returns, how to use those return values, and the typical integration point with postgrid_create_letter. For a zero-parameter tool, this is complete enough for an agent to invoke 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?
The input schema has zero parameters, so the baseline is 4. The description mentions no parameters because there are none to explain, and it adds workflow context that makes calling the tool unambiguous.
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 specific action ('get a presigned URL'), the resource ('upload a PDF directly to cloud storage'), and the exact role of the returned URLs (PUT for upload, GET for postgrid_create_letter). It clearly differentiates this from siblings by describing a cloud-storage-based upload flow rather than a direct file upload.
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 gives an explicit three-step workflow: call this tool, upload to the PUT URL via curl, then pass the GET URL to postgrid_create_letter. It also states the recommended environment ('Cowork or sandboxed environments where file system access is unavailable'), which tells an agent when to choose this over direct-upload alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List bank accounts. Account and routing numbers are masked.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Records to skip (default: 0) | |
| limit | No | Max records (default: 10, max: 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does state that account and routing numbers are masked, which is valuable output-behavior context. However, it does not explicitly confirm read-only semantics, pagination behavior, or any other side effects beyond what the schema implies.
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 brief sentences with no filler. The core purpose is stated first, and the security-relevant masking note is included without adding unnecessary length.
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, no-required-parameter list operation, the description covers the essential purpose and a key output characteristic. With no output schema, it could have explained return structure or pagination defaults in more detail, but the schema already covers pagination parameters, so the description is reasonably complete.
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 skip and limit are already fully documented in the input schema. The description adds no parameter-specific meaning beyond what the schema provides, making the baseline score of 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 uses a specific verb ('List') and resource ('bank accounts'), clearly distinguishing this from sibling tools like get, create, and delete bank account operations. The note about masked account and routing numbers adds useful specificity without ambiguity.
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 is provided about when to use this tool versus alternatives such as postgrid_get_bank_account or the other list tools. The intended use case is implied by the name and verb, but there are no explicit context cues, exclusions, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List checks with optional search and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Records to skip (default: 0) | |
| limit | No | Max records (default: 10, max: 100) | |
| search | No | Search filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates the read-only nature implicitly through 'List' and mentions search and pagination, but it does not clarify what search matches against, how pagination behaves beyond schema defaults, or what the response 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?
The description is a single, front-loaded sentence with no wasted words. It conveys the operation, the resource, and the two key optional capabilities efficiently.
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?
The tool is a simple list operation with optional parameters and no required fields, so the basic description is mostly sufficient for invocation. However, without annotations or an output schema, the description omits specifics about search behavior and response shape, leaving some ambiguity for an agent deciding whether this tool fully satisfies a user request.
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 skip, limit, and search. The description adds only the generic note that search and pagination are optional, which adds minimal value beyond the schema. Baseline 3 is appropriate since 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?
The description clearly states a specific action ('List') and resource ('checks'), and the optional search and pagination details help distinguish it from simple retrieval or other resource lists. However, it uses the American spelling 'checks' instead of the tool name's 'cheques', and it does not explicitly contrast with sibling list tools.
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 is given about when to choose this tool over siblings like postgrid_get_cheque, postgrid_list_letters, or other list tools. The description only implies the obvious use case of listing checks; it provides no exclusions, prerequisites, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or search PostGrid contacts. Supports pagination with skip/limit.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip (default: 0) | |
| limit | No | Maximum records to return (default: 10, max: 100) | |
| search | No | Search by name or company |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It mentions pagination, which is useful, but it does not disclose whether the operation is read-only, what response format is returned, how search behaves, or any constraints beyond the schema defaults. This is a minimal behavioral disclosure for a tool without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The primary action and resource are front-loaded, and the pagination detail is concise and relevant. Every word 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 list/search tool with a fully documented parameter schema, this is mostly adequate. However, there is no output schema and no annotations, so the description would benefit from stating what the response contains and clarifying that this is a safe read-only operation. It is minimally complete but leaves some contextual gaps.
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 input schema has 100% coverage for all three parameters (skip, limit, search), so the schema already documents their meaning. The description adds only the word 'pagination' and names skip/limit without adding deeper semantic context beyond the schema, 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?
The description clearly states the action ('List or search') and the resource ('PostGrid contacts'), and the pagination note sets expectations about scope. It does not explicitly name sibling tools like postgrid_get_contact, but the verb 'list/search' distinguishes it adequately from create/update/delete/get variants.
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 guidance about when to use this tool versus alternatives, such as using postgrid_get_contact for a single contact or other list tools for different resources. The description merely states what the tool does without explaining the appropriate selection context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List letters with optional search and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip (default: 0) | |
| limit | No | Max records to return (default: 10, max: 100) | |
| search | No | Search filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does convey a read-only listing operation with search and pagination, but it omits details such as return shape, ordering, or search-field semantics. 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?
The description is a single, front-loaded sentence with no filler. Every word earns its place, and the core action is immediately clear.
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?
The tool is a simple list operation with optional parameters, and the schema covers parameter semantics. However, there is no output schema and the description does not describe return values or pagination behavior beyond the schema defaults. It is adequate for a basic list call but leaves meaningful gaps.
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 skip, limit, and search already documented in the input schema. The description mentions search and pagination but adds no new parameter meaning beyond what the schema provides, so the baseline score 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?
The description uses a specific verb ('List') and resource ('letters'), and mentions optional search and pagination. It is clear about what the tool does, though it does not explicitly distinguish itself from siblings like postgrid_get_letter or postgrid_list_contacts.
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 provides no guidance on when to use this tool versus alternatives. It only restates the operation and gives no exclusions, prerequisites, or pointers to sibling tools such as postgrid_get_letter for single-letter retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List templates with optional search and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Records to skip (default: 0) | |
| limit | No | Max records (default: 10, max: 100) | |
| search | No | Search filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only restates the operation: 'List templates with optional search and pagination.' It doesn't disclose response contents, ordering, rate limits, or any side effects. The pagination mention is a small behavioral credit, but overall the disclosure is minimal.
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 concise sentence with no wasted words, front-loading the verb and resource. It is efficiently sized, though the brevity edges toward under-specification rather than deliberate completeness. Every word 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?
The tool is simple with 0 required parameters and full schema coverage, but it has no output schema, no annotations, and sits among 29 siblings including several other list tools. The description gives an agent no basis for choosing this tool over postgrid_list_contacts or postgrid_list_letters, and doesn't describe what a response looks like, so it is incomplete in 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% — skip, limit, and search each have descriptions in the schema, so the schema does the heavy lifting. The description adds marginal context by flagging search and pagination as the tool's optional behaviors, but it adds no new meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List templates' with optional search and pagination. It clearly conveys the core operation, but it doesn't explicitly differentiate itself from the many sibling list tools (postgrid_list_contacts, postgrid_list_letters, postgrid_list_cheques), relying on the resource name in the tool title to disambiguate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It doesn't mention when to prefer it over postgrid_get_template for retrieving a single template, or over other postgrid_list_* siblings, and there are no explicit exclusions or conditions. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up city and state from a ZIP/postal code.
| Name | Required | Description | Default |
|---|---|---|---|
| countryCode | No | Country code (default: 'US') | |
| postalOrZip | Yes | ZIP or postal code to look up |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the core behavior: a lookup returning city and state. It does not mention edge cases such as invalid/unsupported postal codes, default country behavior (US is in the schema, not the description), or the exact output shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no filler. Every word contributes to the purpose, and the key object ('city and state') is 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 two-parameter lookup, the description and schema together are mostly sufficient, but there is no output schema and the description does not specify the return format or any country-specific behavior beyond the schema's default. It also lacks routing guidance to distinguish it from address verification 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%, so the schema already explains both postalOrZip and countryCode. The description adds little beyond the schema, except reinforcing that the postal code maps to a city/state result, which is consistent with the baseline.
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 uses a specific verb ('look up') and names the exact resource ('city and state from a ZIP/postal code'), so an agent can tell this is a postal-code lookup. It does not explicitly differentiate it from the address verification siblings, but the operation is distinct enough on its own.
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 is given about when to choose this tool over sibling tools like postgrid_verify_address or postgrid_autocomplete_address. The description states what the tool does but not when it is preferred or when it should be avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing PostGrid contact. Only provided fields will be updated.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Contact ID to update | |
| city | No | Updated city | |
| No | Updated email | ||
| lastName | No | Updated last name | |
| firstName | No | Updated first name | |
| companyName | No | Updated company name | |
| countryCode | No | Updated country code | |
| description | No | Updated description | |
| phoneNumber | No | Updated phone | |
| postalOrZip | No | Updated ZIP/postal code | |
| addressLine1 | No | Updated street address line 1 | |
| addressLine2 | No | Updated address line 2 | |
| provinceOrState | No | Updated state/province |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds useful transparency by stating that only provided fields are updated, signaling merge-like rather than full-replace semantics. It does not disclose response behavior, side effects, or error conditions, so it is not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The main operation is front-loaded, and the critical partial-update behavior is stated immediately. Every word contributes to the agent's understanding.
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?
The description is sufficient for an agent to select and invoke the tool: it names the resource, identifies the update operation, and explains the merge behavior. With 13 parameters fully documented in the schema, the description need not repeat field details. It could mention the response format or failure behavior, but the absence is not critical for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond individual parameter labels by clarifying that omitted fields are preserved, which is essential for correctly understanding optional parameters. This partial-update semantic makes the description valuable for parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Update'), the resource ('existing PostGrid contact'), and the key partial-update behavior ('Only provided fields will be updated'). This distinguishes it from sibling tools like create, delete, list, and get.
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 when to use the tool: when an existing contact needs modification. It also communicates that only supplied fields change, which helps avoid accidentally wiping data. However, it does not explicitly mention alternatives or provide exclusions, leaving the agent to infer the full usage boundary from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing template's HTML content or description.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Template ID to update | |
| html | No | Updated HTML content | |
| description | No | Updated description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only names the action and target fields; it does not disclose whether omitted fields are preserved, whether the update is destructive, what the response looks like, or any authentication requirements. This is a meaningful transparency gap for a mutation 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?
The description is a single sentence with no wasted words. It leads with the action, identifies the resource, and specifies the updatable fields clearly and efficiently.
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 three-parameter update with full schema coverage, the description is minimally adequate. However, with no annotations and no output schema, it leaves gaps around behavioral details such as partial-update semantics and response behavior, which an agent would need for safe invocation.
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 id, html, and description. The description adds no additional meaning beyond restating 'HTML content' and 'description', so it does not exceed the baseline of 3.
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 clear verb ('Update'), a specific resource ('existing template'), and the exact scope of changes ('HTML content or description'). This distinguishes it from sibling tools like postgrid_create_template, postgrid_get_template, and postgrid_delete_template.
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 tool is for modifying an existing template, which provides some usage context. However, it does not explicitly state when to prefer this over creating a template, nor does it mention prerequisites like the template already existing or what fields are required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a PDF to temporary storage and get a URL that PostGrid can access. Use this before postgrid_create_letter when you have a PDF file to mail. Accepts either a local file path or base64-encoded PDF content. The URL expires after 5 minutes and the file is auto-deleted after 24 hours.
| Name | Required | Description | Default |
|---|---|---|---|
| base64 | No | Base64-encoded PDF content. Use this from Cowork or sandboxed environments where file system access is unavailable. | |
| filePath | No | Absolute path to a local PDF file. Use this from Claude Code or other file-system-accessible environments. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden and discloses decision-relevant traits: the URL expires after 5 minutes and the file is auto-deleted after 24 hours. It also notes the two accepted input modes. It stops short of describing failure behavior or the exact return payload, but covers the lifecycle constraints that matter most for downstream 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?
Four sentences, each with a distinct job: purpose, usage timing, input formats, and lifecycle. The most important fact (what it does) is front-loaded, and there is no filler or repetition of schema content.
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 two-parameter tool with no output schema, the description covers what it does, when to use it, how to pass input, and how long the artifact persists. The return value is implied ('get a URL'), though the exact output shape and failure modes are not specified; the essentials for a correct call are present.
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 each parameter already carries environment-specific guidance. The description adds the either/or semantic — 'Accepts either a local file path or base64-encoded PDF content' — which is valuable because both params are marked optional and an agent needs to know one is expected rather than both or neither.
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 action (upload), resource (PDF), destination (temporary storage), and the result (a URL PostGrid can access). This clearly differentiates it from siblings like postgrid_create_letter and postgrid_get_upload_url.
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?
Explicitly says 'Use this before postgrid_create_letter when you have a PDF file to mail,' giving both sequencing and the triggering condition. It does not enumerate when-not-to-use conditions or name alternatives beyond create_letter, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a single US/CA address using PostGrid Address Verification. Returns verified, corrected (with before/after diff), or failed status.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City | |
| line1 | No | Street address line 1 (structured input) | |
| line2 | No | Address line 2 | |
| countryCode | No | Country code (default: 'US') | |
| postalOrZip | No | ZIP/postal code | |
| freeformAddress | No | Full address as a single string (alternative to structured fields) | |
| provinceOrState | No | State/province code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of explaining behavior. It clearly states the tool verifies an address and returns verified, corrected, or failed status, and it adds the useful detail that corrected results include a before/after diff. It does not discuss side effects or external call behavior, but the verification semantics are reasonably well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the action and scope, then efficiently communicates the return statuses and the diff detail.
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 tool with no output schema and no annotations, the description covers the key facts an agent needs: single-address scope, US/CA geography, and the three outcome categories. It could be more detailed about the shape of the corrected-address response, but the provided outcome summary is a solid foundation for selecting and invoking the 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 input schema already provides descriptions for all seven parameters, so the baseline is 3. The description adds no additional parameter-level meaning beyond the schema's existing coverage, such as precedence rules between freeformAddress and structured fields.
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 uses a specific verb ('Verify'), identifies the resource ('single US/CA address'), and names the provider ('PostGrid Address Verification'). It distinguishes this tool from the related batch sibling by explicitly saying 'single', and it also previews the three possible result statuses.
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 gives clear context: this is for verifying one US/CA address, which implicitly separates it from postgrid_verify_addresses_batch and autocomplete-style tools. However, it does not explicitly name alternative tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify multiple addresses at once (up to 2,000). Addresses are chunked into batches of 500. Returns verification status for each address.
| Name | Required | Description | Default |
|---|---|---|---|
| addresses | Yes | Array of addresses to verify (max 2,000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully reveals the 2,000-address cap, the 500-address batching behavior, and that a verification status is returned per address. However, it does not mention partial failure behavior, error semantics, or whether batching is transparent to the caller, which are relevant for a batch operation.
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 with no filler. The core operation is front-loaded, followed by the key constraint and the expected output. Every sentence 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 one-parameter batch tool with no output schema, the description adequately covers input, limits, chunking, and the per-item return value. The main gap is the absence of a more precise response structure or failure semantics, but the description is sufficient for an agent to make a correct first call.
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 the addresses array and its nested fields. The description adds the batching detail, but that is behavioral context rather than additional parameter meaning. Per the baseline rule, the score stays at 3.
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 uses a specific verb and resource ('Verify multiple addresses') and immediately differentiates itself from the singular sibling postgrid_verify_address by emphasizing batch processing. It is clear about the operation's scope without requiring the agent to inspect the 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 phrase 'Verify multiple addresses at once' provides clear context for when to use this batch tool versus a single-address verification tool. It does not explicitly name alternatives or state when not to use it, so it stops short of full exclusion guidance.
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.
v1.0.0postgrid_account_summarypostgrid_autocomplete_addresspostgrid_cancel_chequepostgrid_cancel_letterpostgrid_create_bank_accountpostgrid_create_chequepostgrid_create_contactpostgrid_create_letterpostgrid_create_templatepostgrid_delete_bank_accountpostgrid_delete_contactpostgrid_delete_templatepostgrid_estimate_costpostgrid_get_bank_accountpostgrid_get_chequepostgrid_get_contactpostgrid_get_letterpostgrid_get_templatepostgrid_get_upload_urlpostgrid_list_bank_accountspostgrid_list_chequespostgrid_list_contactspostgrid_list_letterspostgrid_list_templatespostgrid_lookup_city_statepostgrid_update_contactpostgrid_update_templatepostgrid_upload_pdfpostgrid_verify_addresspostgrid_verify_addresses_batchScored across 30 tools
Most tools are cleanly separated by resource and action: letters, cheques, contacts, templates, bank accounts, and address verification. The only mild ambiguity is between the two PDF-upload workflows (postgrid_upload_pdf vs postgrid_get_upload_url) and between the create_letter preview path and postgrid_estimate_cost, though descriptions provide enough context to choose correctly.
All tools share the postgrid_ prefix and almost all follow a verb_noun snake_case pattern, making navigation predictable. Minor deviations include postgrid_account_summary as a noun phrase and the slightly awkward postgrid_verify_addresses_batch, but these do not undermine the overall consistency.
30 tools is at the high end for an MCP server, but the count is justified by the breadth of PostGrid's domain: letters, cheques, contacts, templates, bank accounts, address verification, PDF upload, and cost estimation. Each tool maps to a distinct operation with little redundancy or filler.
The tool surface covers full lifecycle management for letters, cheques, contacts, templates, and bank accounts, plus address verification, batch verification, autocomplete, PDF upload, cost estimation, and account status. There are no obvious dead ends for the physical-mail and check-printing workflows described.
Verify US & international addresses and send physical mail (postcards, letters, checks) via Lob.
Physical mail API for AI agents. Send letters, certified mail. Sandbox + live keys via MCP.
Print & mail PDF/HTML/Markdown/text/DOCX/images to US addresses; pay per call in x402 USDC on Base.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
