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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true. The description adds a useful behavioral distinction: mode='scan' plans, mode='dry_run' actually executes dry-run steps. However it doesn't disclose the safety guarantees of these steps, what a 'recommendation' contains, or side effects. With annotations covering the safety profile, this is a modest addition.

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, front-loaded sentences with no filler. Slightly more context on the workflow itself would have been warranted, but nothing 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 complex 7-parameter workflow tool with an open-world annotation, no output schema, and many sibling tools, the description is thin. It doesn't explain what 'safe next steps' means, what the inbox merges, or what the result looks like. The schema carries parameter semantics, but overall context is barely sufficient.

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 seven parameters are already well documented in the schema, including defaults for max_depth and per-field meanings of the four dimension_id parameters. Baseline 3 applies; the description adds nothing beyond what the schema provides.

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 the tool ('Merged accounting inbox') and distinguishes the two modes, but 'Merged accounting inbox' is a vague noun phrase with no verb. Among dozens of siblings in the accounting surface (reconcile_bank_transactions, continue_accounting_workflow, recommend_workflow, analyze_unconfirmed_transactions), an agent cannot tell what this scans, what 'recommends safe next steps' means concretely, or when this is preferred. Purpose is discernible but weakly differentiated.

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

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

The description explains the difference between the two modes but gives no guidance on when to use this tool versus alternatives like recommend_workflow, continue_accounting_workflow, classify_bank_transactions, or the various reconcile_* tools. There are no exclusions or prerequisite conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the 'read-only' phrasing is largely redundant. The description adds useful behavioral context by enumerating which analyses the tool actually runs, but it doesn't disclose what happens to unconfirmed transactions afterward or what the response contains.

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

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

A single front-loaded sentence with the resource stated first and the operations enumerated compactly. Zero 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 should ideally convey what the agent receives back (a findings list, flagged items, etc.), and it only implies this through the enumerated analysis types. Combined with the missing usage guidance, the definition 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?

Schema coverage is 100%, so both parameters (min_confidence, accounts_dimensions_id) are fully documented in the schema. The description adds no meaning beyond that, 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?

The description names a clear verb (analyze) and resource (unconfirmed bank transactions) and enumerates the specific analyses performed (duplicates, invoice matches, own-account transfers, expense patterns). It is more specific than the raw name, though it does not differentiate itself from adjacent tools like classify_bank_transactions or reconcile_bank_transactions.

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 guidance, no prerequisites, and no mention of alternatives such as classify_bank_transactions or reconcile_bank_transactions. The agent must infer from the sibling list alone whether this is the right tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so safety is partly covered; the description nonetheless adds substantive behavior: an existing document is refused with the document_exists error, and replace_existing=true overwrites and permanently loses the old file. Permission/auth requirements are not mentioned, 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?

Three tight sentences: scope first, then the replace/refuse rule, then the domain rationale. No filler, and the most decision-critical constraint (refusal unless replace_existing) 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 correctly supplies the observable result of failure (document_exists) and success semantics (overwrite wipes the old file). It does not say what a successful attach returns or whether re-attaching the same file is treated as a no-op, but for a single-write tool with full schema coverage that is 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 100%, so the baseline would be 3. The description adds meaning beyond the schema by explaining the 'one document per record' rule and the document_exists failure mode that governs replace_existing, plus the file types accepted for file_path.

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 (attach) and resource (source document) with the exact file formats accepted and enumerates the four target entity types, which are the enum values of entity_type. An agent can immediately distinguish it from get_document and delete_document siblings.

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

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

Gives clear use context: the RPS rule that every accounting entry requires a source document, and that manual journals and directly-booked transactions need one too. It also states the one-document-per-record constraint and the replace_existing override. It does not name a sibling (e.g., delete_document to clear a wrong attachment), 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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: irreversibility is per successful row (not all-or-nothing), already-registered rows are skipped rather than re-processed, and failures/indeterminate outcomes are surfaced per ID. This is meaningful partial-failure semantics an agent cannot get 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?

Two terse sentences with zero filler; the irreversible nature is stated first, followed by skip/error semantics. Every clause carries distinct information and the highest-risk fact 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 correctly compensates by describing the per-ID result reporting (success, failure, indeterminate), which is the key return behavior. It stops short of describing whether the response is partial on failure or how skipped rows are distinguished, but coverage is solid for a 2-parameter 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 100% — both 'ids' (positive integers, 1-500) and 'reason' (required audit note, max 500 chars) are fully documented in the schema. The description adds no parameter-level detail beyond schema, 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 ('Confirm/register') and resource ('journals') with explicit batch scope ('multiple'), which distinguishes it from the singular sibling confirm_journal without naming it. The purpose is unambiguous, but it never explicitly contrasts itself with confirm_journal or batch_delete_transactions.

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?

Batch usage is implied by 'multiple journals' and the 'batch_' prefix, but there is no explicit statement of when to choose this over looping confirm_journal, or whether all IDs must belong to the same connection/period. Usage is inferable but not stated.

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 and idempotentHint=false, but the description goes further by disclosing IRREVERSIBILITY and, crucially, partial-batch semantics: CONFIRMED rows are skipped and lookup/indeterminate outcomes are reported per ID. This per-ID failure behavior is exactly the kind of context an agent needs for a batch mutation. It stops short of stating permission/auth requirements or the required audit reason's behavioral role.

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 terse sentences, front-loaded with the action and the IRREVERSIBLE warning, then the skip and reporting semantics. No filler; every clause 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 two-parameter destructive batch tool with no output schema, the definition covers action, reversibility, skip logic, and failure reporting — a solid picture. Auth/permission prerequisites and the practical need for the audit reason are the only notable omissions.

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 ids and reason are fully documented in the schema. The description adds only a marginal hint ('per ID' reporting) and does not explain the semantics of the required audit reason or the 500-item cap. Baseline 3 applies when the schema carries the parameter 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?

States a specific verb and resource ('Delete ... transactions') and adds the batch scope ('multiple'), which cleanly distinguishes it from the sibling delete_transaction. The odd all-caps 'PROJECT' qualifier is unexplained and adds ambiguity rather than clarity.

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 batch scope and the note that CONFIRMED rows are skipped imply usage, and the contrast with single delete_transaction is inferable from the name. However, no alternative tool is named and there is no explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already declare write, destructive, non-idempotent, and open-world behavior, but the description adds the important default dry-run behavior and notes that withheld tax is handled. It does not explain the destructive impact of non-dry execution or remediation steps, so it falls short of fully rich behavioral 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?

Two short sentences with no filler. The action and scope are front-loaded, and the critical dry-run default is stated immediately after, making the description easy to scan.

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 12-parameter mutation tool with no output schema, the description covers purpose and the key safety default but omits workflow context: that an AccountStatement file is required and that a reviewed dry-run plan is needed before execution. The rich schema compensates for missing parameter details, but the two-step dry-run/execute process is left to inference.

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 12 parameters are thoroughly documented in the input schema, including defaults and account mappings. The description adds only high-level distribution types and tax handling, not parameter-level syntax or constraints, so the baseline 3 is appropriate.

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

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

States a specific verb and resource scope: 'Create journal entries for Lightyear dividend, interest, and reward distributions, including withheld tax.' This clearly distinguishes it from sibling tools like book_lightyear_trades and parse_lightyear_statement by focusing on distribution booking, though it does not name those alternatives explicitly.

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

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

