McpStamp Invoices

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the mutation profile is known. The description adds genuinely useful non-annotation context: writes persist to a shared profile read by every other server, hence the 'call it once, first' ordering. However, it never says whether omitted fields are preserved or cleared on a subsequent call, which matters a lot for a 16-parameter setter flagged non-idempotent — that ambiguity keeps it at 3.

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 most important facts — what it owns, where it lands, when to call — are front-loaded. No restating of the title or filler.

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

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

For a 16-parameter mutation tool with no output schema, the description covers the cross-server blast radius and call ordering an agent needs before invoking it. The remaining gap is update semantics (overwrite vs merge on repeat calls) and whether a return value confirms saved 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 coverage is 100%, so the baseline is 3; the description goes slightly beyond by grouping parameters into functional clusters (identity, address, VAT, bank, defaults including currency/tax rate/terms/prefix/timezone) that help an agent decide which are core versus optional defaults. It doesn't explain the three tax-rate aliases (vat, tax_rate, vat_rate) or the email/phone 'only if the user gave it' rule, but the schema already carries those.

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 ('The ONE business profile... Save to the shared profile') and enumerates the exact fields it owns (name, address, VAT id, bank, defaults). The phrase 'the ONE business profile for the whole suite' cleanly separates it from siblings like client_add and invoice_create, which operate on other entities.

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?

'Call it once, first' gives explicit sequencing and frequency guidance that an agent can act on before calling any invoice or client tool. It stops short of naming alternatives or stating what to do if the profile already exists (re-call vs read), which would have made it a 5.

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

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

The annotations only tell us this is a non-destructive, non-idempotent write; the description goes well beyond that by disclosing upsert semantics ("re-adding the same name updates the stored address, email and VAT id") and the conflict path (an identical record is refused with the id that holds it). It leaves one meaningful gap: whether fields omitted on a re-add are cleared, preserved, or ignored.

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, and both earn their place: the first states purpose and downstream consumer, the second states upsert and conflict behavior. Purpose is front-loaded and nothing is padded.

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

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

For a mutation tool with no output schema, low schema coverage and four parameters, the description supplies the essential behavioral contract: name as identifier, update-on-re-add, and refusal of exact duplicates with the offending id. The remaining gap is the return/identifier behavior on success and how omitted fields are treated on update.

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 25%, so the description carries real weight — and it does name all four fields (name, address, email, VAT id) and establishes that "name" is the key used for lookup and for invoice_create references. It does not add format or validation detail for vat_id/email beyond the single schema note, nor clarify partial-update semantics.

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

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

The description opens with a specific verb and resource ("Store a client") and immediately ties it to a downstream sibling ("so invoice_create can refer to them by name"). That makes it trivially distinguishable from client_list, client_delete and the invoice tools 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 states the condition that motivates calling it — creating a client that a later invoice_create can reference by name — and discloses the re-add path. What's missing is an explicit exclusion (e.g. use client_list to look up, client_delete to remove), so it stops short of full when/when-not routing.

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

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

The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds important behavior beyond the annotations by disclosing the referential-integrity guard and the failure mode: referenced clients are refused and the blocking documents are listed.

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 definition is two sentences, front-loaded with the core action and the key constraint. Every phrase contributes useful information, with no redundant restatement of the title or sibling names.

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

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

For a one-parameter destructive tool, the description supplies the essential invocation context: what is deleted, the referential-integrity precondition, and the refusal behavior. The annotations already cover the destructive and non-idempotent nature, so no material gap remains for correct agent use.

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

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

Schema coverage is 100% and the single parameter is fully documented as 'Client name or id, exactly as client_list shows it.' The description adds no further parameter semantics, so the baseline 3 is appropriate when the schema carries this burden.

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

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

The description uses the specific verb 'Delete' with the resource 'client' and narrows scope to 'one stored client that nothing refers to.' This distinguishes it from sibling tools such as client_add and client_list without requiring the schema to be opened.

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

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

