Invoice

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them by enumerating the mutation types (add a line, change a rate, apply a discount, move the due date) and the human-approval precondition. It does not state reversibility or error behavior, keeping it short of a 5.

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

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

Front-loaded with the core action, then the precondition. Three sentences with only mild redundancy — the closing sentence re-emphasizes approval already stated in sentence one, which is defensible as a guardrail but slightly repetitive.

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?

Output schema exists, so return values need no explanation, and annotations carry the safety/idempotency profile. The description supplies the approval prerequisite and the range of possible mutations, leaving only per-parameter detail for changeId/invoiceId as a minor gap.

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

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

Schema description coverage is 0% across 3 parameters, so the description must compensate. It does explain the critical one ('confirmed' must be true, only after approval), but changeId and invoiceId are left entirely to their names. Partial compensation only.

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 ('Apply') and resource ('one suggested invoice change') with clear scope, and implicitly contrasts with the sibling suggest_invoice_change by specifying this is the accepting/committing half of the workflow. An agent can distinguish it from the suggest path 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 condition for use ('after the freelancer explicitly approves that change', 'Pass confirmed true only then') and a negative guard ('not a substitute for the freelancer's approval'). It does not name a sibling alternative explicitly, but the gating condition is unambiguous.

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-idempotent, non-destructive, closed-world, so the safety profile is covered by structured data. The description adds genuinely new behavioral context: the object stays an unapproved draft until seal_invoice, and the currency/amount representation contract for downstream calls. It does not address what happens on duplicate invocation, but that is largely covered by 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?

Three short sentences, front-loaded with the core action, then constraints, then unit conventions. Dense and largely waste-free, though the final sentence about amounts is slightly tangential since no amount parameter exists here.

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

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

An output schema exists, so return values need not be described, which relieves some burden. Still, for a 4-required-parameter creation tool with 0% schema coverage, three parameters (title, number, clientName) remain completely undefined for the agent.

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 4 required parameters, so the description must compensate. It clarifies that currency is a three-letter code and that amounts are minor units of that currency (relevant to later tool calls), but title, number, and clientName are left entirely unexplained 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?

"Start a draft invoice" is a specific verb+resource, and the description explicitly contrasts the draft stage with seal_invoice, so the agent can place it in the invoice lifecycle. It does not, however, distinguish it from the other draft-mutating siblings (place_line, set_invoice_due, offer_discount) that presumably operate on an invoice created here.

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 sentence about seal_invoice implies this is the entry point of the workflow before any commitment is approved, which is useful implied guidance. There is no explicit when-to-use/when-not statement (e.g., whether it must precede place_line, or what happens if an invoice already exists).

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 the write/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, and the description adds genuinely useful state-machine context: the operation only succeeds on a draft and is refused post-approval. It does not mention permissions/auth or what happens to the previous description text, so it stops short of full disclosure.

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, each earning its place: what it does, the state constraint, and the routing to the alternative tool. The key constraint (draft-only) is front-loaded in the first sentence.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description covers scope, precondition, exclusion, and fallback tool, which is close to complete for a mutation of this size, with the only real gap being parameter-level detail on invoiceId/lineId/description.

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 schema only carries a minLength/maxLength on description; nothing documents the invoiceId/lineId pairing (lineId even $refs invoiceId). The description says a 'line description' is being corrected but adds no format, length, or identifier semantics, so it does not compensate for the documentation gap across three required parameters.

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+resource ('Correct a line description') and scopes it to a draft invoice, which is far more than a restatement of the name. It also explicitly names a sibling for the adjacent case (suggest_invoice_change with add_line), so an agent can distinguish it from the other line-oriented tools 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?

It gives an explicit precondition (invoice must still be a draft), an explicit exclusion (a different description is refused after approval), and a named alternative for the case where you want a different line (suggest_invoice_change with add_line). Nothing about when to pick this tool is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds that results are scoped to the signed-in freelancer (an auth/ownership constraint) plus the downstream-id workflow, but says nothing about pagination or result-set size despite the offset 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 and scope, followed by the follow-up step and the anti-pattern warning. 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?

The presence of an output schema means return values need not be described, and the list-then-read workflow is covered. However, for a paginated list tool with an undocumented offset parameter, the omission of any pagination guidance leaves a 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% and the single parameter is offset, which the description never mentions. With a low-coverage schema the description is expected to compensate, and it does not explain pagination, defaults, or how many invoices come back.

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 with scope ('the signed-in freelancer's invoices'), which both identifies the operation and distinguishes it from read_invoice and the other invoice-mutation 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?

'Use a returned id with read_invoice. Do not guess an invoice.' gives a clear workflow: list first to obtain ids, then read. It routes to the correct sibling and rules out guessing, though it never states when listing is unnecessary (e.g., if you already hold an id).

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 carry destructiveHint=true and idempotentHint=false, so the description's added value is the seal-state rule and the hand-off to accept_invoice_change for changing a sealed discount. That is real behavioral context beyond the structured fields, though it never says whether a new discount replaces an existing one.

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, each load-bearing: the action, the kind/value mapping, the sealed-invoice rule, and the anti-fabrication constraint. Nothing is padded and the core action 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?

An output schema exists, so return values need no explanation, and the parameter and lifecycle rules are covered well enough to call it correctly. Only the unexplained 'note' parameter and the unspecified replace-vs-add behavior on unsealed invoices keep it short of 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 0% schema description coverage the description must carry the load, and it does for the hardest part: it ties each 'kind' enum to the meaning of 'value' (none uses 0, percent is a whole number 1-100, fixed is whole minor units). The required 'note' and 'invoiceId' parameters receive no explanation, leaving a small gap.

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 ('Record a discount the freelancer is putting on the invoice') and scopes it to the invoice workflow shared with siblings like seal_invoice and accept_invoice_change. An agent can distinguish this from place_line or quote_line_rate without opening a 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 gives clear operating context: the discount is the freelancer's, and after sealing a different discount is refused until accept_invoice_change applies an apply_discount suggestion, which tells the agent when this call will and won't succeed. There is no explicit when-to-use versus a sibling alternative, but the workflow condition is 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?

Annotations declare a mutating, non-idempotent, destructive write, and the description adds context those flags cannot convey: the sealed-invoice gate and the required add_line suggestion workflow. It does not explain why the operation is flagged destructive or whether duplicate calls create duplicate lines, so it stops short of 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?

Two tight sentences with no filler; the field list is front-loaded and the sealing caveat is placed second, which matches its conditional nature. Nothing is wasted or buried.

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

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

With an output schema present there is no need to describe returns, and the description covers the mutation's key constraint and the unusual 'minor units' rate convention. Minor gaps remain around invoiceId semantics and quantity/rate limits, but nothing essential to calling the tool is missing.

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

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

Schema description coverage is 0%, so the description carries the burden. It adds real meaning for rateMinor ('whole minor units') and lists the unit enum, but the other fields are mostly name restatements, and invoiceId plus the quantity/rate bounds are never addressed.

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 ('Add one line') and immediately enumerates the fields the line carries, so the agent knows this creates a line item rather than quoting a rate (quote_line_rate) or mutating an existing line (set_line_quantity). The mention of sealing ties it unambiguously to invoices.

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 when-not condition: once the invoice is sealed a new line is refused until accept_invoice_change applies an add_line suggestion, naming the alternative pathway. The positive when-to-use case (adding a line to an open invoice) is implied rather than stated, which keeps it 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 this is a non-read-only, destructive, non-idempotent mutation, so the safety profile is covered. The description adds genuine state-machine context beyond the annotations — the invoice-seal precondition and the fact that re-rating is refused post-seal — which is exactly the kind of behavioral trait annotations cannot express.

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 tight sentences with the core operation front-loaded and the seal constraint second. 'The rate already chosen' is slightly indirect phrasing, but there is no padding 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 three-parameter mutation with an output schema, the description covers the essential constraint an agent needs (sealed invoices reject new rates) and points to the change-request path. Missing auth/permission requirements and the meaning of 'already chosen' keep it just short of fully complete.

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

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

Schema description coverage is 0%, so the description must carry the load. It meaningfully clarifies rateMinor as a whole number of minor units in the invoice currency, which the bare integer schema (1..100000000) does not convey, but invoiceId and lineId remain completely unspecified.

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 ('Set the rate ... for one line') and specifies the unit as minor units of the invoice currency, which pins down the operation precisely. It does not explicitly contrast itself with siblings like set_line_quantity or offer_discount, but the resource-level specificity is enough to identify 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?

Gives a real usage condition: after the invoice is sealed, a different rate is refused, and the named alternative is accept_invoice_change applying a change_rate suggestion. This routes the agent away from this tool in the sealed case, though it says nothing about authorization or the pre-seal 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuine governance context beyond them: draft status is not an approved commitment and proposed changes do not authorize line/rate/discount/due-date changes. This is useful behavioral framing for a read 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?

The operative instruction ('Read the invoice before answering') is front-loaded, and the remaining sentences are compact governance constraints. Slight redundancy between the draft-status and proposed-changes warnings keeps it from a 5.

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

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

With an output schema present, return values need not be explained, and rich annotations carry the safety profile; the description supplies the policy context an agent needs before quoting an invoice. It is largely complete, missing only explicit parameter or alternative-tool routing.

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 (invoiceId) with 0% schema description coverage, and the description never mentions it or its expected form. With only one self-evident identifier the gap is minor, but the description does not compensate for the missing schema documentation.

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 clear verb+resource (read the invoice) and 'Quote only this record' implicitly scopes it to a single invoice rather than a collection like list_invoices. It does not explicitly name a sibling to distinguish itself from, so it lands at clear-but-undifferentiated.

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 a usage directive ('Read the invoice before answering') but no explicit when-not or alternative-tool guidance, even though siblings like list_invoices, describe_line, and quote_line_rate could plausibly overlap. Usage is implied rather than scoped.

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-destructive, idempotent write, and the description is consistent with that while adding the crucial behavioral gate (do not confirm until explicit approval). It still doesn't say what the sealed state means downstream (whether it can be reopened or amended), which limits it below a 5.

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

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

Two sentences, front-loaded with the action, followed by the precondition. The second sentence is a long enumeration but every item in it is meaningful approval criteria, so little is wasted.

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

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

For a two-parameter, approval-gated write with an output schema and full annotation coverage, the description supplies what the structured fields cannot: the state transition and the human-approval precondition. Only the post-seal lifecycle (irreversibility, next steps) is unaddressed.

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 carry the parameter burden. It explains the semantics of confirmed well (a deliberate approval gate), but invoiceId is left entirely to the schema and the const:true constraint on confirmed is never mentioned in prose.

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 precise verb and state transition ('Mark the current draft as the approved invoice'), which is clearly distinct from sibling lifecycle tools like begin_invoice, read_invoice, and accept_invoice_change. It does not explicitly name a sibling or contrast its behavior, so it falls just short of the top band.

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 precondition: pass confirmed=true only after the freelancer has approved the lines, quantities, rates, due date, late terms, and discount. This tells the agent both when to call it and when not to, which is exactly the guidance an approval-gated mutation needs.

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

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

Annotations only classify this as a non-read-only, non-idempotent write; the description adds the non-obvious business rule that post-seal dates are refused and names the remediation path (accept_invoice_change applying a move_due_date suggestion). It stops short of 5 because it doesn't clarify whether re-setting the same date on a sealed invoice is permitted or what error/return signals the refusal.

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 tight sentences with zero filler; the operation and its value format come first, and the sealed-invoice constraint with its remediation follows immediately. 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?

With an output schema present, return values need not be described, and annotations cover the safety profile. The remaining functional gaps are minor: no explicit precondition (draft/unsealed state) and no statement of what happens on a redundant same-date set.

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 carry the load. It does supply human-readable semantics for dueOn ('calendar day', YYYY-MM-DD) beyond the raw regex pattern, though it adds nothing about invoiceId beyond the self-evident 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?

The description states a specific verb and resource ('Set the due date') plus the value domain ('calendar day in YYYY-MM-DD form'), and it situates the tool relative to the sibling that owns the post-seal path (accept_invoice_change with move_due_date). An agent can distinguish it from suggest_invoice_change / accept_invoice_change 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 gives a clear when-not condition: once the invoice is sealed, a different date is refused and the change-suggestion route must be used instead. It does not explicitly state the normal precondition (invoice not yet sealed) or name suggest_invoice_change as the pre-seal alternative, so it stops short of full when/when-not/alternatives coverage.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the sealed-invoice refusal rule and the required remediation flow through accept_invoice_change, which an agent could not infer from the annotations 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?

Two sentences, zero filler, and the core action is front-loaded ahead of the constraint. Every clause earns its place by conveying either the operation or a non-obvious workflow rule.

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

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

An output schema exists, so return values need not be explained, and the sealed-invoice workflow rule is a valuable addition. However, with zero parameter documentation and no mention of auth or the effect on existing line totals, the definition is only minimally complete for a destructive mutation tool.

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

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

Schema description coverage is 0%, so the description carries the full burden for three required parameters, yet it only implies that 'one line' is identified by an id. It says nothing about invoiceId being a UUID, the 1-10000 quantity bounds, or whether quantity is absolute versus relative.

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: 'Set the quantity on one line.' It is unambiguous about what is mutated, though it does not distinguish itself from sibling tools like place_line or offer_discount beyond the resource it touches.

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 key usage constraint explicitly: after the invoice is sealed, a different quantity is refused, and it names the correct alternative path (accept_invoice_change applying an adjust_quantity suggestion). That is a clear when-not plus alternative, though it omits other preconditions such as required permissions or draft-state expectations.

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 declare readOnlyHint=false, so an agent could assume the invoice is mutated; the description corrects this with 'This does not change the invoice,' which is exactly the kind of context annotations cannot convey. It still omits whether repeated submissions create duplicates (idempotentHint=false) or what authorization is required.

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 two most decision-relevant facts, the action and the no-mutation guarantee, are front-loaded, followed by a dense one-clause-per-kind list. Nothing is padded, though the telegraphic sentence fragments would read better as a compact list.

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

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

With an output schema present, return values need no explanation, and the description supplies the conditional parameter rules the 0%-coverage schema lacks. The remaining gap is procedural context: no statement of prerequisites (e.g. invoice must exist in a draft state) or of what a recorded suggestion means for later acceptance.

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 17 parameters, so the description carries the entire burden and does so well by mapping each enum kind to its conditionally required fields (e.g. add_line needs description/quantity/rateMinor/unit). It leaves the always-required invoiceId and summary unexplained and does not state accepted values for unit or lateBasis.

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 ('Record a suggested change') and immediately scopes it with 'This does not change the invoice,' which separates it from the many mutating siblings. It does not, however, name or contrast itself with accept_invoice_change, the sibling that would otherwise be confused with it.

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 guidance on when to suggest a change versus applying it directly through siblings like place_line, set_line_quantity, offer_discount, or write_late_terms, even though the kind enum mirrors those tools. The per-kind requirement list implies what each kind does but never says when one is appropriate.

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 non-read-only, destructive, non-idempotent write, but the description adds genuinely new behavior: the mutual exclusivity of feeMinor and percent per basis, and the hard constraint that basis/grace/fee/percent cannot change after approval until a revise_late_terms suggestion is accepted. It stops short of stating permissions or what the write returns, so not a 5.

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

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

Three dense sentences, front-loaded with the action and the field semantics, with no filler. The final sentence is long but carries a real constraint rather than 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?

An output schema exists, so return values need not be described, and the description covers the mutation's semantics and its post-approval immutability rule. The remaining gap is the precondition for calling at all (which invoice states are writable) and the purpose of the note 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 0% across 6 required parameters, so the description must compensate. It does explain the basis enum meanings and the feeMinor vs percent coupling, but leaves graceDays, invoiceId, and note semantics (note is a required 1-1000 char justification) unaddressed.

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 ('Record late terms') and immediately enumerates the key fields (grace days, basis), including the three basis values. It is distinguishable from the read/calculate siblings, though it doesn't explicitly name a sibling it is not, 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?

Usage is implied rather than stated: the agent learns a post-approval write is refused until an accepted revise_late_terms suggestion exists, which is useful lifecycle guidance. However, there is no explicit when-to-use/when-not framing, no statement of required invoice state, and no comparison to sibling tools like suggest_invoice_change.

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