The only guidance is 'DRY RUN by default,' which hints at a preview-first workflow but does not explain when to use this tool versus alternatives such as book_lightyear_trades or parse_lightyear_statement. No prerequisites, exclusions, or explicit when/when-not instructions are provided.

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 and idempotentHint=false, so the risk profile is known; the description usefully adds that the default is a non-mutating dry run and that sells need a capital-gains file for FIFO basis. It does not warn about duplicate journals on repeat non-dry-run calls, which is the main residual behavioral gap.

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, front-loaded sentences: action, safety default, then conditional requirement. No filler, and the most decision-relevant fact (dry run by default) appears early.

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 14-parameter booking tool with no output schema, the description covers the action, the safe default, and the one hard precondition. The dry-run → plan_handle → execute workflow is left to the schema, which is acceptable given the 100% coverage but would have been worth one sentence.

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% with rich per-parameter text (fee_account, skip_tickers, plan_handle defaults), so the schema carries the load. The description only reiterates the capital_gains_file requirement already encoded in the schema, adding little parameter-level meaning.

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

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

States a specific verb and resource — booking Lightyear stock Buy/Sell trades — which cleanly separates it from siblings like parse_lightyear_statement (parse only) and book_lightyear_distributions (different asset event). An agent can tell what this tool produces 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?

Clearly signals that the default call is a preview and that sells additionally require capital_gains_file, which is real usage guidance. It stops short of naming prerequisites (parse the statement first, or the reviewed-plan workflow behind plan_handle) or stating when not to call 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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds meaningful context beyond that: it is a pure calculator with no ledger access, and it discloses the date-gated rate behavior. It doesn't spell out return format, but with no output schema present this is a minor gap.

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 that front-load the core computation and then the scope boundary. It is information-rich without padding, though the parenthetical formula list is tight enough to be slightly heavy on first read.

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

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

For a pure-calculation tool, the definition covers what it computes, the rate logic, the data source boundary, and the origin of each input. Nothing material is missing for an agent to invoke it 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?

Schema coverage is 100%, so the schema already documents every parameter well, including defaults and omissibility. The description adds cross-tool provenance for two inputs (TSD declaration, compute_profit_and_loss), which is genuine value beyond the schema.

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

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

States a specific verb (compute) and resource (cumulative TuMS § 49 tax-free limits) with the exact formulas and rates involved. It is clearly distinguishable from sibling calculators like compute_profit_and_loss or compute_trial_balance.

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 defines what it is NOT: 'Pure calculator over caller-supplied year-to-date figures ... it does not read the ledger,' and names the sources for inputs (TSD declaration, compute_profit_and_loss). This positions it well, though it doesn't state when passing which optional args matters or when to skip it entirely.

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), so the bar is low, yet the description adds that the tool is advisory rather than a filing, that judgment on incidentality rests with the operator, and it provides provenance/verification date. It does not describe the shape of the returned verdict, but the added legal-date context is substantive.

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 sentences, front-loaded with the core check and threshold amount before provenance and advisory notes. The long source URL is justified for a tax rule pinned to a legal effective date, and no sentence is redundant.

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

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

For an 8-parameter tool with no required params and no output schema, the description supplies the domain model an agent needs (base turnover from confirmed sale invoices, separate buckets, operator decides incidentality) and annotations cover safety. Gaps remain: no stated return shape and no routing against get_vat_info.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema by explaining the model: confirmed sale invoices supply the taxable/0% base while the other buckets are supplied separately and only counted if non-incidental. That relationship between parameters is not visible from the individual field descriptions alone.

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 (check) and resource (Estonian VAT registration threshold) and pins it down with the exact 40 000 EUR figure and legal scope date 2025-01-01. It never differentiates itself from the VAT-adjacent sibling get_vat_info, so sibling routing is left to inference, but the operation itself is unambiguous.

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

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

It frames the tool as a read-only advisory and explains that the operator must judge whether real-estate/insurance/financial turnover is incidental, which implies the intended context. However, it names no alternative tool and gives no explicit when-to-use or when-not-to-use condition, so usage remains inferred rather than stated.

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 disclose destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds value by flagging that execute_apply 'requires approval' and that dry_run_apply is only a preview, but it never says what execute_apply actually mutates or whether its effects are reversible, leaving the destructive flag uncontextualized.

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?

It is a single compact line with no filler, and the mode breakdown follows the opening purpose statement. The lead fragment 'Merged unmatched-bank classification' is opaque internal jargon rather than a clean front-load, which keeps it out of the top band.

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 six-parameter, three-phase workflow tool with a destructive apply step and no output schema, the description covers only the mode names. It omits the data flow between phases (classifications_json and the consume-once plan_handle lifecycle) and any post-apply outcome, leaving real workflow gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the mode semantics that drive which parameters matter (classify vs apply, plan_handle, classifications_json), but adds no syntax or format detail beyond the schema.

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

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

The name plus 'Merged unmatched-bank classification' makes it clear this tool classifies bank transactions, and the three mode clauses sharpen the verb into concrete phases. It does not, however, distinguish itself from adjacent siblings like reconcile_bank_transactions or analyze_unconfirmed_transactions, so an agent must infer the boundary.

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 'classify groups; dry_run_apply previews; execute_apply requires approval' implies the intended phase order and the safety gate on the final phase. There is no explicit statement of when to prefer this tool over reconcile_bank_transactions, nor of preconditions such as needing classify output before apply.

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 and readOnlyHint=false, so the delete is flagged as destructive by structured data. The description usefully adds that metadata is only patched onto the kept transaction and that deletion targets the newly imported PROJECT duplicate, but it does not say whether deletion is reversible, what happens if the delete ID is not actually a duplicate, or what the operation returns.

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

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

A single sentence that front-loads the patch action before the delete, which matches the actual execution order. It is efficient, though slightly dense with compound clauses.

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 destructive, non-idempotent mutation with a nested patch object and no output schema, the description covers the core mechanic but omits what an agent needs: behavior on validation failure, whether the delete is hard or soft, and confirmation requirements. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so both IDs and the patch object are already documented in the schema. The description adds the semantic framing of which ID is authoritative ('kept older') versus deleted ('newly imported duplicate'), which reinforces but does not go beyond the schema's own descriptions.

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 compound verb+resource: patch CAMT metadata onto the kept transaction, then delete the duplicate PROJECT transaction. The keep/delete pairing is explicit and clearly distinguishes it from generic delete_transaction or detect_duplicate_purchase_invoice.

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?

Implied usage (resolving a detected possible-duplicate) is clear from the name and pairing of keep/delete IDs, but there is no explicit when-to-use statement, no mention of the sibling detect_duplicate_purchase_invoice as the upstream step, and no stated preconditions such as having already reviewed the duplicate.

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

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

Annotations already declare readOnly, idempotent and non-destructive, and the description is consistent with them while adding the useful nuance that only cached API/reference data is discarded, not business records. It does not mention the cost of the operation (subsequent calls refetch upstream), which would have made it 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, zero filler, with the action front-loaded and the usage conditions immediately after. Every clause 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 one-optional-parameter cache utility with no output schema, purpose and trigger conditions are fully covered. The only omission is whether clearing 'all' affects other active connections or other users, a detail the schema hints at but does not explain.

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

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

