PaidPilot Invoice Tools

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuinely new operational context: it is a pure calculation with no network request, nothing is stored, it costs $0.02 USDC via x402 with the payment key location, and invalid input is errored without charge. That payment and billing-failure behavior is not derivable from the annotations.

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

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

Four tight sentences lead with the core transformation and then layer the alternative, the no-side-effect guarantee, and the pricing/error model. Every clause carries information an agent needs; nothing is redundant 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?

For a 16-parameter, nested, no-output-schema tool this covers the essentials: what it produces, that it is side-effect free, the cost, and error handling. It only gestures at the return shape ('validated invoice JSON with totals'), which is thin given the absence of an output 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?

Schema description coverage is only 31% across 16 parameters, so the description is expected to compensate, and it partially does by naming hours x rate, rounding, grouping and expenses. However, it adds no meaning for currency, discount, tax_rate, notes, terms, payment_instructions or the buyer/seller sub-objects, leaving the coverage gap only partly closed.

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+transformation: 'Turn time entries ... into a validated invoice JSON with totals.' It also names the sibling it is not ('Use validate_invoice ... instead if you already have an invoice'), so an agent can distinguish it from the other six 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?

Explicitly routes the agent to validate_invoice with the selecting condition ('if you already have an invoice'), which is clear alternative guidance. It does not address the other calculation/payment siblings (pricing, late_fee_calc), so some ambiguity remains, but the primary branch point is covered.

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 readOnly/idempotent/non-destructive/closed-world, and the description adds context those fields cannot carry: pure in-process calculation with no network request and nothing sent or stored, a $0.01 USDC x402 charge with the payment location (_meta["x402/payment"]), and the billing behavior on invalid input (error, not charged). This is exactly the kind of pricing and side-effect disclosure an agent needs before invoking.

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-loads what the tool does, then return values, then the sibling alternative, then caveats and cost. Every sentence carries distinct information (outputs, alternative, legal scope, purity, price); no filler or repetition.

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

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

Even without an output schema, the description names the return payload (days late, fee, new total, invoice line), covers the payment requirement and error/billing behavior, and disclaims legal-cap lookup. Nothing needed to call a 10-parameter calculation tool 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?

Schema description coverage is 100%, so the schema already documents all ten parameters including fee_type enum semantics, compounding behavior and grace_days. The description restates the fee-structure options but adds no syntax or format detail beyond what the schema provides; baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (calculate) and resource (late fee on one overdue invoice) and enumerates the supported fee structures (flat, monthly %, annual %, simple/compounding, grace days). It explicitly differentiates from the sibling payment_terms_check, so an agent can route correctly 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?

Gives an explicit alternative and the condition that selects it: 'Use payment_terms_check instead to work out when an invoice is due.' It also adds a when-not caveat ('Not legal advice; it does not look up state caps'), which prevents misuse for statutory-cap questions.

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 profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new operational context: the cost ($0.01 USDC via x402 with payment in _meta["x402/payment"]), that invalid input errors without charge, and that no network request or storage occurs. These are the kinds of billing and failure semantics an agent must know before calling.

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?

Purpose, return shape, prerequisite, and cost are all front-loaded in an efficient run of sentences with no filler. Minor redundancy between "Draft only: nothing is sent" and "nothing is sent or stored" 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?

For an 11-parameter, no-output-schema tool, the description covers everything material: the returned fields (subject, body, days overdue, suggested next step), the prerequisite chaining, the side-effect guarantee, pricing, and error/charge behavior. Nothing needed to invoke it 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?

Schema description coverage is 82%, so the schema already documents nearly all 11 parameters (tone, as_of, amount, currency, due_date, etc.). The description adds only the tone concept and the invoice framing, contributing little syntax or format meaning beyond what structured data supplies. Baseline 3 applies.

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

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

States a specific verb (draft), resource (payment reminder email), and scope (one unpaid invoice, three tone modes). It also names the sibling tool late_fee_calc and the condition for chaining, so an agent can distinguish it from invoice_from_timesheet or receivables_health_report without opening schemas.

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

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

"Use late_fee_calc first if you want the fee amount quoted" gives explicit sequencing guidance, and "Draft only: nothing is sent" implicitly routes agents elsewhere if they need actual delivery. No explicit when-not-to-use statement or exclusion of other siblings, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: pure local calculation, no network request, nothing sent or stored, a $0.01 USDC x402 charge with the payment field location, and that invalid input is not charged. That is exactly the kind of non-obvious cost and side-effect information 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?

Front-loads purpose and supported formats, then return values, then the sibling hand-off, then cost/error semantics. Every sentence carries distinct information with no 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?