It clearly states the condition under which deletion is allowed and explicitly says deletion is refused when the client is referenced by invoices, quotes, credit notes, purchase orders, deposits, statements, or schedules. It does not name an alternative tool, but the when-not condition is unusually specific.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds useful behavioral context beyond annotations: it states the empty-list behavior ('With none stored it says so') and notes that invoice_create can create a client, which helps interpret an empty result. No contradictions with annotations.

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

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

The description is short and front-loaded with the main purpose. The final note about invoice_create is slightly tangential but still adds context about empty results; overall it earns its place without excessive verbosity.

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

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

For a zero-parameter, read-only list tool without an output schema, the description is complete: it names the result fields, states the empty-case behavior, and confirms no side effects. Nothing an agent needs to invoke this correctly is missing.

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

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

The tool has zero parameters and the schema is an empty object with 100% coverage, so there is essentially no parameter semantics to add. The description explicitly confirms 'No arguments,' which is sufficient and aligns with 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?

The description states a specific verb ('List') and resource ('every stored client') plus the exact fields returned (id, address, email, VAT id). It is immediately distinguishable from siblings such as client_add and client_delete, and even clarifies the no-argument nature of the call.

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

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

The description gives clear context for when to call this tool (need to see all stored clients) and explicitly notes it takes no arguments and writes nothing, signaling it is a safe read-only list operation. It does not explicitly enumerate when not to use it, but the purpose is self-evident among the sibling tools.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent, closed-world write. The description adds real value beyond that: a never-reused invoice number is returned, rounding happens per line before summing, mixed currencies are refused, and there is a free-tier limit of 3 per month. It still does not say whether the invoice is issued/finalized on creation or what a failed call leaves behind, which matters for a non-idempotent write.

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, front-loaded sentences that each carry a distinct fact: return value, units/rounding, currency constraint, quota. The telegraphic style is efficient, though fragments like 'Free: 3 a month' would read better as an explicit quota statement.

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 7-parameter create tool with no output schema, the description covers the return shape (record plus number), monetary units and rounding, currency agreement, and a rate limit. It is close to complete; the main omission is the lifecycle state of the created invoice and any consequences of auto-adding unknown clients.

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

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

Schema coverage is 100%, so the schema already documents every parameter, including unit_price in major units and the currency-agreement rule. The description reinforces the major-units convention and the round-then-sum ordering, which is a useful correctness cue, but adds little syntax or meaning the schema does not already carry.

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?

'Create an invoice from line items' states a specific verb and resource, and the 'from line items' framing implicitly separates it from invoice_from_hours. It never names a sibling outright, so the differentiation is inferable rather than explicit.

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 explicit when-to-use or when-not-to-use statement; the agent must infer that hour-based billing belongs to invoice_from_hours and that retrieval belongs to invoice_get. The 'one currency per invoice' rule gives some prep guidance, but nothing routes the caller between siblings.

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

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

Annotations establish the mutation profile (not read-only, not idempotent, non-destructive), so the description's job is narrower. It adds the entry_ids echo-back behavior that enables chaining to entry_mark_billed, which is valuable. But for a non-idempotent create it does not warn that repeat calls produce duplicate invoices, and it says nothing about permissions or side effects on referenced entries.

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 compact, front-loaded sentence that leads with the purpose and then the branching behaviors. Every clause carries information; the only minor cost is that the fx_rates and entry_ids clauses make it denser than it needs to be, since the schema already explains those 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?

With 14 parameters, a non-idempotent create, and no output schema, the definition should do more work. It gives the gist of the return ('returns a single-line invoice', echoes entry_ids) but omits the idempotency caveat and doesn't sketch the response shape, which matters because there is no output schema to fall back on.

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 ties the core semantics together: hours and rate form a single line, fx_rates with target_currency converts the rate, and entry_ids are echoed back. That is real meaning beyond the field list. It still leaves tax_rate, discount_percent, due_days, issue_date and notes unmentioned, though those are largely self-describing by name.

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 ('Creates and returns a single-line invoice') plus the narrowing scope ('bill one client for N hours at an hourly rate'). The 'shortcut for the common case' framing implicitly distinguishes it from invoice_create, but never names that sibling, leaving the contrast to inference.

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

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