The single 'scope' parameter has 100% schema description coverage including an enum and a stated default, so the schema carries the full burden. The description adds no scope semantics of its own; 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 and resource: clearing the e-arveldaja API cache and reference data, which is concrete enough to distinguish it from data-mutating siblings like delete_client or invalidate_journal. It does not explicitly contrast with the nearest sibling, clear_session_log, but the resource named ('cached API and reference data') is unambiguous.

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

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

Gives two concrete trigger conditions: after out-of-band edits in the e-arveldaja web UI, and before reports that must reflect the latest upstream state. This is clear when-to-use guidance, though it names no exclusions or alternative tools for the same need.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds the irreversibility detail ('cannot be undone') and the connection scope, which is modest value, but it does not say what exactly is erased or whether other callers on the connection are affected.

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 and followed by the blast radius. Nothing extraneous or 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 zero-parameter destructive operation with annotations covering the safety profile and no output schema, the description supplies the essentials. A note on the retention/confirmation implications, and reconciling 'audit log' in the description with 'session log' in the name, would close the remaining gap.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the schema already declares an empty object with additionalProperties=false. Baseline of 4 applies; nothing is missing.

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 — 'Clear the audit log' — scoped to 'the current connection', which is more precise than the bare tool name. It does not, however, name its closest siblings (get_session_log, list_audit_logs) to make the read-vs-clear distinction 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 statement of when to clear versus when to keep the log, no prerequisite or confirmation guidance, and no reference to the sibling read tools that an agent would naturally consider first. The destructive warning is a caution, not usage 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, closed-world, so safety is covered. The description adds that the balance is derived from journal postings and that filters are optional, but says nothing about caching behavior (the 'fresh' param hints at caching) or result stability, so it adds only modest context.

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?

It is a single efficient sentence with the core action front-loaded. It is appropriately sized, though slightly thin given the tool's complexity.

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 computation tool with full schema coverage and annotations, the description covers the essentials. However, it omits where the result can be retrieved, whether results are cached, and how it relates to sibling balance tools, leaving some gaps.

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

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

Schema coverage is 100%, so the schema already documents all seven parameters in detail, including date formats, account_id semantics, and dimension filtering. The description merely echoes optional filters (client/dimension/date) without adding syntax or format details, so 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 (Compute) and resource (account balance) plus inputs (journal postings). It distinguishes somewhat from compute_account_dimension_balances by naming the resource 'account', but does not explicitly call out the sibling, so it's clear yet not fully differentiated.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives like compute_account_dimension_balances or compute_trial_balance even though they are close siblings. Usage is only implied by the phrasing 'from journal postings'.

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, so the safety profile is covered. The description adds real behavioral context the annotations cannot: the return grain (one row per dimension plus a total), the inclusion of API INITIAL opening balances, and a cross-tool reconciliation guarantee against compute_account_balance.

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, no filler, with the core purpose and the example front-loaded and the return/reconciliation guarantee second. Every clause carries information an agent cannot get from the schema.

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

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