There is no output schema, so the description usefully enumerates what comes back (discount amount and deadline, annualized cost of skipping the discount, suggested reminder dates) and also covers billing and error behavior. Nothing needed to invoke it 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?

Schema description coverage is 100%, so all five parameters are already documented, including the terms examples. The description repeats the same example terms ('Net 30', '2/10 Net 30', 'EOM') rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('work out the due date and status for payment terms') and enumerates supported term formats. It explicitly distinguishes itself from late_fee_calc, so an agent can separate it from siblings 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?

Gives a clear usage condition (computing due date/status from terms) and an explicit hand-off rule: 'Use late_fee_calc once the invoice is overdue.' This is a named alternative with the condition that selects 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 readOnly=true, idempotent=true, destructive=false and openWorldHint=false; the description reinforces this by stating no network request and no payment, and adds the concrete return content (tool prices, Base network, receiving address). It stops short of describing the response shape (currency, per-tool structure), so it adds value without being 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?

Three short sentences, front-loaded with the 'Free' signal, and each sentence carries useful information about cost, output, and side effects. Slight redundancy between 'Free' and 'no payment' is the only waste.

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 correctly compensates by enumerating what is returned. It is adequate for a zero-parameter read tool, though a hint about the price format/currency would make it fully self-contained.

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?

Zero parameters, so the baseline is 4. The description confirms 'No input', which is consistent with the empty schema and leaves no parameter ambiguity for the agent.

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 ('Return') and precisely enumerates the resource: the price of every paid tool, the HTTP invoice PDF route, the payment network (Base), and the receiving address. This is clearly distinguishable from the invoicing-focused siblings and an agent can tell exactly what it retrieves 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 framing 'Free. No input, no network request, no payment' tells the agent this is a zero-cost, side-effect-free lookup safe to call anytime, which is meaningful usage context. There are no alternative pricing tools among the siblings to exclude against, so the missing explicit 'use this when...' clause is a minor gap.

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 a safe read-only, idempotent, non-destructive profile, but the description adds substantial context beyond them: pure calculation with no network request, nothing sent or stored, an x402 cost of $1 USDC per call via _meta, and that invalid input returns an error without charging. That is a rich behavioral picture an agent cannot infer from structured fields alone.

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 purpose followed by outputs, usage, and pricing; every section is load-bearing. The long enumeration of return metrics is justified because there is no output schema, though it could be tightened slightly.

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 carries the full burden of describing returns and does so thoroughly — grade, score, aging buckets, overdue %, DSO, concentration, collection priority list with next action, and recommendations. Pricing and error behavior are also covered, leaving no material gap for correct invocation.

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

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

Schema coverage is high (83%), so the schema already documents most parameters. The description still adds value by naming supported CSV sources, noting that columns are auto-detected, capping input at 1000 invoices, and clarifying the CSV/JSON row duality — meaning beyond the raw field 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?

States a specific verb and resource ('Grade the health of a business's accounts receivable from its invoice list') and names the source data (invoice list/CSV/JSON). It also distinguishes itself from siblings by pointing to payment_reminder_draft and late_fee_calc as downstream actions rather than duplicating them.

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 it for a monthly AR review or before chasing payments' gives explicit triggering contexts, and the description routes the agent to payment_reminder_draft and late_fee_calc for next actions. It stops short of stating when NOT to use it or how it differs from payment_terms_check/validate_invoice.

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 readOnly/idempotent/non-destructive/openWorld=false, but the description adds real value: it is free, offline, requires no payment, and performs the identical checks as the paid PDF route. It also discloses the two possible return shapes (computed totals vs. field errors), which is more than the annotations convey.

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 compact sentences, front-loaded with 'Free.' and immediately stating the action, input source, and outcomes. No filler or redundancy.

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

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

For a single-parameter validator with nested input, no output schema, and full annotation coverage, the description supplies everything needed: the input origin, the two return cases, and the offline/no-payment behavior. Nothing essential 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?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond it by explaining where the invoice object comes from (body for POST /v1/invoice.pdf, or output of invoice_from_timesheet), which tells the agent the required level of well-formedness. It adds meaningful context without restating the field 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?

States a specific verb (validate) and resource (an invoice JSON), and clarifies which shape of input it accepts — the body for POST /v1/invoice.pdf or the output of invoice_from_timesheet. This lets an agent distinguish it from the generation siblings 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 makes the when clear: use this to run the same checks as the paid PDF route before committing, offline and free. It does not explicitly name alternatives to avoid (e.g. that this returns errors rather than generating a PDF), but the comparison to the paid route implies the intended pre-flight role.

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