Implies the usage context (one client, one hourly rate, single line) and names the trigger for the fx_rates branch, which is genuinely useful. However it never states when NOT to use it or that invoice_create is the alternative for multi-line or non-hourly invoices.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value by disclosing the returned shape — all lines, tax breakdown, and post-credit-note balance via credited_minor. It says nothing about behavior for an unknown invoice number (error vs empty result), which is the remaining unknown for an agent.

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 dense sentence with the core action front-loaded and no filler; every clause adds payload information the schema does not carry.

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

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

With no output schema and no annotations about return content, the description carries that load and does so well by describing the record's contents. The only gap is missing-invoice behavior and identifier format, minor for a read-only single-entity getter.

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

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

There is one parameter with 0% schema description coverage; the description only re-establishes that 'number' is an invoice number. It adds no format, prefix, or example value, so the agent still has to guess the expected identifier syntax.

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 ('Return the full stored record for one invoice number') and enumerates the payload (lines, tax breakdown, open balance), which implicitly separates it from invoice_list. It never names a sibling tool explicitly, so differentiation is inferred rather than stated.

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

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

The phrase 'full stored record' hints this is the detail-retrieval path versus a list/summary call, and the mention of credited_minor points to reconciliation use. However, there is no explicit when-to-use, when-not-to-use, or named alternative such as invoice_list or invoice_pdf.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description's real contribution is disclosing the returned fields and the derived 'balance still due after any credit note', but it says nothing about result ordering, result caps, or pagination for what could be a large collection.

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

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

Two sentences, front-loaded with purpose followed by filtering capability; the field enumeration is dense but earns its place because no output schema exists. Slightly list-heavy, but nothing 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 read-only list tool with no output schema, enumerating the returned fields and the credit-note-adjusted balance is exactly the missing context an agent needs. The remaining gap is pagination/ordering behavior on a potentially unbounded collection, which is not addressed.

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%: 'from' and 'to' are documented as YYYY-MM-DD inclusive, while 'client' and 'status' have no schema descriptions. The description recovers the three filter dimensions (status, client, date range), which is modest compensation, but it adds no format or matching semantics for 'client' (exact id, name, or partial match) beyond what the schema already shows.

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 ('List invoices') and immediately enumerates the fields each record carries, which separates it from invoice_get and overdue_report at a glance. The odd phrasing 'by number' would be better as 'with' given the fields listed are not numbers, but the intent is still 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?

'Filter by status, client and date range' implies how to narrow results, but there is no explicit when-to-use guidance, no statement of what an unfiltered call returns, and no reference to sibling tools such as invoice_get for a single record or overdue_report for outstanding balances.

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

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

The annotations cover the safety profile: not read-only, not destructive, not idempotent. The description adds real behavioral context on top: the additive rather than replacing semantics, which is the key non-idempotent detail, and the failure mode that an overpayment is refused with the open balance named. It says nothing about currency handling or whether a nonexistent invoice number errors.

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 highest-risk parameter semantics and the error case. There is no filler, and each sentence gives information the caller 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 mutation tool with no output schema and 5 parameters, the description covers the amount parameter and the overpayment behavior well. It leaves gaps on partial failure and edge cases, such as whether the invoice number must match an existing invoice and the response shape. This is adequate but not complete.

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

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

With 80% schema coverage, the baseline is 3. The description expands on `amount`: major units, additive, omit to settle in full, which largely repeats the schema's own wording. The other four parameters, including `number` and the free-form `method` and `reference`, get no added meaning from 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 gives a specific verb and resource: 'Record a payment on one invoice.' That is clearly distinct from the sibling tools (invoice_create, invoice_get, invoice_list, overdue_report) even though none of them is named. It is not a restatement of the name, so the purpose is clear 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?

The description implies when to call it (when a payment arrives for a specific invoice) and clarifies the omit-amount case, but it names no alternative and states no preconditions, such as the invoice needing to exist. An agent can infer the usage but must work it out rather than read 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?

