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

No annotations are supplied, so the description carries the full burden. It usefully explains that these fields become the issuer and are validated by an e-invoicing ruleset, and it clarifies the conceptual boundary with a branding profile, but it says nothing about creation side effects, duplicate-name behaviour, error modes for invalid tax ids, or what the Idempotency-Key parameter does.

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 lead sentence is front-loaded and states the core identity of the tool immediately, followed by two short paragraphs that add scope and a useful disambiguation. Some lines are slightly discursive, but 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 15-parameter creation tool with no annotations and no output schema, the description gives good conceptual framing but leaves large gaps: nothing about what is returned on success, which optional fields are actually required by common rulesets, or how the idempotency key should be supplied. It is adequate for an agent to understand intent, less so to call the tool confidently.

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 only 20% across 15 parameters, so the description has to compensate and does so only partially: it highlights legal_name, tax_id, address and bank details as the fields that matter for issuance and compliance. Many parameters — display_name, logo_file_id, default_locale, default_currency, default_timezone, Idempotency-Key, email, phone, website — get no treatment at all in the description.

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 opens with a specific verb and resource — 'Create an identity to issue documents as: the seller side' — and names the fields that constitute that identity (legal_name, tax_id, address, bank details). It explicitly separates itself from a branding profile, so an agent can tell what kind of entity is being created, though it never names the closer sibling business_profile_list as the alternative for reading existing profiles.

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

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

Usage is implied rather than stated: you create this when you need to issue documents as a seller and the ruleset will check the issuer fields. There is no explicit when-not guidance, no mention of preconditions such as an existing profile, and no pointer to business_profile_list for inspection, so the agent must infer routing from context.

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 behavioral burden, and it only discloses sort order ('newest first'). It never says this is a read-only operation, says nothing about pagination, page size limits, or what the response contains. For a cursor-paginated list tool, that leaves the agent guessing on the traits that matter most.

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

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

Three short sentences with the conceptual definition front-loaded and the disambiguation pointer last. The emphasis asterisks and literary phrasing ('identities you issue documents *as*') cost a little precision, but nothing is padding.

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

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

No output schema and no annotations, so the description would need to cover return shape and mutation safety—it covers neither. Combined with completely undocumented limit/cursor parameters, an agent cannot tell how many results come back or how to retrieve the remaining pages.

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 0%, so the description must explain both parameters, but it mentions neither 'limit' nor 'cursor'. The 'newest first' phrase hints at sort order but not at how to page or what a cursor represents, leaving the cursor parameter entirely undocumented anywhere in the definition.

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 defines the resource precisely—'the identities you issue documents *as*'—and implies enumeration via 'newest first', so an agent can infer a listing of business profiles. It also separates the concept from branding profiles ('how documents *look* rather than who issues them'). The verb itself is never stated outright, which keeps it 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?

It gives an implicit usage rule—one profile per billable entity, so a business with two trading names needs two—and routes a related-but-different need to branding profiles. There is no explicit 'use this when...' statement, no mention of the create/list relationship, and no guidance about paging through results.

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

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

With no annotations at all, the description carries the full burden and discloses almost nothing beyond the verb. It never warns that the dispatched operation may mutate or destroy data, says nothing about permissions, side effects, error behavior, or what the response contains. The only behavioral insight is the implicit dependency on find_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?

A single sentence with no filler, front-loading the action and the source of the operation identifier. Nothing could be removed without losing 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 generic executor with a nested free-form arguments object, no annotations, and no output schema, the description is thin. An agent cannot tell from it whether the call is safe, what errors to expect, or how results are shaped, and would have to infer behavior from the discovered operation itself.

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 both parameters are already documented in the input schema, including the free-form 'arguments' object that must match find_operation's inputSchema. The description's 'by name' adds no meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb (run) and resource (an operation returned by find_operation), which is precise enough for a generic dispatcher. The name alone is ambiguous, and the description resolves it by tying execution to the discovery tool. It only stops short of 5 because it gives no hint about what kinds of operations exist in this domain.

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 'returned by find_operation' embeds a usage precondition: the agent must discover an operation name first. However, it offers no guidance on when to use this versus calling a domain-specific sibling like document_create or recurring_cancel directly, and no exclusions or failure-mode advice.

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 notable work: it declares the call is non-mutating (nothing stored, no PDF produced, no render consumed) and explains the two-tier mandatory-field plus Schematron execution at a pinned ruleset version. It also names output keys (`valid`, `fully_checked`, `rulesets`), which matters since there is no output schema. It stops short of error behavior, latency/cost characteristics, or what an incomplete run looks like.

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

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

Three short paragraphs, each front-loaded and each doing distinct work: what it does and costs, what actually runs, and how to read the result. No sentence is redundant, and the most decision-relevant fact (no render consumed, nothing stored) leads.

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 complex invoice-shaped input with no annotations and no output schema, the description covers the behavioral essentials and substitutes for the missing output schema by explaining how to combine `valid` with `fully_checked`. The remaining hole is input completeness: nothing tells the agent which profile strings are acceptable or that e-invoice checking imposes extra requirements (VAT tax scheme, delivery date, buyer reference) that the schema documents only field by field.

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 only 33% and the description adds almost nothing for the three top-level parameters. `data`, `profile` and `document_type` are never discussed; notably `profile` is a free string with only one example, and the description says rulesets differ but does not say where valid profile values come from. The one indirect hint ('names a field of the request you can go and change') is too vague to guide input construction.

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 scope: check a document against an e-invoicing ruleset, explicitly without rendering. The 'without rendering it / costs no renders' framing separates it from the render and calculate siblings, but it never mentions the two closest siblings by name (document_validate and compliance_xml), so an agent must still guess which check path it wants.

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

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

