Paperjoy

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses that the default is a free unsent draft, that draft=false sends immediately, which fields become required, that sending costs one credit, and that mcp:submit permission is needed.

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 create action and default draft behavior, then moves efficiently through the workflow and send conditions. It is compact without omitting critical 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 9-parameter mutation tool with no annotations and no output schema, the description is largely complete: it covers creation, draft versus send, required fields, cost, permission, and workflow. A minor gap is that it only names review_url without fully describing the response shape.

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

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

Schema coverage is 78%, so many parameter meanings are already documented. The description adds important cross-field semantics: all fields are optional for a draft, while sending requires all fields except signature, signature_id, and mistake.

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

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

States a specific verb and resource: create a postcard for the authenticated user. It also distinguishes creation from previewing, updating, and submitting via sibling tool names, so an agent can tell what this tool is for without opening other schemas.

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

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

Explicitly describes the default draft workflow and the alternatives: preview with preview-postcard-tool, change with update-draft-tool, review at review_url, or send with submit-postcard-tool. It also states when to set draft=false for immediate sending.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered. The description still earns credit by adding 'Permanently' (no undo) and a concrete failure mode — submitted postcards are rejected — which annotations alone do not convey. Missing auth/permission context keeps it off a 5.

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

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

Two sentences, the destructive action and its scope are front-loaded, and the constraint follows immediately. There is no filler.

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

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

For a one-parameter destructive tool with full schema coverage and a destructiveHint annotation, the description covers action, scope, irreversibility, and the key rejection case. It omits what a successful response returns, though no output schema exists to cover that gap.

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

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

Schema description coverage is 100% and the single `id` parameter includes a format example (pc_abc123). The description adds nothing beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a draft postcard') and narrows the object to drafts only, which separates it from submit-postcard-tool and update-draft-tool. It stops short of naming any sibling explicitly, so the differentiation is inferred from the state restriction rather than stated.

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

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

'Submitted postcards cannot be deleted' gives a clear exclusion condition that an agent can check before calling. It does not name what to do instead when the postcard is already submitted (e.g., no deletion path exists), leaving that inference to the agent.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds value by noting the call is scoped to the authenticated account and that the credit balance is part of the payload, but it says nothing about behavior when unauthenticated or about other fields returned.

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

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

One sentence, front-loaded with the verb and resource, with the key return field appended. Nothing is wasted and nothing important is buried.

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 read with annotations covering the safety profile and no output schema, the description supplies the essential facts: account scope, authentication context, and the headline return value. Only the full set of status fields is left unstated, a minor gap.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly frames it as an implicit-context call on the authenticated account, which is the only semantic an agent needs.

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 ('Get') and a specific resource ('the authenticated Paperjoy account status'), and further specifies the payload ('available credit balance'). No sibling tool in the list touches account-level data, so an agent can route here 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?

Usage is only implied: an agent can infer it should call this when it needs credit balance or account state, but the description never says so explicitly and offers no exclusions or alternatives. Adequate but leaves the trigger condition to inference.

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

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

readOnlyHint=true already declares the safety profile, so the description does not need to argue non-mutation. It adds genuine value with 'for the authenticated user', signaling per-user data scoping, but says nothing about behavior when the ID does not exist or belongs to another user.

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

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

A single front-loaded sentence with no filler. Every clause (verb, resource, identifier, user scope) carries information.

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

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

For a simple single-parameter read with annotations covering safety and full schema documentation, the essentials are present. However, with no output schema, the description does not indicate what is returned (a postcard object and its fields) or how missing/unauthorized IDs are handled, which would help an agent interpret results.

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 single 'id' parameter with an example format (pc_abc123). The description adds only that the ID identifies a postcard, which the schema already conveys, so baseline 3 applies.

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

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

States a specific verb and resource ('Retrieve one postcard by ID') and adds scope ('for the authenticated user'). It implicitly distinguishes itself from list-postcards-tool by returning a single postcard, but never names that sibling or any other, so differentiation is inferred rather than stated.

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

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

The phrase 'by ID' implies it is the right tool when a postcard identifier is already known, versus the listing tool otherwise. There is no explicit when-to-use/when-not or named alternative, so guidance is only implied.

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

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

readOnlyHint=true already establishes the safe read profile, and the description adds genuinely new context: default ordering ('newest first') and that drafts are included by default. It omits pagination behavior despite the limit parameter and says nothing about what the response contains, so the added value is moderate.

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 wasted words, and the collection scope plus ordering are front-loaded. The draft/status guidance follows naturally as supporting 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 read-only list tool without an output schema, the description covers scope and ordering but not the shape of the returned list (fields per postcard) or how limit interacts with paging. An agent can call it, but is missing detail on result volume and contents.

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 75%, with status (enum), last_name, and company_name already documented in the schema. The description reinforces the status filter's purpose but adds no syntax or semantics for limit or the name filters beyond what the schema states. Baseline 3 applies when the schema does most of the work.

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

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

States a specific verb and resource ('List existing postcards') plus scope ('for the authenticated user, newest first, including drafts'). It implicitly contrasts with the singular get-postcard-tool by scoping to a collection, though it never names that sibling explicitly.

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

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

'Filter by status to find drafts that still need to be sent' gives a concrete usage cue for the status filter. However, it never states when to prefer get-postcard-tool (single card) or how this relates to sibling listing tools like list-signatures-tool, leaving the selection boundary implied.

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

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

