Pressmark

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description reinforces it with 'statelessly' and 'without mutating server records.' It adds no detail on precision/rounding or how partial payloads are handled, which are the remaining behavioral unknowns for a calculation tool.

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

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

Two sentences: the capability and its scope first, a compact worked example second. Nothing is redundant with the annotations or title, and the example is directly load-bearing.

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?

An output schema exists so return values need not be described, annotations cover the mutation profile, and the example disambiguates the single nested parameter. What's left unexplained is the semantic convention for tax_rate (rate vs percentage) and rounding — the main source of mis-invocation for a totals calculator.

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 baseline would be 3; the inline example goes beyond the schema by revealing the internal shape of the nested document, including field names inside items (quantity, unit_price) that the schema never documents. It does not show how tax_rate or discount_amount are expressed, so it falls short of 5.

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?

Names a specific verb (compute) plus an enumerated set of outputs (subtotal, tax, discount, grand total, balance due) scoped to a document payload. The phrase 'statelessly ... without mutating server records' separates it from mutating siblings like record_payment and generate_document.

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 stateless/no-mutation framing makes the intended context clear: use it when totals are needed for a preview or validation without persisting anything. It stops short of naming an explicit alternative or exclusion rule (e.g. 'use record_payment when you intend to settle the balance').

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the description's 'stateless ... without mutating server records' largely restates that. It does add that a brand-new synthesized document is returned and that PDF synthesis occurs, but it omits anything on prerequisites, error conditions, or how credit_reason/due_days alter 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?

Two sentences, front-loaded with the core verb and the stateless constraint, followed by a compact example call. The inline JSON example is slightly noisy but earns its place by showing the required payload shape.

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 an output schema present and full schema description coverage, the description does not need to explain return values, and it covers statelessness and the target types adequately. The main gap is the lack of any relation to the five sibling tools, which for a six-parameter tool in a crowded namespace is the missing piece.

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 every parameter is already documented in the schema, including the target_type enum, due_days being invoice-only, and payment_link QR embedding. The description adds only an example call showing document plus target_type; it contributes no semantics beyond the schema, which is the baseline-3 case.

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: it converts an Estimate/Quote JSON into another lifecycle document (invoice, receipt, credit note) statelessly and in memory. The scope is clear enough to distinguish it from mutation-oriented siblings, though the listed targets omit 'estimate' and 'refund' which the target_type enum actually supports, and it never names generate_document or preview_document as the 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?

The phrase 'without mutating server records' implies the selection condition (use this when you want a throwaway synthesized document rather than a persisted one), and a concrete invocation example is given. However, there is no explicit when-to-use / when-not-to-use statement and no named alternative among the five siblings (generate_document, preview_document, calculate_totals, record_payment, get_pricing), so routing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the non-mutating claim largely restates structured data. However, the description adds genuinely new behavioral facts: statelessness and a <25ms latency expectation, which help an agent decide to call it inline rather than batch.

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 the core capability front-loaded and a single compact example; nothing is padded. The example is somewhat redundant given a 100%-documented schema, which keeps it from a 5.

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?

An output schema and rich annotations remove the need to describe return values or safety, and the schema fully documents parameters. But for a 37-parameter, 57-archetype tool, the description says nothing about mode interactions or the preview-then-generate workflow, leaving the agent to infer routing from sibling names alone.

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% across all 37 parameters, so the schema carries the semantic load. The inline example pins down the shape of from/to/doc_type, adding marginal value, but there is no explanation of the interactions between parameters (e.g., payment_link with payment_qr_code, or state_code with notary_required).

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-plus-resource ('synthesize a vector PDF document') and enumerates concrete archetypes (invoice, receipt, contract, NDA, lease), so an agent knows exactly what is produced. It does not distinguish itself from siblings like preview_document or convert_document, which also deal with documents, so it stops short of a 5.

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

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

The phrase 'statelessly ... without mutating server records' implies a generation-only, safe-to-call context, but there is no explicit when-to-use or when-not-to-use guidance. It never tells the agent why to pick this over preview_document (dry run?) or convert_document, which is the most likely routing confusion.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'without mutating server records' largely restates structured data. 'Static' is the one genuinely additive cue, implying the catalog is fixed and not user-specific, but nothing is said about freshness or environment scoping.

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

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

Two short sentences, front-loaded with the resource and scope, followed by a compact call example. Nothing is padded and nothing needs to be re-read.

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 an output schema present, return values need not be described, and the description still names the three payload categories plus the read-only guarantee for a zero-parameter tool. Minor gap: no statement about whether the catalog differs by environment or how often it changes.

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 is 4 and the schema has nothing to explain. The 'get_pricing({})' example usefully confirms that an empty object is the correct call shape rather than omitting arguments.

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 ('Read') and enumerates the concrete payload: subscription tiers, single-pass unlocks, and checkout links. That clearly separates it from the action-oriented siblings (calculate_totals, convert_document, record_payment), though it never names an alternative explicitly.

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

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

Usage is only implied: the example 'get_pricing({})' shows the no-argument invocation, so the agent knows how to call it, but there is no statement of when to prefer this over record_payment or calculate_totals, nor any precondition.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the description doesn't need to re-argue safety. It does add genuinely new behavioral facts: output resolution (144 PPI), output encoding (Base64 data URI), and the stateless no-persistence contract. Rate limits and size limits for large documents are not mentioned, which 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, front-loaded with the operation and output format, with the example placed last where it aids rather than delays comprehension. No filler or restatement of the tool name.

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?

An output schema exists, so return-value structure need not be explained, and the description still usefully names the Base64 PNG form. Annotations cover the safety profile. The remaining gap is workflow context: with 37 overlapping parameters shared across generate_document and convert_document, the description should say when a preview is preferred over a generated file.

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 37 parameters are already documented with per-field descriptions and 8 enums. The description contributes only a single example call exercising doc_type, from, and to; it adds no guidance on interaction between the many optional formatting flags. Baseline 3 applies when the schema carries the load.

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 concrete verb and output artifact: render a 144-PPI PNG preview as a Base64 data URI, statelessly. That is far more specific than the title alone. However, it never names or contrasts itself with generate_document or convert_document, which share the same 37-parameter payload, so an agent cannot tell from the description which of the three to pick.

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 'statelessly ... without mutating server records' implies this is the read-only preview path versus a persisting generate step, and the inline example shows a minimal valid call. But there is no explicit when-to-use/when-not-to-use statement and no mention of the sibling generate_document or convert_document, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful context beyond annotations: the operation is stateless and in-memory, it returns a new synthesized document rather than mutating server records, and it produces PDF output. It does not discuss authentication or limits, but those are less critical here.

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 and front-loads the core behavior. The example is compact, though using an empty document object as the example payload is slightly confusing since document is a required object containing invoice data.

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 that an output schema exists and annotations cover safety traits, the description provides enough context for an agent to understand that this is a stateless, non-mutating synthesis operation. It could be improved with explicit sibling differentiation, but the essential behavioral picture is 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 the schema already documents all parameters including defaults for amount_paid. The description adds only a minimal example call and does not explain parameter interactions or formatting beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: stateless in-memory payment calculation and PDF synthesis returning a Receipt or partial-payment Invoice. It clearly distinguishes itself from mutating tools by emphasizing 'without mutating server records,' though it does not explicitly contrast itself with siblings like calculate_totals or generate_document.

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 usage when a stateless payment receipt or balance calculation is needed, but it never states when to choose this over calculate_totals or generate_document. It provides an example call but no explicit conditions or alternatives.

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