Gives a clear operating context: run it on every invoice before sending rather than learning about the problem from a rejection. That is genuine when-to-use guidance. What is missing is any exclusion or alternative — nothing says when to prefer document_validate or compliance_xml instead.

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 real work: it discloses the tool is side-effect free ('without storing anything'), performs no ruleset validation, and produces lossy output for invalid documents — the single most surprising behavior. What it omits is the shape of the response (raw XML string, encoding, size limits, or whether a download handle is 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?

Front-loaded with the outcome, then rationale, then the parameter design note. Every paragraph has a purpose. The syntax rationale runs slightly long for a point that could be one sentence, but it pre-empts a likely caller error, so the length is defensible.

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

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

No annotations and no output schema means the description is the only source for behavioral contract, and it does not say what actually comes back from a tool whose entire job is producing an artefact. For a 3-parameter, mutation-free generator the coverage is adequate on intent but incomplete on output.

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 low (33%), so the description must compensate, and it does so for the most confusing parameter: `profile` is explained as a syntax-plus-ruleset bundle, which is why no separate syntax argument exists ('asking a caller for both is asking them to know that Peppol means UBL'). It says nothing about `document_type` or `data`, though the deeply described nested $defs largely cover the body. Net: meaningful but partial compensation.

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 first line states a concrete verb+resource: produce the e-invoicing XML for a document, explicitly without persistence. That distinguishes it from `document_create`/`document_render` and pairs it conceptually with the validation path. It stops short of 5 because the counterpart is named by HTTP path (`/validate-compliance`) rather than by sibling tool name (`compliance_check`), so an agent must infer the mapping.

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

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

It gives an explicit workflow: validate first, then take the XML once it passes, and states that refusals belong to the validation endpoint. It also carves out when NOT to expect value here — this will happily emit XML missing mandatory elements rather than erroring. Alternatives and sequencing are both spelled out.

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?

No annotations are supplied, so the description carries the full burden. It identifies this as a write that persists a customer and discloses that tax_id/electronic_address are optional for plain PDF workflows, which is useful. But it says nothing about duplicate handling, permission requirements, whether the Idempotency-Key field prevents double creation, or what the call returns (there is no output schema).

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

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

Three short sentences with no filler, and the core purpose is front-loaded in the first line. The e-invoicing caveat is scoped tightly to the two fields it concerns.

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 10-parameter creation tool with no annotations and no output schema, the description covers only two fields and omits most of what an agent would need: idempotency semantics, address object usage, and the shape of a successful response. The in-scope content is strong but the coverage is far too narrow for the tool's complexity.

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 20% across 10 parameters, so the description needs to compensate. It adds genuine domain meaning for tax_id and electronic_address (buyer VAT number vs. Peppol routing identifier, and when each is unnecessary), but the remaining parameters — including the non-obvious Idempotency-Key, metadata, billing_address, and shipping_address — get no explanation at all.

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 concrete action and resource: 'Store a customer you can bill repeatedly.' That is clearly distinguishable from the sibling read/update tools (customer_list, customer_get, customer_update). 'Store' is slightly softer than 'create', but the intent is unambiguous.

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

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

Usage is only implied: you call this to persist a customer for repeated billing. There is no guidance on when to use customer_create versus customer_update, no mention of handling existing/duplicate customers, and no stated prerequisites. The e-invoicing note gives conditional context for two fields rather than for invoking the tool.

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?

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about read-only semantics, permissions, error/not-found behavior, or what 'stored' implies (e.g., persisted vs. draft records). The single phrase hints at persistence but is far from 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?

The fragment is short but under-specified rather than concise; there is no front-loaded verb or scope statement, and the four-word phrase cannot earn its place as a complete tool definition.

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 annotations, no output schema, and no parameter documentation, the description is the only source of behavioral information and it supplies none. An agent cannot determine return shape, failure modes, or ID provenance from this definition.

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 0% for the single customer_id parameter, and the description adds no meaning: it never explains that customer_id identifies the customer, what format an ID takes, or where to obtain one. It does not compensate for the schema gap at all.

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?

"One stored customer" is a noun phrase that essentially restates the tool name customer_get rather than stating a verb and resource. It weakly implies fetching a single customer (as opposed to customer_list), but an agent learns nothing about what 'get' actually returns or what identifies the customer.

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

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

There is no when-to-use guidance, no mention of customer_list as the alternative for multiple records, and no prerequisite or not-found behavior. The only usage signal is the tool name itself.

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

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

With no annotations supplied, the description carries the full behavioral burden. It does disclose two real traits — cursor pagination and newest-first ordering — but says nothing about what fields a customer record contains, whether listing exposes sensitive billing data, or whether results can be filtered by email/name.

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 first line is well front-loaded and economical. The second paragraph is about customer optionality in document rendering rather than about listing, so for this specific tool it is largely tangential and displaces content the agent actually needs.

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, read-only list with no output schema and no annotations, the definition covers identity and pagination adequately. It falls short on return contents and filtering, which is the information an agent would need to decide whether this or customer_get answers its question.

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

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

Schema description coverage is 0% for two parameters, so the description must compensate. "Cursor-paginated" explains the pagination model behind limit/cursor, but it never explains how to obtain or reuse a cursor, how limit interacts with paging, or that ordering is fixed at newest-first (so no sort parameter exists).

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 people and companies you bill, newest first" plus "Cursor-paginated" identifies the resource (customers) and the listing behavior, which separates it from customer_get/customer_create/customer_update siblings by implication. It never uses an explicit verb like "list", so the agent must infer the retrieval action, but the inference is easy and correct.

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 no when-to-use or when-not-to-use guidance for this tool versus customer_get or business_profile_list. The second paragraph ("A customer is optional — the stateless render endpoints take a buyer inline — but storing one lets a document reference it by id") is guidance about whether to persist a customer at all, which belongs to customer_create rather than to listing them.

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?

No annotations exist, so the description carries the full burden, and it discloses two genuinely non-obvious behaviours: tri-state field semantics (omit vs. null) and the scoping side effect that already-issued documents are not rewritten. It omits permission/auth requirements, what happens for an unknown customer_id, and any mention of the Idempotency-Key parameter present in the schema.

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

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

Three tight sentences with no filler, and the most consequential rule (omit vs. null) is front-loaded immediately after the purpose statement. 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 an 11-parameter mutation with no annotations and no output schema, the description covers the hardest semantic problem (partial update) and the main side effect, but leaves the agent guessing about the response payload, idempotency behaviour, and error handling on a bad id.

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

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

Schema description coverage is 0%, and the description compensates only generically by explaining that omitted fields are preserved and null clears them — a rule that applies to all nullable params but explains none of them individually. Nothing is said about tax_id vs. electronic_address, metadata merge/replace behaviour, the billing/shipping distinction, or the Idempotency-Key.

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 ("Change a stored customer"), which is unambiguous against customer_create and customer_get. It stops short of naming any sibling explicitly, so an agent must infer the create/read/update split from the names alone.

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

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

Usage is implied rather than stated: the patch semantics ("only the fields you send are changed") tell the agent how to call it, but there is no explicit when-to-use guidance, no alternative named (e.g. customer_create for new records), and no prerequisites or failure conditions.

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 it does disclose one important trait: the operation neither persists nor renders (no side effects). It says nothing about error behavior on invalid tax data, whether a business profile is required, or whether validation rules (e-invoicing) are enforced during calculation — meaningful gaps for a compute tool with a compliance-heavy schema.

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

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

Two sentences, zero waste, and the key constraint (no storage, no rendering) is front-loaded. The return-value summary arrives immediately after, in the order an agent needs it.

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

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

There is no output schema, and the description compensates well by naming the returned breakdown (subtotal, discounts, tax, shipping, total). For a two-parameter tool it is nearly sufficient, but it omits the relationship between `document_type` and the computed figures and says nothing about failure modes.

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

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

Top-level schema description coverage is reported at 0%: neither `data` nor `document_type` is documented at the top level, and the description adds no parameter guidance at all. It never mentions that `document_type` (invoice vs credit_note vs quote) affects how totals are computed, which is the single most important semantic the schema lacks.

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

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

The description states a specific verb and resource ("Compute the totals for a document") and immediately scopes it with "without storing or rendering it," which cleanly separates it from document_render and document_create. It does not explicitly name those siblings, nor does it clarify its relationship to document_validate, which is the nearest ambiguous alternative.

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 context is concrete: "so a checkout page can show a figure before committing to one" tells the agent this is a pre-commit preview path. There are no explicit exclusions or named alternatives (e.g., when to call document_validate or document_render instead), so it falls short of the 5 bar.

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. It usefully discloses two behaviors: the document lands in draft state, and totals are frozen at creation rather than recalculated. However, for a mutation tool it omits permissions/auth needs, idempotency behavior (despite an Idempotency-Key parameter), what happens on duplicate `number`, and how the draft is finalized via document_transition.

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

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

Three short sentences, front-loaded with the action and the resulting state, and every sentence carries distinct information (state, totals semantics, rendering deferral). The only friction is the mismatched backticked 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?

For a 24-parameter, six-required-field creation tool with no annotations and no output schema, the description should at minimum cover required inputs, idempotency, and what is returned (a draft document id). It covers none of these, leaving an agent to reverse-engineer the call from a large schema.

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

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

Twenty-four parameters at 13% schema description coverage, and the description explains none of them — not the six required fields (number, issue_date, currency, business_profile_id, customer_id, line_items), not the Idempotency-Key, not the draft/finalization relationship to document_type. The schema does carry rich prose on a few fields (tax_scheme, delivery_date, buyer_reference), but the description adds zero compensating 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 a clear verb and resource ('Create a document') plus the resulting state ('in `draft`'), which is genuinely differentiating information. It implicitly separates itself from document_calculate (totals are stored, not recalculated) and from the render siblings, though it never distinguishes itself from document_duplicate or document_update by name.

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 one explicit routing rule ('use `create_document_render` once the document is final'), but that tool name does not match any listed sibling — the available tools are document_render and document_render_stored, so an agent following the text literally will look for a non-existent tool. No guidance on when to prefer document_duplicate, document_calculate, or document_transition in the lifecycle.

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 disclosure burden and does real work: it states the signature is verified before the row is looked up, that this prevents using a forged token to probe for valid render ids, and that the token path skips auth work entirely. What it omits is what a failure looks like (404 vs 401/403), whether the response is streamed binary, and any rate limiting — gaps for a tool whose output is a file.

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 action is front-loaded in the first four words, and the remaining prose adds security-relevant behavior rather than filler. The second sentence is long and em-dash-laden, and the parenthetical 'by signature or by API key' slightly duplicates the token schema text, but nothing is wasted outright.

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, no-annotation, no-output-schema tool, the definition covers the auth model well but leaves the required render_id undefined and says nothing about the response shape (PDF bytes, content type, streaming) or error behavior. An agent could call it correctly but would be guessing about the return value and failure modes.

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

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

Schema coverage is 50%: the token parameter is well documented in the schema itself, while render_id has no description anywhere. The description reinforces the token path ('by signature or by API key') and explains the check ordering, but it never says what a render_id is or where it comes from, leaving the undocumented required parameter unexplained.

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 opening sentence gives a specific verb and resource ('Fetch the PDF') and names the two authentication paths, which is more than a restatement of the name. It does not, however, distinguish this tool from close siblings such as document_get_render or document_render_stored, so an agent cannot be certain which of these retrieves a stored render.

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 token description ('Present it and no API key is needed... Omit it and the request authenticates normally') implicitly tells the caller which credential path applies, and 'this is the one endpoint a browser hits directly' hints at the direct-link use case. There is no explicit statement of when to use this versus the sibling render-retrieval tools, and no exclusions or prerequisites beyond the auth choice.

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 it does disclose one genuinely non-obvious behavior: the copy receives the next available number, not the original's, which matters for downstream finalization. It is silent on permissions required, whether the source is untouched, what else is copied (content, attachments), and what state the original remains in.

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, and the key fact (new number assigned) is placed immediately after the action statement. 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 one-parameter mutation tool with no annotations and no output schema, the description covers the action and the notable numbering side effect but omits the return value the agent needs — presumably the new document's identifier. That gap matters because the agent must act on the draft afterward, and nothing in structured data supplies it.

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 0% for the single `document_id` parameter, so the description must compensate — it only implies that you identify the source document to copy, adding no format, type, or reference guidance. The parameter name is largely self-explanatory, which keeps this from being worse than a 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 opens with a specific verb+resource+destination: "Copy a document into a new `draft`." That is far more informative than the name alone and makes it distinguishable from document_create in spirit, though it never names that sibling or states the contrast 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 agent must infer that this is the tool for replicating an existing document rather than creating one from scratch (document_create) or fetching it (document_get). The clause about finalizing without collision hints at the use case but gives no explicit when-to-use vs when-not-to-use guidance.

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

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

With no annotations, the description carries the full behavioral burden and falls short. The clause "with the totals stored when it was created" hints that totals are a creation-time snapshot rather than recalculated, which is genuinely useful, but there is no disclosure of permissions, error behavior, 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?

A single short sentence with no wasted words, but the brevity is under-specification rather than efficiency. The phrasing is somewhat cryptic and does not front-load an actionable verb.

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

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

There is no output schema and no annotations, so the description should explain what a returned document looks like and what "totals" means, but it does neither. For a lookup tool with an undocumented parameter and undocumented return shape, the definition is inadequate.

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 single document_id parameter has 0% schema description coverage, so the description must compensate and does not—it never mentions the parameter, its format, or where an id comes from. The most important semantic (is this an internal or public id?) is left entirely unstated.

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?

"One document" implies fetching a single document by id, which implicitly contrasts with the sibling document_list, but no explicit verb appears and the phrase is close to naming the resource rather than the operation. An agent can infer retrieval, but nothing distinguishes it from document_get_render or document_get_render_stored.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as document_list for multiple documents or document_render for rendered output. The agent must infer context 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.

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

With no annotations, the description carries the full burden and does disclose the state machine: download_url and expires_at are null until status is completed, and a failed render carries a failure reason. It says nothing about auth, error behavior on an unknown render_id, or polling rate limits, but the conditional field semantics are the key behavioral trait an agent needs.

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

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

Three short lines, front-loaded with what the tool returns, followed by the state-dependent caveat and the lifecycle hint. Nothing is padding and the ordering matches how an agent would reason about the call.

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

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

There is no output schema, so the description must sketch the return shape, and it does so by naming status, totals, download_url, expires_at, and failure. The contents of 'totals' and the URL's usage (e.g., expiry-limited direct download) remain unspecified, which is a minor but real gap.

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

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

Schema description coverage is 0% for the single required render_id, and the description never explains it — notably it does not say the ID comes from the document_render call. The parameter name is largely self-explanatory, so this is a modest gap rather than a blocker.

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 resource ('one render') and enumerates what it returns: status, totals, and download information. This implicitly separates it from siblings like document_download_render (which fetches bytes) and document_render (which creates), though it never names them 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?

'Poll this after an asynchronous render' gives a clear triggering condition and lifecycle position. It stops short of naming the alternatives (document_download_render, document_render_stored) or saying 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?

No annotations exist, so the description carries the full burden. It correctly conveys the read-only listing behavior, the newest-first ordering, and the pagination protocol, which are genuinely useful. It does not disclose whether archived/deleted documents are included, what a returned item contains, permission requirements, or rate limits.

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

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

Three short lines, front-loaded with the core purpose and then the two operational facts an agent needs (ordering and pagination). Nothing is redundant; every sentence adds 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 paginated list with no output schema and no annotations, the description covers purpose, ordering and cursor mechanics, which is most of what matters. It leaves gaps around the shape of returned items, whether the response exposes total counts, and the undocumented limit parameter, which an agent would need to page efficiently.

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 0%, so the description must compensate, and it partially does: it explains that status and document_type act as narrowing filters and that the cursor value comes from a prior response's next_cursor field. It omits the limit parameter entirely (default 50, max 100) and never lists valid values for status or document_type, so two of four parameters remain semantically thin.

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?

"Every document on the account, newest first" states the resource, the scope (account-wide) and the ordering, so an agent knows this is a bulk list rather than a single fetch. It never explicitly contrasts itself with siblings like document_get or find_operation, but the plural/whole-account framing makes the distinction reasonably clear.

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

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

It gives concrete follow-on guidance for pagination (pass the next_cursor from a response) and suggests filtering by document_type or status to narrow results. However, it never says when to choose this over find_operation or how to retrieve a single document (document_get), and gives no guidance on expected result volume or when to prefer a search tool.

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 substantially well: it discloses statelessness (nothing stored but the PDF), the default JSON return with a signed `download_url`, the binary alternative, that the call is asynchronous but blocks until the finished render is returned, and a throughput constraint (single worker, avoid parallel bursts). It omits auth requirements and the meaning of `Idempotency-Key`, so it is not exhaustive.

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 lead sentence states the core distinction and everything after it is scoped to a concrete decision: which path, what you get back, how to get bytes, and how to pace calls. Sentences are short and front-loaded with no filler, though the final operational paragraph is somewhat tangential to selecting the tool.

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

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

For a complex invoicing render tool with a deep nested schema and no output schema, the description covers the essentials an agent cannot infer: the call is stateless, the return value is a JSON payload with a signed URL (or raw PDF), and the render completes before returning. Given the large nested input tree, more guidance on the required `data`/`template` pair would have closed the remaining gap.

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

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

Schema description coverage is only 17%, so the description has to compensate. It adds real meaning for `output.delivery` (url vs binary bytes) and implicitly for the inline `data` body, but `template`, `document_type`, `Idempotency-Key` and the sync/async `output.mode` interaction with `pollUntilTerminal` go largely unexplained in the description text.

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 ("Render a document supplied inline, storing nothing but the PDF") and distinguishes the stateless path from the stored-document path. It loses a point because it routes to a sibling named `create_document_render`, which does not exist under that name in the sibling list (the closest is `document_render_stored`), which could send an agent looking for the wrong 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?

It gives an explicit alternative and the condition that selects it: render inline here, or use the other tool when the document already lives in the system. It also adds operational guidance (prefer one call at a time because rendering is CPU-bound on a single worker) and explains how to ask for bytes instead of a URL. It stops short of 5 because the referenced alternative name does not match the actual sibling tool.

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 must carry the behavioral load, and it does add useful return-value context: a signed `download_url` requiring no API key and a validity window ending at `expires_at`. However, it says nothing about whether a render is persisted as a retrievable resource (the siblings `document_get_render` and `document_download_render` imply it is), nor about idempotency semantics, cost, or rate limits for a tool that has an `Idempotency-Key` parameter.

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

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

Three short sentences, front-loaded with the action, then the routing decision, then the return contract. No filler and no restatement of the 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?

There is no output schema, and the description covers the key return fields (`download_url`, `expires_at`), which is good. But for a 7-parameter rendering tool it omits whether a render becomes a durable object addressable by the render-inspection siblings, and it leaves the majority of parameters unexplained, so an agent still has gaps before calling it confidently.

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 only 43% across 7 parameters, and the description adds no parameter guidance beyond echoing the `expires_at` concept. `document_id`, `template_id`, `page_size`, and `Idempotency-Key` are undocumented in both schema and prose, and the expiry floor/ceiling behavior is not restated in the description.

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?

"Render a stored document to a PDF" gives a specific verb (render), resource (stored document), and output format. The second sentence reinforces the scope word "stored," which is exactly what separates it from the sibling `render_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?

It states the selecting condition ("Use this when the document lives here") and names the alternative with its own condition ("To render one you hold yourself, without storing it, use `render_document`"). Both branches of the decision are explicit, leaving nothing 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?

With no annotations, the description carries the full burden and does most of it: it discloses the 409 on drafts, the exact 'No render exists for this document' refusal, the 202 response with the delivery in `queued`, and that mail is sent asynchronously with retries, plus the polling endpoint for outcome. It omits permission/scope requirements and any duplicate-send or idempotency behavior, which are the remaining gaps 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?

Front-loaded with the action, then preconditions, then the response contract, in three tight paragraphs. A few phrases are more verbose than needed ('and on that path a render must already exist', the repeated restatement of the no-render case), but nothing is off-topic.

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

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

There is no output schema, and the description supplies the return contract (202, `queued`, background delivery, poll `GET /deliveries/{id}`), which is exactly what an agent needs. For a 7-parameter, no-annotation mutation tool it is close to complete, with only auth/permission expectations and recipient-field semantics left implicit.

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 0% across 7 parameters, so the description must compensate. It does so well for the non-obvious one — attach_pdf's default of true and the render-existence consequence of each value — and ties document_id to the finalize prerequisite, but to/cc/bcc/subject/message get no explanation beyond their conventional names and examples.

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 opening sentence gives a specific verb and resource ('Queue the document to be emailed, with its PDF attached'), which cleanly separates it from document_render (makes a render) and document_transition (finalizes). An agent can identify the operation without opening 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?

Explicit preconditions are stated: the document must be finalized (draft sends are a 409) and, under the default attach_pdf path, a render must already exist. It spells out the correct call sequence (create, finalize, render, send), names the failure mode for skipping a step, and gives the alternative path (attach_pdf: false) that removes the render requirement.

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 reasonably well: it discloses the 409 refusal on invalid transitions and clarifies that `to: "sent"` is a record-keeping action rather than an actual delivery. It omits permissions/auth requirements and whether voiding is irreversible, which matters for a lifecycle-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?

Front-loaded purpose sentence, scannable bullets per transition, and a closing caveat that prevents the single most likely misuse. No filler, and the duplication of the enum list is defensible as authoritative state-machine semantics.

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 2-parameter state-machine tool with no annotations and no output schema, the description covers valid targets, failure mode (409), and the sibling boundary. It does not state what the call returns or which role can perform each transition, leaving modest 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 enum values are already fully documented in the schema, and the description's bullet list is essentially a verbatim restatement of the `to` property description. `document_id` has no description in either place, and the description does not compensate, so schema coverage of 50% is only partially offset.

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 ("Move a document through its lifecycle") and enumerates every legal target state, so an agent knows exactly what the tool mutates. The closing sentence explicitly separates it from `document_send`, which is the most confusable sibling.

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?

Bullets define what each transition means operationally (e.g. `unpaid` undoes `mark_paid`, `restored` revives an archived doc) and route the agent to `document_send` when actual emailing is intended. The gap is that it never states which source state each transition requires, saying only "valid from certain states," which leaves the agent to discover the state machine by trial and 409.

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 does real work: it discloses the draft-only precondition, the 409 failure mode, and precise patch semantics (only sent fields change, explicit null clears). It omits side effects an editor of invoices would care about — whether totals are recalculated, whether validation runs, or what the call 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?

Three short sentences, zero waste, with the precondition first, the failure mode second, and the field-level contract last. Every sentence carries information an agent needs.

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 23-parameter mutation tool with no annotations and no output schema, the description covers the state constraint and patch semantics well but leaves field-specific meaning and post-call behavior undocumented. An agent could call it correctly for simple scalar edits but would be guessing on nested arrays and unsupported fields.

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 0% across 23 top-level parameters, so the description must compensate, and it does explain the global omit-vs-null contract that governs every field. However, it says nothing about the many opaque fields (reason, source_document_id, business_profile_id, tax_scheme) or whether array fields like line_items are replaced wholesale or merged, which is the highest-risk ambiguity here.

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

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

States a concrete verb and resource ('Change a document') plus the gating state ('still a `draft`'), which tells an agent immediately what class of operation this is. It does not name a sibling (e.g. document_transition or document_create) to differentiate the path for non-draft documents, so it falls just 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?

Gives a clear when-to-use condition (document is in draft) and a when-not (finalized documents are immutable, returning 409). It stops short of pointing to the alternative tool for a finalized document, leaving the agent to infer document_transition or document_duplicate.

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 does useful work by declaring the operation stateless, non-pricing and non-rendering, which implies no side effects and no persisted artifacts. But it never says what a failed check produces — an error list, a boolean, an exception — and there is no output schema to fall back on. For a validation tool, the failure behavior is the behavior that matters most.

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

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

Three short sentences, purpose first, then cost/contrast, then routing to alternatives — a sensible front-loaded order. Mild redundancy between 'without pricing it' and 'no totals are computed' costs it a point.

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 takes a large nested invoice document, and 'well-formed' is left undefined: schema shape only, or EN 16931 business rules too? The sibling compliance_check makes that ambiguity consequential. Combined with no output schema and no statement of what a failure looks like, an agent cannot predict the result of calling it.

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 description says nothing about either top-level parameter, and reported schema description coverage for them is 0%, so it fails to compensate on the surface. In practice the nested $defs carry very rich per-field documentation, so an agent can still construct a payload. The description adds no meaning of its own here.

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

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

States a specific verb and object: 'Check that a document body is well-formed', plus the key negative — no pricing. It distinguishes itself from the two neighboring stateless operations. The only blemish is that the named siblings are inverted ('calculate_document'/'render_document' vs. the actual 'document_calculate'/'document_render'), which slightly blunts the differentiation.

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 routes the agent: use the calculate tool for money, the render tool for the document, this one for neither. That is real when-to-use guidance with named alternatives. It does not address the overlap with compliance_check, which is the less obvious boundary an agent would need.

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?

No annotations are supplied, so the description carries the full disclosure burden. It usefully states the return payload (full input schema of each match) and reassures that most of the API is reachable this way, but says nothing about whether the search has side effects, how many matches come back, ordering, or token cost of returning many schemas.

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, both earning their place: the first defines the operation and its output, the second defines the trigger. The usage condition is front-loaded immediately after the purpose with 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?

As a discovery meta-tool in a family that includes call_operation, the critical missing piece is the bridge: the description never explains that matches are then executed with call_operation, nor what identifying field the result carries. The mechanics of the search itself and its return shape are adequately 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 single query parameter is fully documented in the schema, including worked examples, so the baseline is 3. The description's "by what it does" reinforces intent-based rather than name-based matching, but adds no new constraint, format, or search-syntax detail beyond what the schema already says.

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: search every API operation by what it does and return each match's full input schema. That is far more precise than the name alone. It does not distinguish itself from the sibling call_operation, which is almost certainly the follow-on step, leaving a small gap in differentiation.

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 this when no tool above covers what you need" gives a clear activation condition and implicitly rules out cases where a concrete sibling already applies. It does not go further to say what to do with the results (e.g. invoke the discovered operation via call_operation), so the guidance stops one step short of the full workflow.

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 present, the description carries the full burden and does so well: it declares irreversibility ("cannot be resumed or edited afterwards"), the exact failure mode of a repeat call (409), and the blast radius ("Invoices already issued are left alone"). That is precisely the mutation-risk context an agent needs before calling a destructive 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?

Four short sentences, front-loaded with the terminal nature, then error behavior, then the alternative, then the side-effect caveat. Nothing is padded and 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 single-parameter destructive tool with no annotations and no output schema, the description covers consequences, error behavior, side effects, and the alternative. It leaves out any mention of permissions/authorization and what the call returns, which are the remaining 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 0%, so the description would ideally explain `recurring_id`, but it says nothing about it. The name is self-describing and there are no enums or nested objects, so the risk of misuse is low, but the description adds no meaning beyond the schema.

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

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

"End a schedule permanently" gives a specific verb plus resource, and "permanently"/"Terminal" immediately separates it from the pause and resume siblings. An agent can tell this is a destructive lifecycle termination 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?

It explicitly routes temporary stops to a pause tool, which is exactly the when-not-to-use guidance this needs. The problem is that the named alternative `pause_recurring_invoice` does not match any sibling — the real tool is `recurring_pause` — so the routing hint is directionally right but literally wrong.

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 it does disclose two real behavioral traits: the schedule is created in an active state and will issue invoices without further action, and the products are ordinary documents rather than a special entity type. It omits important consequences — that generated invoices are not finalized by default (auto_finalize defaults false), how to stop or cancel the schedule, and what state results after cancellation.

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

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

Three short sentences, front-loaded with the core purpose and with zero filler. The final sentence's tool reference is inaccurate, which costs it a point, but the prose itself is tight.

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 10-parameter tool with a large nested template schema, no output schema, and no annotations, the description covers purpose and activation state but leaves the most complex surface unexplained: how the invoice_template payload is parameterized per occurrence, and how invoice numbering is resolved between the template and numbering_sequence_id. Adequate to start, not adequate to call confidently.

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 80%, so the schema already documents the key fields (frequency, start_date, interval, end_date, max_occurrences, auto_finalize), and the description adds nothing about them. The largest omission is `invoice_template`, a deeply nested payload used as the per-occurrence template — the description never explains how its invoice_number, issue_date, or currency fields interact with recurring generation or with numbering_sequence_id.

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 — 'Set up a schedule that issues invoices on its own' — which distinguishes it from the one-off document_create sibling by emphasizing autonomous, recurring issuance. It stops short of explicitly naming the sibling it replaces, so it lands at clear-but-not-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?

It gives implicit context (it starts active, first invoice fires when the schedule next falls due) and points to a reader for outputs, but offers no guidance on when to choose this over document_create, no prerequisites (an existing customer_id and business_profile_id are required), and no mention of recurring_pause/recurring_resume/recurring_cancel for lifecycle management. Notably it names `list_generated_invoices`, which does not appear in the sibling list — the closest match is `recurring_generated`.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose a genuinely useful trait — results are ordered newest first — but says nothing about pagination behavior (limit/cursor), what is returned when a schedule has issued nothing, or required auth on the schedule. For a read-only listing tool that 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?

Short and front-loaded, which is good, but the two sentences are largely redundant: "The invoices one schedule has actually issued" and "The documents produced by this schedule" restate the same idea. Terminology also drifts between "invoices" and "documents" for the same return objects, which costs a little clarity.

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

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

There is no output schema and no annotations, so the description must carry more than it does. It conveys the concept and ordering of results but omits pagination semantics and any sense of what a returned document record contains, which matters for an agent that must decide whether to page or how to consume the result.

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 0% — the schema gives only titles and types for `recurring_id`, `limit`, and `cursor`. The phrase "one schedule" implies what `recurring_id` selects, but `limit` and `cursor` (paging) are not explained at all, and "newest first" only hints at ordering rather than the cursor's role.

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 resource and scope: the documents/invoices actually issued by one recurring schedule, with explicit ordering ("newest first"). It also states what the tool is not (the list of schedules themselves), so an agent can distinguish it from the schedule-listing tool without opening 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?

Explicitly contrasts with the alternative: "as opposed to `list_recurring_invoices`, which lists the schedules themselves" tells the agent when to pick this one. However, the referenced sibling name does not exist in the sibling list (the actual tool is `recurring_list`), and there is no guidance on paging or on cases where no documents have been generated.

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 provided, the description carries the full disclosure burden. It does add useful context — results are account-scoped, sorted newest first, and represent definitions rather than generated invoices — but it says nothing about pagination behavior, permissions, or total-count/ordering guarantees for a tool that clearly supports cursoring.

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

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

Three short sentences, front-loaded with what the tool returns, followed by the disambiguation and the filtering hint. No filler and no repetition of the input schema.

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 no annotations, no output schema, and zero parameter documentation, the description resolves the highest-risk ambiguity (definitions vs. generated invoices) competently. However, it leaves an agent guessing about cursor-based paging and what a schedule record looks like, which is a meaningful gap for a list endpoint.

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 0%, so the description must explain all three parameters. It only addresses `status` (results can be narrowed by it) and gives no semantics for `limit` or `cursor`, leaving the pagination contract entirely undocumented in both schema and description.

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 identifies the resource (recurring schedule definitions on this account) and the ordering (newest first), and it explicitly separates this from the invoices those schedules produce. The verb is implied by the tool name rather than stated, but an agent can still tell this apart from recurring_generated or the document_* 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?

It names the alternative explicitly ('for those, use `list_generated_invoices`') and states the distinguishing condition, which is the most likely point of confusion for this tool family. It also notes that results can be narrowed with `status`, though there is no guidance on when filtering is advisable or on how paging should proceed.

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 much of it: state prerequisite, HTTP 409 refusal for non-active schedules, and the side-effect scope ("Nothing already issued changes"). What remains undisclosed is the response payload and any permission requirements, which matters 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?

Three short sentences, zero filler, with the core action first and the constraint and reversal path after it. Every sentence adds information an agent would otherwise have to guess.

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 mutation with no annotations and no output schema, the definition covers precondition, error behavior, side effects, and the recovery path. Only the identifier's provenance and the success response shape are absent, which are minor for a tool this narrow.

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 0% and the single parameter `recurring_id` is never mentioned in the description, so its format, where it comes from (presumably recurring_list/recurring_create), and whether it accepts an external reference are unstated. The parameter is self-evidently an identifier on a one-param tool, which keeps this at minimum-viable rather than failing.

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?

Opens with a specific verb+object ("Stop a schedule issuing invoices") plus the crucial temporal qualifier "for now", which distinguishes it from recurring_cancel without naming that sibling. It also points at the inverse operation, resume_recurring_invoice, so an agent can place the tool in the lifecycle immediately.

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?

"Only an `active` schedule can be paused; anything else is refused with 409" gives an explicit precondition and failure mode, and "Restart it with `resume_recurring_invoice`" names the alternative. It stops short of saying when to choose pause over recurring_cancel, leaving the temporary-vs-permanent distinction to be inferred from "for now".

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 the state-transition requirement, the specific failure code (409), and the irreversibility of a cancelled schedule. Gaps remain on what resuming actually triggers (immediate issuance vs. waiting for the next scheduled run) and on permission requirements.

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

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

Three short sentences, front-loaded with the operation and followed by the precondition and the failed-recovery path. 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?

For a single-parameter mutation with no output schema, the definition covers the main risk an agent faces: calling it on the wrong state. It does not explain the observable effect of a successful resume or how to obtain a valid id, which would round it out.

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 0% and the only documentation for `recurring_id` is the bare title, so the description must compensate. Saying the target is 'a paused schedule' implies the identifier refers to a recurring schedule in that state, but it adds no format, sourcing, or lookup guidance (e.g., how to obtain the id from recurring_list).

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 ('Start a paused schedule issuing again') and names the exact state precondition, which distinguishes it from recurring_pause, recurring_cancel, and recurring_create among siblings. An agent can identify the operation without opening 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?

It states both the when ('Only a `paused` schedule can be resumed') and the when-not ('anything else is refused with 409', cancelled schedules cannot be brought back), plus the correct alternative ('create a new one'). Nothing about applicability 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?

With no annotations, the description carries the full behavioral burden. It implies a safe, account-scoped read of built-in templates, but says nothing about return shape, whether template IDs are stable, ordering, or pagination. It is enough to know this is a read, but not enough to know what you get back.

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 primary scope first and the disambiguation second. Every clause earns its place and nothing is repeated from structured fields.

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

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

There is no output schema and no annotations, so the description is the only source of information about results, yet it never describes what a template entry contains or how these templates are consumed by document_render/document_render_stored. For a simple catalog call this is adequate but leaves a real gap an agent would care about.

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 properties, so there are no parameters whose semantics need explaining. Baseline 4 applies; the description adds nothing misleading about inputs because there are none.

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 resource (built-in templates available to every account) and implicitly the list operation, which the name confirms. It cleanly separates this from the custom-design case, although the sibling it names (`list_custom_templates`) does not appear in the supplied sibling list, which slightly weakens the routing signal.

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

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

It gives clear usage context: use this for built-in templates, use the other tool for your own designs. There is no explicit when-not guidance or follow-on step (e.g., feed these IDs into document_render), but for a zero-parameter catalog tool the selection guidance is essentially complete.

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