Annotations already cover the safety/property profile (readOnly, idempotent, non-destructive, closed-world), so the description adds context on top: A4 page format, the exact page contents, and a real behavioral branch (Free adds a credit line and no logo; Pro renders unbranded with the customer's logo). It also states the return value is a path. It does not address overwriting an existing file at out_path or any tension between 'write' and readOnlyHint (the write is a rendered artifact, not a mutation of the invoice record).

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 dense sentences, front-loaded with the core action and ending with the branding variance, which is the only non-obvious choice. 'Call this tool to' is filler that could be dropped, but overall the text earns its place.

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

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

For a 2-parameter tool with full schema coverage, annotations, and no output schema, the description covers purpose, output (returned path), page contents, and plan-dependent branding. The remaining gap is overwrite behavior when out_path already exists, which an agent would plausibly want to know before invoking.

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

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

Schema coverage is 100% and the schema already documents both parameters in detail (including the default path, the .pdf requirement, and page contents). The description adds only that a path is returned, so it does not meaningfully extend parameter meaning beyond the structured fields — baseline 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?

States a specific verb and resource: write one stored invoice as an A4 PDF and return the path, plus what appears on the page (issuer, BILL TO, dates, items, taxes, totals). The scope ('one stored invoice', returns a path) implicitly separates it from invoice_get/invoice_list, but no sibling is named explicitly, so differentiation still requires inference.

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: 'one stored invoice' signals that the invoice must already exist (schema points to invoice_create), and the Free vs Pro sentence tells the agent what branding to expect. There is no explicit when-to-use/when-not or alternative routing (e.g., use invoice_get for data, this for a file), so an agent must infer the 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?

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world. The description adds real value beyond that: the effect is scoped to 'this connection', existing data under the token is preserved, and a wrong or expired key is a no-op. It does not say whether the change is immediate or whether repeat activation is harmless, which is relevant given idempotentHint=false.

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

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

Two short sentences, front-loaded with the effect and followed by the failure guarantee and verification pointer. No filler or restated boilerplate.

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, no-output-schema tool with annotations covering the safety profile, this is close to complete: effect, scope, failure behavior, and a verification sibling are all covered. Only minor gaps remain (immediacy of effect, behavior when already licensed).

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

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

Schema coverage is 100% and the single param already documents the MCPL1 format, so the baseline is 3. The description earns an extra point by adding provenance the schema lacks: the key is issued at checkout and must be for this server or the bundle.

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

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

The description names a specific action (turn Pro on) and its scope (for this connection), plus the exact credential shape required. It also positions the sibling license_status as the verification path, so an agent can distinguish activation from status checking without opening either schema.

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

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

It states the precondition clearly: the key must be an MCPL1.<payload>.<signature> token issued at checkout for this server or the bundle, and directs verification to license_status. It stops short of explicit when-not-to-use guidance (e.g., what to do if already Pro or if the key is for a different server).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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 dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.

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

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

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke this tool correctly.

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

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

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.

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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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

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

The description explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state 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?

Annotations already declare readOnlyHint, idempotentHint, and closed-world scope, so the safety profile is covered. The description adds behavior beyond that: the result ordering ('worst first'), the per-currency aggregation, and the free/no-cost trait, none of which are in the structured fields. It stops short of describing pagination or result size limits, which is the only missing behavioral note.

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

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

Two short sentences, front-loaded with the scope and ordering, then the routing alternative and cost note. Every clause carries information; nothing repeats the title.

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's summary of return contents (days overdue, amount, per-currency totals) and sort order carries that burden well. Combined with the tri-state annotations and fully documented single parameter, an agent has everything needed to call and interpret 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 100% and the single as_of parameter is fully documented in the schema, including its default of today. The description adds no meaning beyond that, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('List every invoice not paid in full whose due date has passed'), plus ordering ('worst first') and payload ('days overdue and the amount, then a total per currency'). It also names the sibling it differs from, so an agent can distinguish it from invoice_list without opening either schema.

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

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

Explicitly routes the agent: this tool is the filtered past-due view, and 'Use invoice_list for everything still open' names the alternative and the condition that selects it. It also flags 'Free', which is a useful cost signal for tool selection.

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