readOnlyHint=true already establishes the safety profile, and the description adds real context on top: results are filtered to active custom signatures, scoped to the authenticated user, and ordered newest first. It does not mention pagination, result caps, or what happens when the user has no signatures, which is the only remaining gap.

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

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

Two short sentences with zero waste — what it returns is front-loaded, and the downstream usage note follows. Every clause carries information.

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

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

For a zero-parameter read-only list with no output schema, the description covers the essentials: what is listed, the filter, the ordering, and how to use the result. Only pagination behavior and the shape of a signature record are unaddressed, which are minor for a simple lookup.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The mention of signature_id is a downstream field of another tool, not a parameter of this one.

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 gives a specific verb and resource ('List active custom signatures') plus scope ('available to the authenticated user') and ordering ('newest first'). No sibling tool lists signatures, so an agent can immediately tell this apart from the postcard and account 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?

'Use an ID from this list as signature_id when creating a postcard' explicitly chains this tool to create-postcard-tool, which is a genuine when-to-use instruction. It stops short of naming any exclusion or stating when not to call it, which keeps it out of 5 territory.

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

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

Consistent with readOnlyHint=true, and it goes well beyond the annotation by disclosing cost (free), the exact outputs (two PNGs plus a summary), the conditional nature of the envelope render, and what the summary flags: missing fields, overflowing text, oversized address. That is genuine behavioral context an agent cannot get from the annotations.

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

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

A single front-loaded sentence that names the render action first, then the outputs, then the readiness summary. It is dense with clauses but each one carries distinct information; the parenthetical list of failure modes is slightly heavy but not wasted.

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

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

With no output schema, the description takes on the burden of describing return values and does so thoroughly, including the conditional envelope PNG and the contents of the readiness summary. Nothing an agent needs to call and interpret this tool is missing.

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

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

Only one parameter and schema description coverage is 100%, so the schema already explains that 'id' is the postcard ID with an example format. The description adds no additional meaning about the ID, which is acceptable at this coverage level but is the baseline, not a value-add.

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 ('Render') and resource ('a postcard as the customer will receive it') and enumerates the concrete artifacts produced: a card PNG, an envelope PNG, and a readiness summary. An agent knows exactly what this does without opening the schema, and it is clearly distinct from data-fetching siblings like get-postcard-tool.

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

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

Gives clear usage context: 'Free; works for drafts and sent postcards', and notes the envelope render requires the address, recipient, and font to be set. It implies the pre-send check use case but never explicitly names an alternative (e.g., get-postcard-tool) or states when not to use it.

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

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

With no annotations, the description carries the full burden and does well: it discloses credit cost, irreversibility, the validation gate that leaves the draft intact on failure, and the required mcp:submit permission with remediation. The only gap is the success side — it does not say what the call returns or what state the draft becomes after sending.

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 short sentences ordered by importance: what it does, cost/irreversibility, validity precondition, and auth fallback. No filler and nothing buried.

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 mutation with no annotations and no output schema, it covers preconditions, cost, failure behavior, and permissions well. The one thing an agent would still want is what a successful send yields (confirmation or postcard identifier vs. the draft ID).

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

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

Schema coverage is 100% and both parameters are fully documented in the schema, including idempotency semantics, so the baseline of 3 applies. The description adds cost/irreversibility context that motivates idempotency but does not itself explain the idempotency_key parameter.

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

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

States a specific verb + resource + transition ('Send a draft postcard to production'), which cleanly separates it from create-postcard-tool, update-draft-tool and preview-postcard-tool in the sibling list. An agent can identify the terminal send step without opening any schema.

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

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

Gives clear preconditions (draft must be complete: address, recipient, content, font_id) and the fallback path when the agent lacks permission (ask the user to review at review_url). It does not explicitly route to sibling tools such as preview or update when the draft is incomplete, leaving that inference to the agent.

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

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

Annotations only supply idempotentHint, so the description carries most of the burden and does real work: it discloses partial-update semantics, that null explicitly clears a field, that the call is free, and that submitted cards are immutable. It doesn't cover what a validation failure or the response body looks like, and the partial-update rule sits slightly in tension with a blanket idempotentHint, but there is no contradiction.

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 very short sentences, front-loaded with the action, each carrying a distinct fact (mutation scope, partial semantics, cost, immutability). No sentence is 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 mutation tool with no output schema and only an idempotent annotation, this covers the operational essentials: what changes, how to clear, cost, and the state guard. The missing pieces are the return value shape and how validation errors surface, which are minor for a partial-update 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?

Schema coverage is 75% and the schema itself documents most fields, but the key semantic rule — omitted fields are preserved and null clears a field — exists only in the description and is essential to avoid accidental data loss. That is genuine added meaning over the schema, though the 'mistake' parameter is left unexplained in both places.

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 ('Change a draft postcard') and draws a hard boundary against submitted postcards. It stops short of naming siblings like delete-draft-tool or submit-postcard-tool, but an agent can tell this is the draft-mutation path rather than a create/read/delete tool.

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

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

'Submitted postcards cannot be changed' is an explicit when-not condition, and 'Free' tells the agent there is no cost barrier to calling it. There is no routing guidance to delete-draft-tool for removal or submit-postcard-tool to finalize, so the alternatives are implied by siblings rather than stated.

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