With no output schema, the description correctly carries the return shape (one row per dimension plus total) and a consistency guarantee, which is what an agent most needs. It leaves open how the default date range behaves when date_from/date_to are omitted, a minor gap for a read-only reporting 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 100%, so account_id, date_from, date_to and fresh are already documented in the schema. The description adds only indirect meaning (the mention of API initial balances hints at the cached API data that 'fresh' refreshes) but gives no date-range semantics of its own. 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 and resource ('break an account's balance down per dimension') and grounds it with a concrete example (1020 Arvelduskontod: LHV, Wise, Lightyear). It also distinguishes itself from the closely related compute_account_balance by declaring that its total matches that tool's output.

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 per-dimension breakdown framing makes the selection context clear versus compute_account_balance, which the description names and reconciles against. It stops short of an explicit 'use X when you need only the total, use this when you need the breakdown' rule, and says nothing about list_account_dimensions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully carried by structured data. The description adds that results are derived from journal postings and how accounts are bucketed, which is modest extra context. It does not disclose anything about caching behavior or report completeness (e.g. whether unconfirmed postings are included).

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 action and output structure front-loaded, and no filler. Slightly more framing could earn a 5, but nothing 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 read-only compute tool with full annotation coverage and a fully described two-parameter schema, the description supplies the essential missing piece: the source data and the account grouping. With no output schema, it would help to note the result's shape or filtering, but the tool is largely 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?

Schema description coverage is 100%, so both 'fresh' and 'date_to' are already documented with formats and defaults. The description adds no parameter-level detail beyond what the schema supplies, making the baseline 3 the correct score.

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 ('Compute balance sheet') and names the input source ('from journal postings'), plus what the output groups (Assets, Liabilities+Equity). This clearly separates it from sibling reports like compute_profit_and_loss or compute_trial_balance. However, it never explicitly names those siblings as alternatives, so it stops short of full differentiation.

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

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

There is no guidance on when to prefer this report over the numerous adjacent compute_* / reconcile_* tools (trial balance, P&L, account balance). The description is purely descriptive of what it computes and gives no context, prerequisites, or exclusions.

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/destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the attribution rule (journal header client) and warns that offsetting postings under other clients are excluded, so the result is not proof of personal debt. It omits the caching behavior implied by the 'fresh' 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?

Two sentences, zero waste, with the core purpose front-loaded and the important interpretation caveat following. Every sentence earns its place.

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

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

For a read-only computation with a fully described schema and no output schema, the definition covers purpose, attribution semantics, and the key limitation. It could still say something about the shape of the returned net position, which the absent output schema leaves 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 100%, so all three parameters are already documented (including the default account list). The phrase 'across selected accounts' loosely maps to account_ids but adds no syntax or format detail, and 'fresh' is not elaborated. 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?

The description gives a specific verb+resource: 'Compute net position against a client across selected accounts.' This is clearly distinguishable from generic siblings like compute_account_balance or compute_receivables_aging. It does not name or contrast with a sibling directly, so it stops short of a 5.

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

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

Usage is only implied — the tool computes a client net position, so an agent can infer when it applies. There is no explicit when-to-use/when-not statement and no alternative tool named (e.g. compute_account_balance for a single account). Adequate but with a clear 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add operational context. It adds the scope restriction to unpaid purchase invoices, but says nothing about currency handling, supplier grouping behavior, or what aging buckets/periods are produced.

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 core action and scope, with no filler or restatement of the name.

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

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

The tool is simple and read-only, but there is no output schema, so the description should have described the shape of the report (aging buckets, per-supplier rows). As written, an agent knows what goes in but not what comes out.

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

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

With 100% schema coverage on the single as_of_date parameter (including the YYYY-MM-DD format and default-today behavior), the schema already carries the parameter semantics. The description's mention of a 'specific cutoff' adds only marginal meaning beyond that, 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 (compute), a specific artifact (payables aging by supplier), and the data source (unpaid purchase invoices). It is clearly distinct from the sibling compute_receivables_aging and from list_purchase_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?

It explains how to get a specific cutoff via as_of_date, which is useful usage guidance, but never says when to reach for this tool versus compute_receivables_aging, month_end_close_checklist, or the raw invoice listers. Usage is implied rather than contrasted.

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 (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds genuinely non-obvious behavioral context: account 9000 and legacy YECL closing journals are excluded from the result. It does not mention that results may be cached (implied only by the 'fresh' parameter) or any permission requirements, leaving some behavioral gaps.

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

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

Two sentences, front-loaded with the core purpose, and the second sentence carries real domain information (exclusions) rather than filler. Nothing is wasted and nothing redundant with the schema is repeated.

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 report tool with no output schema, the description conveys the accounting basis and the exclusion rules, which is the information an agent most needs to interpret results. It stops short of describing the returned structure (line items, hierarchy, totals), which is the one remaining gap.

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

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

Schema description coverage is 100%, so date_from, date_to and fresh are fully documented in the schema; the description only implies that the report is period-scoped, which the schema already states. Baseline 3 is appropriate since the schema does all the parameter 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+resource ('Compute profit and loss statement (kasumiaruanne) for a period') and clarifies the accounting content as revenue minus expenses. It is clearly distinguishable from report siblings like compute_balance_sheet or compute_trial_balance by the resource named, though it never explicitly contrasts itself with 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?

Usage is implied (period-based P&L report) but there is no explicit when-to-use/when-not guidance and no alternatives named among report tools such as compute_balance_sheet or generate_annual_report_data. The scoping rule about excluded journals tells the agent how results are shaped, not when to pick this tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context on the data basis (only unpaid sale invoices, grouped by client), but says nothing about the returned structure (aging buckets, totals) for a report tool with no output schema.

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

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

Two sentences, zero filler, with the core computation front-loaded and the optional parameter addressed second. Every sentence earns its place.

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

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

For a read-only computed report with strong annotations and a fully documented single parameter, the description is nearly sufficient, but it never hints at what an aging report returns (buckets, per-client totals), which is the main remaining gap given no 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 coverage is 100% and the schema already documents as_of_date as YYYY-MM-DD with a default of today. The description's sentence merely restates the cutoff concept without adding format or default behavior beyond what the schema provides, 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 (compute) plus resource (receivables aging), the grouping dimension (by client), and the source data (unpaid sale invoices). This clearly separates it from the sibling compute_payables_aging and from compute_client_debt without needing 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?

Usage is implied by the report type but never stated: no condition for choosing this over compute_client_debt or compute_payables_aging, and no note that only unpaid sale invoices are in scope by design. Adequate but leaves the selection decision to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: the default period is unbounded and future-dated postings will be counted when date_to is omitted (period.to = 'unbounded'), which is exactly the kind of default-behavior disclosure an agent needs.

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

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

Three sentences, front-loaded with the purpose and output shape, then the one non-obvious default. No filler and nothing repeated from the schema.

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

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

With no output schema, the description carries the return-shape burden and does so at a high level ('debit/credit totals and balance for each account'), while covering the key default. Minor gaps remain (e.g. how date_from interacts with date_to, whether results are cached), but nothing essential to calling 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 the baseline is 3. The description goes further by explaining the semantics of omitting date_to (every posting counts, including future-dated ones), which the schema's terse 'Period end (YYYY-MM-DD)' does not convey.

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 resource (compute trial balance), names the source (journal postings) and the output granularity (debit/credit totals and balance per account). That source-and-output framing separates it from siblings such as compute_balance_sheet or compute_account_balance without needing to name 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?

The date_to caveat is effectively usage guidance for the common case (omitting it includes future-dated postings), which is genuinely useful. However, it never says when to pick this report over compute_balance_sheet, compute_profit_and_loss, or compute_account_balance, so the alternative-selection guidance is absent.

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 mutation/safety profile is covered. The description adds genuine context beyond that: the operation is irreversible and the only remedy is a separate invalidate_journal call. It still says nothing about state prerequisites or what happens on success.

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, zero filler, with the irreversible warning and its remedy front-loaded. Nothing redundant with the name or 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?

For a one-parameter confirm tool whose annotations already carry the destructive/non-idempotent profile and with no output schema to explain, the description is nearly sufficient. The gaps are minor: no statement of success behavior or preconditions, and no differentiation from batch_confirm_journals.

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% for the single parameter, so the schema already documents 'id' as an Object ID with constraints. The description only implies that the id refers to a journal entry, a marginal clarification over the schema's generic 'Object ID' label, 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?

The description states a specific verb and resource: 'Confirm/register a journal entry.' An agent can identify the operation immediately. It does not, however, distinguish this singular tool from the sibling batch_confirm_journals, and the dual verb 'confirm/register' slightly blurs whether these are one operation or two.

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

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

It names the reversal path explicitly ('use invalidate_journal to reverse if needed'), which is a real alternative and its selecting condition. It stops short of saying when to confirm versus create/update, or when to prefer batch_confirm_journals for multiple entries.

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 and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: it specifies the invoice is 'locked' (irreversible finalization) and that totals will not be altered, plus the freshness requirement for correction approvals. It still omits what happens on failure or whether a plan_handle must be pre-approved.

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 and its key constraint, then the correction prerequisite. Zero filler, though it is arguably terse enough that no signal about the plan_handle/recalculate_totals interaction survives.

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 destructive, non-idempotent finalization tool with a complex nested payload and no output schema, the description covers the locking semantics and correction gate but leaves the preview-digest lifecycle, plan_handle role, and recalculate_totals behavior unaddressed. Adequate but with clear gaps.

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

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

Schema description coverage is only 25% (just 'Object ID' on id), and the nested approved_correction object has eight required fields documented nowhere. The description partially compensates by tying an 'approved preview' to the approved_correction workflow, but plan_handle and recalculate_totals remain unexplained by either schema or 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 ('Confirm and lock a purchase invoice') and adds a distinguishing constraint ('without changing approved totals') that separates it from update_purchase_invoice. It does not explicitly name sibling tools, but an agent can tell this is the finalization step rather than an edit.

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 second sentence, 'Totals correction requires a fresh approved preview,' implies the prerequisite of running preview_purchase_invoice_totals_correction before confirming a correction, which is genuine routing guidance. However, it never names the preview tool, states when NOT to use this tool (e.g. use update_purchase_invoice for changes), or describes what happens if the digest is stale.

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 and destructiveHint=true, so the safety profile is partly covered. The description adds real value beyond them: it discloses the concrete effect ('Locks the invoice for editing') and reversibility via invalidate_sale_invoice, which tempers the destructive hint into a recoverable state change.

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

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

Three short sentences, zero filler, with the action front-loaded ahead of effect and reversal. Every sentence earns its place.

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

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

For a single-parameter mutation with annotations present and no output schema, the description covers the action, its state effect, and the undo path. It stops short of prerequisites or response behavior, but the essential information for correct invocation is present.

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?

Only one parameter (id), documented at 100% schema coverage, so the schema already carries the semantics. The description adds nothing about the identifier, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('Confirm a sales invoice') that an agent can distinguish from siblings like confirm_journal or confirm_purchase_invoice by resource. It does not explicitly call out those siblings, but the resource specificity carries the differentiation.

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

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

The description names the inverse operation ('Reversible via invalidate_sale_invoice'), which signals the undo path, but gives no explicit when-to-use condition, prerequisites (e.g. invoice must be in draft), or when not to confirm. Usage is implied rather than stated.

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 destructive=true and non-idempotent, and the description adds substantially more: the exact API rejection message, the linked_invoice_client_mismatch refusal rule, the post-confirm re-read and validation against invoice client and both postings, and the fact that bank_account_name is never modified. This is well beyond what 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?

Dense but front-loaded: the core action comes first, followed by conditional rules and error behaviors. Every sentence carries non-redundant information, though the prose is somewhat packed for rapid scanning.

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 destructive, non-idempotent mutation with no output schema and 5 parameters, the description covers the required inputs, the auto-resolution rules, the refusal cases, and the post-confirm verification. An agent has enough to call it correctly and to anticipate the failure modes.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: when clients_id is required, why block_on_duplicate matters (inter-account duplicate detection), and the semantics of reassign_client_to_invoice including that the client is taken from the transaction.

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 ('Confirm a bank transaction') plus the required input ('by providing distribution rows'). It is clearly distinguishable from sibling tools confirm_journal, confirm_purchase_invoice, and confirm_sale_invoice.

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 rich conditional guidance: pass clients_id when there is no clients_id (CAMT imports), clients_id is auto-resolved for invoice distributions, and reassign_client_to_invoice is needed when the payer differs from the linked invoice's client. It does not explicitly name alternative tools to use instead, so it stops 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 declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the description is not the sole safety source. But it adds nothing beyond them: it does not disclose that execute_review_action actually books an owner-expense continuation, nor clarify what 'prepare' versus 'execute' destroy or commit. The one self-describing phrase, 'prepare an approval action', understates the mutating execute action.

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 front-loaded sentence with no padding. It is efficiently sized, though the terseness is part of the completeness gap rather than pure virtue.

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

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

For a complex, mutation-capable tool spanning four actions and eight parameters with no output schema, the description is far too thin. It never explains the workflow-handle/plan-handle lifecycle, the consume-once plan_handle semantics, or the difference between preparing and executing, leaving the detailed schema to carry the entire burden.

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 fully documents the eight parameters, including the action enum and each action's required handle. The description adds no parameter syntax, formats, or inter-parameter dependencies. Per the high-coverage baseline, a 3 is appropriate.

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

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

The description names three sub-actions (continue a workflow response, resolve a review item, prepare an approval action) which clarifies the multi-action nature beyond the bare title. However, it omits the fourth supported action (execute_review_action, which books a prepared continuation), and it does not distinguish this tool from any sibling. It is specific enough to be usable but incomplete.

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 lists what the tool can do but gives no when-to-use guidance: no mention of prerequisites such as needing a workflow_handle, review_item_json, or the plan_handle required by execute_review_action, and no routing against siblings like recommend_workflow or get_operation_result_page. The agent must infer all triggering conditions from the schema.

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 the full safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower, but the description adds nothing beyond them: no auth/permission requirements, no note on whether created accounts are immediately usable, no mention of uniqueness constraints on account_no, and no statement of side effects. This tool is non-idempotent, which is worth flagging and is not stated.

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?

At four words the text is technically concise, but this is under-specification rather than conciseness: there is no front-loaded substance to trim. The single sentence conveys no information beyond the tool name.

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

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

For a non-idempotent mutation tool touching financial master data, the description omits everything relevant: required-field expectations, whether duplicate account numbers are rejected, and what happens on success. The absence of an output schema means the description should carry more, not less.

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% with 5 documented parameters, so the schema does the heavy lifting and a baseline of 3 applies. The description adds no extra meaning about which fields are required or how they interact (e.g., cl_banks_id vs swift_code).

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 is a verbatim restatement of the tool name and title ("Create Bank Account" / "Create a bank account") with no added specificity. It does not distinguish this tool from siblings like update_bank_account, delete_bank_account, or get_bank_account, nor does it indicate what an account creation entails.

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

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

No when-to-use guidance, prerequisites, or alternative tools are named. An agent must infer from the tool name alone that this is the creation path in the bank-account CRUD family, with no explicit routing cues.

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, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds no behavioral context of its own — no mention of duplicate-refusal semantics, the attestation requirement, or how creation differs from the update path — even though the schema does carry some of this.

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 front-loaded sentence with zero filler. It is efficient, though its brevity borders on under-specification for a 14-parameter mutation tool.

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

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

For a 14-parameter create tool with non-trivial constraints (duplicate refusal, foreign-entity attestation, required physical-entity flag) and no output schema, a one-line description is thin. The schema compensates for parameter detail, but the description itself supplies no context an agent would want before invoking a write operation.

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 14 parameters (including allow_duplicate, is_physical_entity, foreign_identity_attested) are fully documented in the schema itself. The description contributes nothing beyond it, 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?

The description states a specific verb and resource ('Create a new client') and clarifies the entity covers both buyer and supplier roles, which helps distinguish it from read/update siblings like get_client or update_client. However, it does not name an alternative sibling or explicitly contrast with 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?

There is no when-to-use guidance: nothing about using update_client for existing records, nothing about duplicate handling, and nothing about prerequisites such as the required is_physical_entity flag. The agent gets no routing information beyond the verb.

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=false, idempotentHint=false, and destructiveHint=false, so the write/safety profile is partly covered. However, the description adds nothing beyond that — it does not say what a series is, whether prefixes must be unique, whether the new series becomes usable immediately, or what side effects creation has. With a lower bar due to annotations, this still only reaches 2.

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?

It is short and front-loaded, but brevity here reflects under-specification rather than economy; the single phrase conveys no information beyond the tool name, so nothing meaningful 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?

This is a mutation tool with five required parameters, no output schema, and no domain explanation of what an invoice series is or how it interacts with invoice numbering. Given the complexity of the operation and the surrounding invoice-series tool family, the description is inadequate.

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

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

Schema description coverage is 100% and all six properties carry descriptions, so the schema carries parameter meaning on its own. The description contributes nothing extra, which is the baseline 3 when structured fields do 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?

"Create an invoice series" merely restates the tool name and title with no added detail about scope, effect, or how it differs from siblings like update_invoice_series or create_sale_invoice. It is a tautology of the structured fields rather than a clarifying purpose statement.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as list_invoice_series or update_invoice_series. The agent must infer entirely from the name that this is the tool for setting up a new numbering series.

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 mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the safety baseline is covered. Beyond that the description adds nothing: it does not say whether the created entry is an unconfirmed draft requiring confirm_journal, whether postings must balance, or whether duplicate detection interacts with document_number/block_on_duplicate.

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 front-loaded sentence with zero filler, which is appropriately terse for a tool whose 7 parameters are fully documented in the schema. It is arguably under-specified rather than over-long, but there is no wasted text.

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 that creates double-entry postings in a workflow that clearly includes confirm_journal, batch_confirm_journals, and invalidate_journal, the description omits the lifecycle context an agent needs to call it correctly. With no output schema, it also says nothing about what identifier or state comes back. The annotations cover only the safety profile, leaving the substantive gaps 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 description coverage is 100%, so every parameter is already documented in the schema with constraints and semantics (account dimensions requirement, base_amount EUR equivalent, duplicate detection). The phrase 'with postings' merely restates the postings parameter, adding no syntax or format detail. Baseline 3 applies 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 and resource ('Create a journal entry') plus the nested content ('with postings'), so an agent knows exactly what it produces. However it offers no differentiation from siblings like update_journal, confirm_journal, or create_transaction, which all operate on overlapping journal/booking concepts.

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 contains no when-to-use guidance, no prerequisites, and no alternatives. It never mentions that confirm_journal exists downstream, nor when an agent should create a journal versus a transaction or a purchase invoice. Nothing routes the caller.

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=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds only that a journal is produced, and omits the consequential behavioral fact that the call is non-idempotent (repeated calls create duplicate journals) and that it books a liability to the owner.

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 front-loaded sentence with no filler, and the verb appears first. It is efficient, though extremely terse for a 12-parameter booking operation.

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?

Annotations carry the mutation safety profile and the schema fully documents parameters, with no output schema needed for return values. What is still missing is the double-entry behavior (expense account debited, payable-to-owner credited) and the non-idempotency caveat an agent should know before calling.

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 12 parameters including vat_rate decimals, defaults (1510, 2110), and vat_deduction_mode are already documented. The description adds no parameter-level 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 (Create) and resource (a journal for a business expense paid personally by the owner), and the owner-reimbursement framing separates it from the generic create_journal sibling. It does not explicitly name an alternative, but the purpose is unambiguous.

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

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

The description gives no when-to-use guidance, no prerequisites (e.g. the owner client must already exist), and never contrasts this with create_journal or create_transaction. The agent must infer the routing condition entirely.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent) but the description does not address non-idempotency (repeat calls create duplicates) or what happens on a conflicting code. Its one added signal — that account IDs are read-only and should be replaced by article IDs — partly restates the schema's own field notes.

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 create action before the caveats. The second sentence is dense and slightly ambiguous ('Account IDs are read-only' could be misread as an authorization statement rather than an ignored-input warning), but there is no 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?

For an 11-parameter mutation with no output schema, the description covers the required identity fields and the article-ID trap but says nothing about unit, sales_price, dimension IDs, validation failures, or duplicate-code behavior. Adequate minimum, with clear gaps.

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

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

Schema description coverage is 100%, so every one of the 11 parameters is already documented. The description reinforces the sale/purchase article distinction but adds no syntax, format, or constraint detail beyond the schema's own field text, which is the expected baseline.

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 ('Create a product/service') plus the article linkage that defines the record. It is implicitly distinguishable from update_product/delete_product via the verb, but the description does not explicitly contrast itself with those 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?

Gives useful operational guidance on where to source IDs ('use article IDs from list_sale_articles/list_purchase_articles') and warns which fields to avoid. However it never says when to choose create_product over update_product, or when a product should be created versus handled through an invoice flow.

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 write. The description adds genuinely useful context beyond that: the result is a DRAFT, and confirm_purchase_invoice will fail without exact vat_price/gross_price. It still says nothing about permissions, auth, or side effects like duplicate drafts, 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?

Two compact sentences, front-loaded with the core action before the contract details. Dense but every clause carries meaning; no filler or restatement of 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?

For an 18-parameter invoice-creation tool with no output schema, the description covers the critical numeric and currency contract but omits what the call returns (e.g., the new invoice ID) and how errors beyond currency/VAT manifest. Adequate given the rich schema and annotations, but not 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 coverage is 100%, so the schema already documents all 18 parameters, and much of the description (currency_rate convention, base_* derivation) duplicates schema text verbatim. The one marginal addition is that base_* "may lock actual EUR settlement", which is not in the schema, but the rest is largely redundant.

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 ("Create a draft purchase invoice") and signals the draft state, which meaningfully separates it from confirm_purchase_invoice and create_purchase_invoice_from_pdf. It does not name a sibling explicitly, so the differentiation is implied rather than spelled out.

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 a "direct-call contract" with prerequisites (exact vat_price/gross_price, currency requirements), which is useful setup context. However, it never states when to prefer this tool over create_purchase_invoice_from_pdf or when to use confirm_purchase_invoice instead, so alternative routing is only implied.

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

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

With annotations covering the safety profile (readOnly=false, destructive=false), the description adds real behavioral context: it creates a *draft*, it attaches/keeps the source file, and base_* values 'may lock actual EUR settlement'. It also warns against recalculating prices. It omits duplicate-handling behavior (block_on_duplicate / allow_duplicate_invoice_number), which stays in the schema.

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

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

Two compact sentences, front-loaded with the action and then the contract rules. No filler, no redundancy with 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?

For a 23-parameter mutation tool with no output schema, the description covers the highest-risk items: price exactness, non-EUR rate requirements, and the draft/attachment nature. Remaining gaps (duplicate policy, confirmation-plan flow) are documented in the schema, so the definition is nearly sufficient.

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 23 parameters, setting the baseline at 3. The description reinforces the exactness rules for vat_price/gross_price and the currency_rate convention, but these are largely restated from the schema; it adds only marginal meaning, such as base_* locking settlement.

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 ('Create a draft purchase invoice') plus the distinguishing behavior ('attach the source file'), and the phrase 'from extracted document data' frames the upstream extraction step. It does not explicitly contrast itself with the sibling create_purchase_invoice, so an agent must infer the difference.

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 'Direct-call contract' sentence gives concrete rules for when/how to supply prices and currency_rate, and source_sha256 implies this runs after extract_pdf_invoice. However, it never states when to prefer this tool over create_purchase_invoice or that extraction must precede it, leaving the routing choice implicit.

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-idempotent, destructive write, so the safety profile is covered. The description adds two behavioral facts not present in the schema: created invoices land in DRAFT state and invoice numbers are auto-assigned. It does not explain why the operation is flagged destructive or whether repeated calls duplicate data, leaving a small gap.

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 core behavior is front-loaded and the preview caveat 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?

For a six-parameter mutation tool with a fully documented schema and annotations covering the safety profile, the description supplies the missing result-state context (DRAFT) and numbering behavior. Only the rationale for the destructive flag and duplicate-run behavior are left 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 description coverage is 100%, so all six parameters, including the dry_run default and invoice_ids format, are already documented in the schema. The description repeats the dry_run behavior without adding syntax or edge-case meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb (clone), the source resource (previous-month sale invoices), and the resulting artifact (DRAFT recurring invoices), so the operation and its output state are unambiguous. It does not name the near siblings create_sale_invoice or list_sale_invoices to distinguish itself, 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?

Mentions that dry_run=true previews, which is a genuine usage hint for a mutation tool. However, it gives no guidance on when to prefer this over create_sale_invoice or batch flows, and no exclusions or prerequisites; usage is implied rather than stated.

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 this is a non-readOnly, non-destructive, non-idempotent write operation, so the safety profile is partly conveyed structurally. However the description adds nothing on top: it does not say what gets created, whether the invoice starts as a draft, whether confirmation is required, or what side effects on journals/ledgers occur. For a mutating financial document tool, this is a substantial gap.

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 sentence is grammatically clean with zero waste, but this is under-specification masquerading as brevity rather than genuine conciseness. A single content-free line does not earn its place as the tool's only guidance.

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 12-parameter, 6-required mutation tool with nested item objects, no output schema, and a rich confirm/send/validate sibling ecosystem, the description is inadequate. The schema covers field syntax, but nothing explains the creation workflow, resulting state, or next steps, leaving the agent to reconstruct the process from sibling names alone.

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

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

Schema description coverage is 100%, including a detailed note on item structure, dimension requirements, and discount derivation, so the schema fully documents all 12 parameters. The description contributes no parameter meaning whatsoever, which makes the baseline 3 appropriate rather than higher.

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 'Create a sales invoice' merely restates the tool name and title in sentence form, with no distinguishing detail about scope, downstream effects, or the invoice lifecycle. It technically names a verb and resource, but an agent gains nothing beyond what the name already tells it, especially against siblings like update_sale_invoice or create_recurring_sale_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?

There is no guidance on when to use this versus create_purchase_invoice, update_sale_invoice, create_recurring_sale_invoices, or the confirm/send siblings. No prerequisites, no mention that a created invoice may need subsequent confirmation or sending. The agent must infer everything from the name.

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 disclose readOnlyHint=false, idempotentHint=false, openWorldHint=false, and destructiveHint=false, so the safety profile is partly covered. However, the description adds no context about side effects, permission requirements, duplicate handling, confirmation state, or what is created, which is a notable gap for a mutation tool.

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

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

The description is a single front-loaded sentence with no wasted words. It is maximally concise, and any missing detail is a completeness issue rather than 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 10-parameter mutation tool with no output schema, the description is too thin. It omits usage context, side effects, authentication requirements, and how duplicate handling or transaction confirmation should be understood, leaving the agent to rely almost entirely on the schema and annotations.

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 10 parameters, including the enum for transaction type and duplicate blocking behavior, are documented in the schema. The description adds no parameter meaning beyond what the schema already provides, making the baseline score of 3 appropriate.

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

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

States a specific verb and resource: 'Create' and 'bank transaction'. This clearly identifies the operation, but it does not explicitly distinguish itself from sibling tools such as create_journal or create_sale_invoice beyond the resource noun.

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

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

No guidance is given on when to use this tool versus alternatives. It does not mention prerequisites, when it should be preferred over create_journal, or when another import/booking tool would be more 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 cover readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the bar is lower. The description adds valuable reversibility context by stating the client can be restored with reactivate_client, though it does not describe the full operational impact of deactivation.

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

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

A single sentence with no wasted words, and the core action is front-loaded immediately. The restoration hint follows naturally without disrupting readability.

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

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

For a simple one-parameter reversible mutation with rich annotations and no output schema, the description provides enough context to select and invoke the tool correctly. It only omits what deactivation actually blocks or changes about the client.

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 schema has 100% description coverage and documents the single id parameter as an object ID. The description adds no further parameter meaning, so the schema does the heavy lifting and the baseline score of 3 applies.

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

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

States a specific verb and resource: deactivate a client. The parenthetical points to reactivate_client for restoration, which implies reversibility, but the description does not explicitly distinguish this from delete_client or update_client.

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 by the tool name and the restorative alternative is named, but there is no explicit guidance on when to deactivate instead of delete or update a client. The agent must infer the appropriate context.

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

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

Annotations already declare destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds value the annotations do not carry: the state change is reversible via reactivate_product. It does not say what deactivation blocks (e.g., use in new documents) or whether related data is affected.

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?

One sentence plus a parenthetical, with the action front-loaded and the reversibility note attached directly to it. Zero wasted words.

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 state-change tool with annotations covering idempotency and destructiveness, the description supplies action, undo path, and sibling routing, which is enough for correct invocation. It would be complete at 5 with a note on the effect of deactivation on dependent records.

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% with a single documented 'id' (Object ID) parameter, so the schema does the heavy lifting. The description adds no parameter-level detail such as ID format or source of the ID.

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

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

States a specific verb (deactivate) and resource (product), and names the counterpart reactivate_product, which separates it from delete_product for an agent reading the sibling list. It stops short of explicitly contrasting with delete_product, so the distinction is inferable 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 parenthetical points to reactivate_product as the undo path, which is implicit usage guidance for reversibility. There is no statement of when to prefer this over delete_product or update_product, so the when-not condition 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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds a genuinely new behavioral fact beyond the annotations: the referential-integrity failure condition when transactions exist. It does not state whether the delete is permanent/soft, but the destructive annotation carries that.

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, no filler, with the core action stated first and the failure condition immediately after. Every sentence earns its place.

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

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

For a single-parameter destructive mutation with full annotation coverage and no output schema, the description covers purpose and the key operational constraint. The only untold detail is whether the deletion is reversible or a soft delete, which is minor given the destructiveHint.

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?

Only one parameter, and schema description coverage is 100% ('Bank account ID', required, positive integer). The description adds nothing about the id beyond what the schema already documents, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Delete a company bank account'), which is unambiguous against the CRUD siblings list_bank_accounts, get_bank_account, create_bank_account and update_bank_account. It stops short of explicitly naming an alternative, so it is clear but not fully sibling-differentiating.

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 supplies one real precondition — deletion fails when transactions reference the account — which is useful guidance for choosing when to call it. However, it gives no explicit when-not guidance and no alternative route, so usage is only implied rather than 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 already declare destructiveHint=true and non-idempotent, so the irrevocability bar is partly covered. The description adds the referential-integrity failure mode — the call will error rather than cascade when accounting records reference the client — which is behavior annotations cannot express. It does not say what the response looks like or whether it can be undone beyond "permanently".

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, no filler, and the destructive nature is front-loaded before the failure condition and the alternative. Every clause carries information the agent needs to act correctly.

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-param destructive mutation with annotations covering the safety profile and no output schema, the description covers intent, failure semantics, and the escape hatch. Nothing required to call 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?

There is a single parameter with 100% schema description coverage, so the schema fully documents it. The description adds no syntax, format, or selection guidance for the id beyond what the schema provides; 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 and resource ("Permanently delete a client") and immediately distinguishes itself from the sibling deactivate_client by contrasting permanent removal with hiding an in-use record. An agent can route between delete_client and deactivate_client 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 states when-not to use it (client referenced by invoices, journals, transactions, or other accounting records), names the alternative tool to use instead, and names the intended use case (mistakenly-created master data with no history). Both the trigger and the exclusion are given.

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, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds one useful scoping fact — only the attached document goes, not the invoice/journal/transaction — but says nothing about irreversibility, confirmation requirements, or behavior when no document is attached.

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

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

A single sentence that front-loads the verb and states the scope immediately, with no filler or hedging. Nothing could be cut without losing meaning.

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 destructive operation with full schema coverage and annotations carrying the safety profile, the definition is workable but thin. It omits what the caller should expect on success/failure and any preconditions, which matters more here because there is no output schema or usage guidance 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?

Schema description coverage is 100% and both parameters (id, entity_type) are documented in the schema, including the four-value enum. The description's enumeration of entity types restates rather than extends the schema, so the baseline of 3 applies.

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

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

Specific verb ("Delete") plus a precisely scoped resource ("the source document attached to a purchase invoice, sale invoice, journal, or bank transaction"). This distinguishes it cleanly from siblings that delete the parent records themselves (delete_sale_invoice, delete_transaction) and from attach_document/get_document, without needing to name 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?

There is no when-to-use, when-not-to-use, or alternative-selection guidance. The description never says to reach for this tool rather than get_document, find_missing_documents, or the parent-record delete tools, and it states no prerequisites (e.g., whether the document must exist).

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 and readOnlyHint=false, so the safety profile is covered. The description adds a genuinely non-redundant behavioral fact: the operation fails when the series is in use, which is a failure mode the annotations do not 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?

Two short sentences with zero filler; the core action is front-loaded and the failure condition follows immediately. Every clause 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 one-parameter destructive delete with no output schema, the description covers the action and the key failure condition, and annotations carry the safety semantics. It stops short of noting reversibility or side effects on invoices using the series, but is largely 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?

There is a single required parameter (id) with 100% schema description coverage, so the schema fully documents it. The description adds no syntax, format, or lookup guidance beyond 'Invoice series ID', so the baseline of 3 applies.

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

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

States a specific verb (Delete) and resource (invoice numbering series), which cleanly separates it from the list_/get_/create_/update_invoice_series siblings. It does not explicitly name those siblings, but the resource is unambiguous.

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

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

The description implies when the call is valid by stating it 'fails if the series is already in use', which gives a usable precondition. However, it offers no explicit guidance on when to delete versus update/keep a series, and names no alternative tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond the name: it does not say whether only draft journals can be deleted, whether the deletion is permanent, or whether related transactions block it.

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

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

A single short sentence with no filler, front-loaded on the verb. It is efficiently stated, though its brevity reflects under-specification rather than disciplined concision.

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 destructive mutation with no output schema in a crowded journal tool family, the description should at minimum distinguish itself from invalidate_journal and state any precondition (e.g., draft-only). It omits both, leaving the agent to guess at the correct lifecycle operation.

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% — the single id parameter is documented as "Object ID" with type and range constraints. The description adds no meaning beyond the schema, so the baseline of 3 applies.

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

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

The description gives a clear verb+resource ("Delete a journal entry"), so an agent knows what it does in isolation. However, with siblings like invalidate_journal, update_journal, and create_journal in the same family, it draws no boundary between hard-delete and the other journal lifecycle operations.

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

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

There is no when-to-use guidance and no mention of alternatives. The critical ambiguity — delete vs. invalidate_journal (a likely soft-delete/void path) — is left entirely 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?

Goes well beyond the destructiveHint annotation by disclosing the concrete failure condition (referential integrity with invoices/accounting records), the permanence, and the recommended alternative. Annotation already flags destructiveness; the description adds the operational constraint 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?

Two sentences, front-loaded with the permanence warning, then the failure condition and alternative, then the intended use case. Zero 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 single-parameter destructive mutation with no output schema and destructiveHint=true, the description supplies exactly the missing context: irreversibility, failure mode, alternative path, and scope of intended use. Nothing an agent needs 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% and the single 'id' parameter is documented as 'Object ID' with constraints in the schema. The description adds no meaning beyond the schema, so baseline 3 applies (0-param/simple-case rules push to 3-4; described param already covered).

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?

Specific verb ('delete') + resource ('product/service') with an explicit 'Permanently' qualifier that distinguishes it from the soft-delete sibling deactivate_product. An agent can tell exactly what this does and how it differs from nearby tools.

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

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

Explicit when-not condition: 'Fails if the product is referenced by invoices... use deactivate_product to hide an in-use product instead.' Also states the intended use case ('mistakenly-created master data with no history'). Alternative tool is named with the selecting condition.

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 by structured data. The description adds nothing beyond that: it does not say whether deletion is permanent, whether confirmation is required, or what happens to linked documents, so it fails to earn credit beyond 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?

The description is a single four-word phrase with no waste, but this is under-specification rather than conciseness. There is no structure to front-load and nothing that earns its place beyond echoing 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?

For an irreversible destructive operation on an accounting document, the description omits confirmation semantics, preconditions, and downstream effects. No output schema exists and the annotations only flag destructiveness, so the description should carry more of this burden than it does.

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 a single required parameter (id) and schema description coverage is 100%, so the schema fully documents it. With no parameter information in the description, the baseline of 3 applies.

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

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

The description repeats the tool title verbatim ('Delete a purchase invoice') and says nothing the name does not already convey. It does not distinguish this tool from the many other delete_* siblings (delete_sale_invoice, delete_journal, delete_transaction), so an agent gains no discriminating information.

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

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

There is no when-to-use guidance, no prerequisites (e.g., must the invoice be unconfirmed or uninvalidated first?), and no mention of alternatives such as invalidate_purchase_invoice. The agent must infer all of this from the sibling list.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say the deletion is irreversible, whether documents/numbering are released, or what happens if the invoice is confirmed. For a destructive, non-idempotent mutation with zero description-side context, this is a notable gap.

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

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

A single short sentence with no wasted words, but its brevity reflects under-specification rather than disciplined conciseness. Nothing is front-loaded because nothing beyond the obvious is stated.

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 destructive, non-idempotent delete with no output schema, the description should at minimum flag irreversibility and the alternative (invalidate) or prerequisite state. None of that context is present, so an agent cannot confidently choose this tool over its siblings.

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?

Only one parameter (id) exists and schema description coverage is 100%, so the schema fully documents the input. Per the baseline rule for high coverage, a 3 applies; the description contributes no additional meaning about the identifier.

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

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

The description states a concrete verb and resource (delete a sales invoice), so the basic action is unambiguous. However, it is a near-verbatim restatement of the tool title and offers no differentiation from closely related siblings such as invalidate_sale_invoice, delete_purchase_invoice, or batch_delete_transactions.

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

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

No guidance on when to use this tool versus invalidate_sale_invoice or confirm_sale_invoice, and no stated prerequisites (e.g., whether only draft/unconfirmed invoices can be deleted). The agent must infer the workflow from sibling names alone.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds nothing on top of that — no note about permanence, whether the delete cascades to related journal entries, or what happens on a referenced transaction.

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 words, front-loaded, zero waste — but the brevity reflects under-specification rather than disciplined conciseness. It is not padded, yet it earns its place only barely.

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 destructive, non-idempotent mutation the description says nothing about irreversibility, permission requirements, or the batch alternative. Annotations cover the safety hints, but a one-line description leaves real gaps for a delete operation.

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?

A single 'id' parameter with 100% schema description coverage, so the schema does the documenting. The description adds no meaning beyond the field name, which is the baseline 3 case when the schema carries the load.

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

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

'Delete a transaction' simply restates the tool name and title with a verb+object that adds no distinguishing detail. Among siblings like batch_delete_transactions, invalidate_transaction, and the many resource-specific delete_* tools, an agent gets no help telling this one apart.

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

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

No when-to-use guidance, no prerequisites, and no mention of the obvious alternative (batch_delete_transactions) or the softer invalidate_transaction path. The agent must infer everything from the name alone.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds no behavioral context beyond the purpose line: it doesn't say what a result looks like (boolean vs. matched invoices), whether all keys must be supplied, or how partial matches are treated.

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 front-loaded sentence with no filler. It is arguably under-specified rather than wordy, but as a structure/conciseness judgment it is clean and efficient.

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 is the only place the return value could be described, yet it is silent on output shape. Combined with 6 optional parameters and no stated interaction between the date-range filters and the ±7-day window, it is minimum-viable rather than complete.

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

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

Schema description coverage is 100%, so every parameter is already documented, including the non-obvious 'invoice_date limits amount matches to ±7 days' and the date_from/date_to range. The description merely echoes the match keys and adds no semantics beyond the schema, so 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 (check/detect duplicates) and resource (purchase invoices), plus the four matching keys it compares. It does not distinguish itself from near-neighbors like validate_invoice_data or cleanup_camt_possible_duplicate, but the purpose is unambiguous.

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

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

The intent (verify an incoming invoice is not a duplicate before booking) is implied but never stated, and no alternatives or exclusions are named. Nothing tells the agent when this is preferable to validate_invoice_data or a plain list_purchase_invoices search.

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