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

The description discloses key behavioral details beyond the minimal annotations: decimal string amounts, line total calculation, tax behavior, and the unposted-document constraint. This materially helps the agent predict side effects and constraints.

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 well-organized with a clear opening, essential constraints, and a structured Args list. Despite covering 11 parameters, every sentence adds useful information without redundant restatement of 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?

For a mutation tool with 11 parameters, the description covers required inputs, optional inputs, edge cases, and prerequisite conditions. An output schema exists, so the lack of return-value detail is not a 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?

With only 9% schema coverage, the description carries the full parameter burden and succeeds: every parameter is described, and high-value semantics are added, such as account direction by document type and party_type disambiguation for credit notes.

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 action ('Add a line item') and a specific resource (customer invoice, vendor bill, employee voucher, credit note). This clearly identifies what the tool does and differentiates it from siblings like create_document or create_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?

It explicitly states when the tool applies ('Only unposted documents accept entries') and gives a prerequisite action (unpost_document first for posted documents). It does not explicitly contrast with alternatives like create_document, but the usage context is clear.

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?

Beyond the annotations, the description discloses meaningful behavioral traits: the transaction is non-cash, it transfers credit balance between lots, both documents must be posted and share owner/currency/account, and the response notes divergence when the target differs from the provenance document. It also explains the amount default behavior and date default, which directly informs call behavior.

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 front-loaded with the core operation, then provides context, an explicit alternative, and well-organized parameter documentation. Every sentence contributes either behavioral context, usage guidance, or parameter semantics. The Args block is formatted clearly and maps directly to the input schema.

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

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

Given the tool has 5 parameters, no schema descriptions, and an output schema exists, this description covers everything an agent needs to call the tool correctly: operation semantics, constraints, defaults, ownership requirements, and when to choose an alternative. The only missing details would be error cases, but the detailed constraints and output schema sufficiently cover the core contract.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it succeeds. Every parameter is explained with constraints, defaults, and format: credit_note_id must be posted, applies_to_invoice_id must be posted and share owner/currency/account, amount is a decimal string defaulting to max possible, apply_date is ISO defaulting to today, and owner_type disambiguates ID collisions.

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

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

The description opens with a precise verb and resource: 'Net a posted credit note against a posted invoice or bill from the same owner.' It immediately clarifies that no cash moves, and the mechanism (credit balance transfers between lots on the same A/R or A/P account) distinguishes it from payment-related siblings like pay_document.

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

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

The description explicitly states when this tool is the right choice—'the most common credit-note settlement path'—and provides a direct exclusion: 'Use pay_document instead when the credit note will be settled by sending or receiving cash.' This gives an agent clear decision criteria without needing to inspect other tools.

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

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

Annotations mark this as destructiveHint=true and idempotentHint=true, so the description must clarify the destructive effect, but it only says 'link' and 'for cost basis tracking.' It does not explain whether an existing split-lot assignment is overwritten or whether the operation has consequences beyond linking. This is a meaningful gap for a destructive operation.

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

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

The description is well-structured with a one-sentence purpose, usage guidance, args list, and workflow. It is slightly longer than strictly necessary due to the example workflow, but the workflow concretely demonstrates how the tool fits into a multi-step process, so the length is justified.

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 tool with an output schema, the description provides the workflow, param sources, and when to use it. It is practically complete for correct invocation. The main missing context is the destructive behavior already penalized under behavioral transparency, but for agent invocation the description is 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?

The schema already covers both parameter formats with 100% coverage, so the baseline is 3. The description adds useful context beyond the schema, especially for split_guid: 'GUID of the split (from transaction's investment account)' and the workflow showing how the split_guid and lot_guid are produced.

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: 'Assign a transaction split to a lot.' It clearly identifies the object being operated on (a transaction split) and the target (a lot), and the rest of the description explains how this fits into the lot-assignment workflow, distinguishing it from lot creation and transaction creation 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?

Explicitly says 'Use after creating a buy/sell transaction to link the investment account split to its lot for cost basis tracking' and reinforces this with a numbered workflow. It gives clear timing and context, though it does not explicitly list alternative tools or exclusionary 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?

Beyond the readOnlyHint annotation, it discloses meaningful behavior: the balance sheet equation holds by construction and non-zero unrealized P&L is shown as a synthetic equity row. It also specifies the default date behavior and how it aligns with get_book_summary, giving an agent a clear model of what the tool will do.

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 tightly structured: purpose first, then output behavior, then parameter details. Each sentence adds distinct value, and the parameter explanation is placed in a clearly labeled Args section without unnecessary fluff.

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 one optional parameter, read-only annotations, and an output schema present, the description covers all essential invocation context: date format, defaulting behavior, cross-tool consistency, and the synthetic row caveat. No critical information an agent would need to call this tool correctly is missing.

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

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

The schema provides no description coverage (0%), but the description fully compensates for the single as_of_date parameter: ISO format, default of today, alignment with get_book_summary's implicit cutoff, and explicit use for historical snapshots. This gives an agent everything needed to use the parameter correctly.

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

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

The description opens with a specific verb ('Generate') and resource ('balance sheet'), plus a date scope. The content details — assets, liabilities, equity, account breakdowns, and A = L + E — clearly distinguish this from report siblings like net_worth and cash_flow.

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 makes the primary use case obvious and provides concrete date-handling guidance, including alignment with get_book_summary's implicit cutoff for cross-tool comparisons. It does not explicitly state when not to use it or name alternative report tools, but the context is clear enough.

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 convey readOnlyHint=true, so safety is established. The description adds meaningful behavioral detail: the two calculation paths, defaulting shares to all remaining, and defaulting sale_price to latest price. This goes beyond what annotations provide and is consistent with them.

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 compact and efficiently structured: purpose, mode logic, then parameter details. No sentence is wasted, and the most important behavioral distinction 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 an output schema present, return-value documentation is unnecessary. The description covers the two usage modes and defaults adequately. The only minor gap is ambiguity about partial combinations, such as providing sale_price without shares, but overall the agent has enough to call the tool correctly.

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

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

Schema coverage is only 33%, and the description compensates by documenting all three parameters, including defaults for shares and sale_price. This gives the agent critical meaning that the schema lacks for two parameters, though it stops short of specifying units or edge-case behavior.

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

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

The description opens with a specific verb and resource: 'Calculate potential or actual capital gain for a lot.' This clearly distinguishes the tool from siblings like get_lot or get_latest_price, which retrieve data but do not compute gain.

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 provides explicit mode-based guidance: if both shares and sale_price are provided, compute hypothetical gain; otherwise, use the lot's current state and latest price. This is clear usage context, though it does not name sibling alternatives or state when not to use the tool.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavioral details: default account scope, the filtering of internal transfers, the semantic difference between net cash flow and gross movement, and the effect of include_transfers. It also describes the group_by output shape. This substantially exceeds what annotations alone convey and contains no contradiction.

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 front-loaded with purpose and scope, then organized into clear behavioral notes and an Args block. Every sentence adds information—scope exclusions, transfer filtering rationale, and parameter details—without filler or repetition. It is appropriately detailed for a tool with nuanced behavior.

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 tool with five parameters, two required, and meaningful default-scope behavior, the description covers the essential decision points: what counts as cash flow, what is excluded, how to include transfers, and how grouping changes output. The presence of an output schema means return-value documentation is not required here. An agent has enough context to call 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 description coverage is 0%, so all parameter meaning must come from the description. It thoroughly explains every parameter: date formats, account default behavior, include_transfers semantics for both values, and group_by allowed values plus output format. This fully compensates for the bare schema.

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

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

The description opens with a specific verb and resource: 'Calculate cash flow (inflows and outflows) for a period.' It clearly distinguishes itself from siblings by defining the default scope as BANK and CASH accounts and explicitly contrasting with balance_sheet for credit-card and investment movements. This leaves no ambiguity about what the tool computes.

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 explicit when-to-use guidance and names an alternative: credit-card and investment movements are not cash flow and should use balance_sheet. It also clarifies when to pass include_transfers=true, such as when reconciling against a bank statement, and explains the default filtering philosophy. This is model usage 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?

The annotations already provide destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds useful behavioral context beyond those: lots normally auto-close via assigned splits, and this tool exists for when that doesn't happen. It explains the intended edge-case role without contradicting 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 short and well-structured: a one-line action, explicit use cases, the single parameter, and a clarifying note. Every sentence contributes useful information without repetition or filler.

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

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

This is a low-complexity tool with one fully documented parameter, an output schema, and informative annotations. The description covers when to use it, why it may be needed, and what input is expected, which is complete enough 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?

The schema already describes guid as 'Lot GUID (32-char hex or 8+ char prefix)' with 100% coverage. The description's 'Lot GUID (or 8+ char prefix)' adds no meaningful semantic value 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 opens with the specific verb and resource: 'Mark a lot as closed.' It goes beyond the name by clarifying the tool is for manual cleanup, which distinguishes it from related lot operations like assign_split_to_lot or calculate_lot_gain.

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

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

It explicitly says 'Use when a lot is fully sold but wasn't automatically marked closed, or to manually close a lot with zero shares.' It also explains that lots close automatically at zero quantity, so the agent knows this is a fallback/manual tool rather than a routine one.

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?

Given that annotations only declare readOnlyHint=false, destructiveHint=false, etc., the description adds valuable behavioral detail: placeholder accounts are container-only, commodity defaults to the book's currency, commodity_namespace defaults to CURRENCY, and notes have a 4096-byte limit. These are beyond what the schema or annotations provide, and there is no contradiction with 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 detailed but every sentence earns its place. It leads with the core purpose, then follows a clear Arg list that maps directly to the schema. The formatting is consistent and scannable. Slightly long, but no redundancy or filler.

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

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

Given the tool has 8 parameters and an output schema is present (so return format doesn't need description), the description covers all semantics needed to call the tool correctly. It explains the account type enum, parent ref formats, commodity namespace rules, placeholder behavior, and note limits. Nothing critical is missing for an agent to invoke this tool successfully.

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

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

With 0% schema description coverage, the description fully compensates by explaining every parameter: name, account_type with an explicit list of allowed values, parent with multiple accepted formats, placeholder behavior, commodity, commodity_namespace, and notes length. This is exactly what an agent needs to fill in valid arguments without relying on the schema's bare type definitions.

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 exactly what the tool does: 'Create a new account in the chart of accounts.' This is a specific verb and resource, and it naturally distinguishes from sibling tools like list_accounts, update_account, and delete_account. No ambiguity about the action.

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 provides clear context for when to use it (creating a new account) and includes useful guidance like 'Omit parent for top-level' and that commodity_namespace is 'Required with non-currency commodities.' It doesn't explicitly name alternatives, but the purpose is unambiguous given the sibling set, and the parameter guidance covers key usage decisions.

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 description adds rich behavioral detail: SQLite online backup API, concurrent safety, integrity_check, delete-and-raise on failure, and retention semantics. However, annotations declare readOnlyHint=true while the description describes creating backup files and deleting bad backups, which is a direct annotation contradiction.

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?

Though multi-paragraph, every sentence earns its place: safety, failure handling, retention, restore workflow, and parameter semantics. The core action is front-loaded in the first sentence.

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

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

For a single-parameter backup tool with an output schema, the description covers concurrency safety, verification, failure cleanup, retention, restore instructions, and response contents. Nothing needed to call or interpret the tool is missing.

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

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

Schema coverage is 0% and the schema only names the field as 'Label'. The description fully compensates by explaining that label is optional, free-text, sanitized to [A-Za-z0-9_-], appended to the filename, and provides concrete examples.

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

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

States a specific verb and resource: 'Create an on-demand backup of the GnuCash book.' This is immediately distinguishable from all siblings, none of which perform backup creation.

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 is clear for on-demand backups, and the description explicitly warns that no tool can list or delete backups and that restore is a human-run filesystem operation. This prevents agents from searching for nonexistent sibling capabilities, though it does not state formal 'use this when' 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 indicate readOnlyHint=false and idempotentHint=false, and the description's 'Create' aligns with a mutating, non-idempotent operation. However, the description adds no beyond-annotation behavioral context such as duplicate handling, validation rules, or side effects.

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 well-structured: a one-sentence purpose followed by a compact Args list. Every line adds value by explaining or exemplifying a parameter, with no filler or repeated schema boilerplate.

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

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

All five parameters are fully explained, defaults are specified, and an output schema is present so return-value documentation is unnecessary. The main gap is the lack of broader context about when to create a billing term or how it relates to sibling tools like list_billterms, but the invocation details are complete enough.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It provides meaningful semantics for all five parameters, including examples ('Net 30'), default behavior, and purpose of discount fields. This goes well beyond the bare schema titles.

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 billing term.' The 'Net 30' example clarifies what a billing term is, and the resource name distinguishes it from sibling tools like create_budget or create_taxtable. There is no ambiguity about the operation.

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, such as list_billterms to check existing terms. The one-line purpose implies its use case, but there are no explicit conditions, 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 are all false, so the description carries the burden of behavioral disclosure. It discloses a key behavioral detail: the `year` parameter is ignored when `start_date` is provided, and `start_date` falls back to January 1 of `year` when omitted. This is beyond simple parameter semantics and reveals interaction behavior. However, it does not describe side effects (e.g., whether an existing budget with the same name is overwritten), error handling, or any prerequisites. The description adds some value but could be more transparent about the mutation's full implications.

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 well-organized docstring with a clear one-line summary and a bulleted Args list. Every sentence adds value—there is no filler. The most important behavioral note (year vs start_date) is placed early in the parameter list, and the format is immediately scannable. It is appropriately sized for a tool with six parameters and does not restate schema basics.

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 description fully covers all six parameters with defaults, interdependencies, and usage examples. An output schema exists (as indicated) to handle return values, so the description does not need to explain the response. It is complete enough for an agent to confidently construct a valid call, including handling edge cases like historical budgets and mid-year starts. There are no critical gaps in context.

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

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

The description adds substantial meaning to every parameter beyond the bare schema. It explains the purpose of `name` with an example, the default behavior of `year` and its dependency on `start_date`, the default and options for `period_type`, the use of `num_periods` with an example, and the historical use case for `start_date`. This goes well beyond the type/default information in the schema and significantly improves an agent's ability to select correct values.

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

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

The description opens with the explicit statement 'Create a new budget.' This pairs a specific verb ('create') with a clear resource ('budget'), and it is immediately distinct from sibling tools like list_budgets, get_budget, and delete_budget. The purpose is unambiguous and gives the agent no reason to confuse it with related budget-management 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?

The description does not explicitly name alternatives or state when *not* to use this tool, but it provides strong contextual guidance for the optional `start_date` parameter, explaining that it is used for historical budgets or mid-year starts. This implicitly tells the agent when to set that parameter, and the overall purpose is clear enough that an agent can infer appropriate usage relative to sibling tools. No exclusions are given, but the core usage context is solid.

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 all annotations set to false, the description confirms this is a mutation ('Create a new commodity'). It adds useful constraints such as 'Unique within namespace' and explains the fraction and namespace semantics. However, it does not disclose duplicate-handling behavior, error conditions, or what the created object looks like beyond the 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?

The description is a compact, well-organized docstring. Every line adds meaning: the purpose line is followed by focused parameter definitions with inline examples. There is no fluff or repetition of schema properties beyond what is needed for clarity.

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

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

Since an output schema exists, return-value documentation is not needed. All parameters are fully explained, and the namespace/fraction guidance gives practical context. The main gap is the lack of explicit duplicate-name or error behavior, which would make it fully complete for a create tool.

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

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

Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. It thoroughly documents all five parameters with concrete examples, defaults, allowed namespace values, and fraction semantics. This is exemplary compensation for a schema with no property 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?

The description opens with a specific verb and resource: 'Create a new commodity (stock, mutual fund, etc.)'. This clearly distinguishes it from sibling tools like create_prices or create_account, and the examples disambiguate what a 'commodity' means in this system.

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 usage—use this tool when you need to add a new tradable commodity—but it does not explicitly state when to prefer it over alternatives or what conditions should be checked first (e.g., verifying the commodity does not already exist). No exclusions or sibling comparisons 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?

Beyond the annotations, the description discloses important behavioral details: owner-side derivation from document type, per-type ID counters, default date/currency behavior, the conditional requirement for party_type on credit notes, and the subtle provenance semantics of applies_to_id. These are exactly the non-obvious traits an agent needs to know.

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 long, but every section earns its place: purpose, workflow, then parameter semantics. The most critical behavioral nuance (provenance not constraint) is clearly surfaced. Formatting with code literals and per-argument lines makes it scannable despite the length.

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

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

Given 10 parameters, complex conditional logic, and an output schema, the description is complete. It covers the full lifecycle (create → add entries → post), defaulting behavior, credit-note specifics, and even notes a response echo for date_opened. Nothing an agent needs 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?

Schema description coverage is only 10%, so the description carries the full burden for the other 90%. It meaningfully explains all 10 parameters, including defaults, conditional requirements, allowed values, and constraints like 'job_id must belong to the same owner'. This is far beyond what the input 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 opens with a specific verb and resource ('Create a customer invoice, vendor bill, employee expense voucher, or credit note') and enumerates the four document types. It also distinguishes itself from sibling tools like add_document_entry and post_document by sketching the creation workflow.

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 clearly states when to use this tool: to create the four document types. It goes further and routes the agent through the follow-up workflow ('add line items with add_document_entry, then post_document'), which is valuable context. It does not explicitly list exclusions or alternatives for non-document creation (e.g., create_transactions), but the usage context is strong.

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 include readOnlyHint=false, so a write operation is expected and the description's 'Create' is consistent. The description adds useful behavioral context beyond the schema: it explains job semantics, the customer/vendor restriction, and the reason employees are unsupported. It does not contradict any annotation.

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 front-loaded with the core action and then efficiently explains the domain concept and parameters. The Args block is structured and every sentence adds value; there is no filler or repetition of 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?

The tool has an output schema, so return-value documentation is not required. The description covers the required parameters, optional reference, and domain constraints. It could add more about validation or what happens if owner_id does not exist, but the current information is sufficient for correct invocation in the expected context.

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

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

Schema description coverage is 0%, so all parameter meaning falls on the description. It fully compensates by documenting owner_id, owner_type, name, and reference with examples and constraints, including the explicit allowed values 'customer'/'vendor' and the exclusion of employees.

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

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

The description opens with a specific verb and resource: 'Create a job for a customer or vendor.' It also defines a job as a project-level container grouping invoices or bills, giving the tool a clear domain meaning and distinguishing it from sibling tools like list_jobs, update_job, and delete_job.

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 concrete usage context: jobs are useful when a single customer has multiple distinct engagements that should be reported separately. It also explicitly excludes employees, stating they are not supported. It does not name an alternative sibling tool directly, but the create/update/list/delete family is clear enough from context.

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

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

Annotations declare readOnlyHint=false (write operation), idempotentHint=false, destructiveHint=false. The description adds meaningful behavioral context: it is 'additive' with 'nothing else in the book changes,' the lot auto-closes when splits net to zero shares, and it errors if the account ref matches nothing. This goes beyond the binary hints, explaining side-effect scope and failure conditions. It doesn't contradict 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 well-structured: opening purpose, then usage flow, then an exclusion note, then an Args block. Every sentence contributes new information—no fluff. It's longer than minimal but appropriate for a tool with a non-obvious workflow and parameter formats. The front-loaded purpose and quick usage clarity earn it a 4; it loses a point for slightly dense formatting in the middle section.

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 description covers everything an agent needs: what the lot is for, the full lifecycle, how to chain it with sibling tools, parameter formats, error behavior, and when to skip it. An output schema exists, so return values need no description. For a 3-parameter tool with a defined workflow, this is complete and leaves no critical gaps.

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

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

Schema description coverage is 0%, so the description bears full responsibility for parameter meaning. It explains each parameter: account accepts full path, %short GUID, or full GUID; title is a lot identifier with an example; notes are optional. This is far more than the bare schema (type: string) provides. The description fully compensates for the schema's silence.

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

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

The description uses a specific verb-resource pair ('Create a new, empty lot') and clearly states the purpose ('for cost basis tracking'). It distinguishes this tool from siblings by naming the exact flow (create_lot → create_transactions → assign_split_to_lot → calculate_lot_gain) and contrasting it with valuation-only tools (get_book_summary, balance_sheet). No ambiguity about what it does or when it applies.

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?

Provides explicit 'when to use' via the full workflow and states a clear exclusion: 'Skip this tool when you only want a valuation — get_book_summary and balance_sheet price holdings without lots.' It also names the specific alternative tools, leaving no inference burden on the agent. This is textbook usage 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 only say readOnly=false, idempotent=false, etc. The description adds materially beyond that: additive behavior, no duplicate checking, per-type ID counters, employee notes rejection, and the returned ID handle. No contradiction with annotations.

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

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

The description is detailed but every sentence adds value. Key behavioral warnings are front-loaded, and the Args section is cleanly structured with no filler.

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

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

Given the tool's complexity and minimal schema documentation, the description covers purpose, usage, behavior, return value, parameter semantics, and edge cases like employee notes. Nothing critical is missing for correct invocation.

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

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

Schema coverage is only 20%, but the description documents all five parameters with meaning: party_type roles, currency defaulting, notes 4096 cap and employee rejection, name examples, and address sub-fields with caps. It fully compensates for the sparse 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 opening sentence names a specific verb and resource: 'Create a customer, vendor, or employee.' It clearly distinguishes this from sibling tools like list_parties, get_party, update_party, and delete_party.

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 explicit usage context: 'each call creates a fresh party — names are NOT checked for duplicates, so list_parties first when unsure.' It names the relevant alternative tool and explains when to use it, plus clarifies party_type semantics.

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 description adds substantial behavioral context beyond the sparse annotations: existing prices are updated rather than duplicated, currency defaults to the book's currency with a worked example, date and source default, and price_type values are enumerated. This is exactly the kind of surprise-preventing behavior 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?

The description front-loads the core operation and the critical upsert semantics, then uses a compact Args block. There is no filler; the example is purposeful and the structure makes the details 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?

Given an output schema exists and annotations cover the non-read-only nature, the description supplies everything needed to invoke the tool correctly: defaults, edge cases, examples, and valid price_type values. No important behavioral or parameter-related information is missing.

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

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

Schema description coverage is 0%, but the description fully compensates: every parameter is explained with formats, examples, defaults, and allowed values. The currency explanation and the 'USD = 7.30 CNY' example add meaning far beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'Record a price for a commodity (stock, NAV, exchange rate).' It clearly conveys that this is a single-price write operation and contrasts naturally with siblings like get_prices, delete_price, and create_prices.

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 purpose is clear enough that an agent can infer when to use it, and the upsert behavior is stated. However, it never explicitly tells the agent when to prefer this over the sibling create_prices, or when to use the price-querying siblings instead. The guidance is implied rather than explicit.

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 description reveals critical behavior beyond annotations: existing prices with the same commodity/currency/date/source are updated in place with status 'updated', never duplicated; the whole batch is sunk on any bad row under on_error='abort'; and dry_run=true previews as 'would_create'/'would_update'. It also notes one book open and one save, which is not inferable from 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?

The description is long only because the TSV format is complex; every block serves a purpose: input grammar, example, per-column semantics, batch behavior, and companion tool. The front-loaded one-line summary makes the core purpose immediately identifiable.

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 description is complete for a tool with a complex data input and error semantics. It explains the full input contract, defaults, update-in-place behavior, atomic failure mode, dry-run statuses, and even the companion listing tool, so an agent can invoke it safely and correctly without digging elsewhere.

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

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

Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. It precisely documents the `prices` TSV format with required and optional columns, per-column defaults, and gives a concrete multi-row example. `dry_run` and `on_error` are each given behavioral meaning beyond their schemas.

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?

"Record MANY prices in one call (bulk quote entry)" clearly states the verb, resource, and batch scope, and distinguishes it from the single-item sibling create_price. The opening sentence is specific and 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 explicitly says per-row semantics match create_price's exactly, signals dry_run and on_error behaviors, and points to list_commodities(stale_days=30, held_only=true) as the companion work list. An agent knows when this tool applies and what alternatives/contexts 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?

Beyond the annotations, the description adds meaningful constraints: currency defaults to the book default, and currency is 'not updatable after creation — delete and recreate to change it.' It also clarifies that notes are visible in GnuCash's double-line register view, helping an agent predict side effects. It does not contradict 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 longer than average but every line earns its place for a 9-parameter tool with no schema-level descriptions. The one-sentence purpose is front-loaded, followed by a compact Args list with examples and constraints.

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 description covers every parameter, required and optional, including defaults and format validation. Since an output schema exists, not describing the return value is acceptable. Minor details like how soon the schedule starts are not necessary for a correct invocation.

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

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

With 0% schema description coverage, the docstring compensates fully by explaining each parameter: split amounts must be decimal strings, quantity is required on commodity mismatch, frequency has six enumerated values, and currency has a concrete usage example. This goes well beyond the bare schema types.

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

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

The opening sentence uses a specific verb ('Create') and names a distinct resource ('recurring transaction template'), which cleanly separates it from siblings like create_transactions and create_transaction_from_scheduled. The scope is unambiguous even before reading the parameters.

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 sets a clear context: this tool is for recurring templates, not one-off transactions or posting from an existing schedule. It does not explicitly name alternative tools or state when not to use them, so it stops short of a full exclusion 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 only convey generic traits (mutating, non-idempotent, non-destructive). The description goes well beyond them by disclosing posting-time side effects (multi-entry composites produce multiple tax splits per line), the name-uniqueness constraint, the same-commodity requirement across accounts, and the ASSET/LIABILITY account restriction. No contradiction with annotations.

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

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

Well-structured and front-loaded: one-sentence purpose, a tight domain-context paragraph, a formatted Args section, and a complete runnable example. The length is justified by the complexity the schema fails to capture; 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?

Complete for a moderately complex create tool: purpose, every parameter and sub-field, constraints, side effects, and a worked example are all present. The output schema covers return values, and annotations cover the safety profile, so nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 0% and the entries parameter is an untyped shell (additionalProperties: true), so the description carries the full burden and succeeds. It documents name uniqueness with concrete examples and fully specifies the entries dict structure, including the crucial pitfall that percentages are rates ('5.00' = 5%, not '0.05') and the accepted account reference formats.

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

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

Opens with the specific verb+resource 'Create a new sales-tax table' and then elaborates what a taxtable is and how entries behave. This clearly distinguishes it from the sibling CRUD tools list_taxtables, update_taxtable, and delete_taxtable.

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 through the create verb and the thorough domain explanation, but there is no explicit routing to alternatives such as update_taxtable for modifying an existing table or list_taxtables for discovery. No preconditions, exclusions, or 'use this when' guidance is 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 are largely uninformative (readOnlyHint=false merely indicates mutation; no idempotency or safety hints). The description adds the useful default behavior of transaction_date ('Defaults to next occurrence') but does not disclose what happens to the scheduled template after creation, whether repeated calls duplicate transactions, or other side effects. For a state-changing operation, this is a meaningful 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 description is extremely concise: a one-line purpose statement followed by a tight parameter list. Every sentence earns its place, and the key purpose 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?

Basic invocation data is present: required guid and optional transaction_date with default behavior. The presence of an output schema means return values need no explanation. However, for a mutating operation that materializes a transaction, the description omits the effect on the scheduled template and the consequences of repeated calls, leaving the agent with partial context.

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 schema description coverage at 50%, the description compensates by explaining both parameters: guid as a scheduled transaction GUID/prefix, and transaction_date as the date for the transaction with a clear default of next occurrence. This adds real meaning beyond the raw schema, though date format could be more precise.

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 ('actual transaction from a scheduled template'), which clearly distinguishes it from sibling create_scheduled_transaction (template creation) and create_transactions (manual transaction creation). The phrase 'actual transaction' makes the materialization purpose 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 intended use is implied: use this when you have a scheduled template and want to generate the concrete transaction, optionally on a specific date. However, it does not explicitly state when not to use it, nor does it contrast with alternatives like create_transactions or update_scheduled_transaction.

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 carrying only readOnlyHint=false, destructiveHint=false, and idempotentHint=false, the description shoulders the behavioral burden and does so exhaustively. It discloses atomic save semantics, whole-batch abort on structural errors, per-row duplicate rejection, force override, dry_run validation without writing, auto-filled row marking (auto_filled_from), and that notes are intentionally not copied from source. None of this contradicts the annotations — readOnlyHint=false is consistent with a tool that creates transactions.

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 long, but the tool is genuinely complex (TSV format, five opt-in extensions, auto-fill, error modes, dual output tables), and nearly every block earns its place. It is well-structured with capitalised headers, ASCII code examples, and a clear front-loaded purpose statement followed by progressively deeper detail. It loses one point only for sheer length — much of the extension detail could arguably be deferred until an agent actually tries to use an extension.

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?

Despite the tool's high complexity (4 parameters, intricate TSV input grammar, multiple behavior modes, and a non-trivial output envelope), nothing an agent needs to call it correctly is missing. Input format, extensions, balancing rules, currency handling, error semantics, and the full output structure (results and duplicates tables, dry-run summary/effects) are all documented, so the lack of additional context in the schema/output_schema is fully compensated.

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

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

Schema description coverage is 0%, so the description must compensate fully — and it does. Every parameter is explained beyond the schema type: 'transactions' is fully specified as a TSV block with header-driven layout and extensions; 'force' (override blocking HIGH duplicates), 'dry_run' (validate + write nothing), and 'on_error' ('abort' vs 'skip') each get concrete semantic meaning. The description completely replaces the absent schema documentation.

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

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

The description opens with a specific verb-resource pair ('Create transactions in one atomic command (bulk entry)') and explicitly declares itself 'the canonical entry tool for one transaction or many.' It even names the removed predecessor (create_transaction) to prevent confusion, and the scoping ('one transaction or many') distinguishes it from related siblings like update_transactions, replace_splits, and enter_statement without needing their schemas.

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

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

The description clearly establishes when to use the tool ('the canonical entry tool for one transaction or many') and gives rich usage scenarios (recurring monthly entries via auto-fill, statement entry via field targeting). However, it never explicitly states when NOT to use it or names alternatives for adjacent operations — e.g., it doesn't say 'use update_transactions to edit' or 'use enter_statement for statement workflows,' despite such siblings existing. Usage context is strong; explicit exclusions are the only 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?

The description discloses all key behavioral assumptions: monthly compounding at apr/12, one payment per month, avalanche allocation, rounding to 0.01, and which debts will be excluded. It even promises that exclusions are surfaced in ⚠ lines rather than silently dropped, which goes well beyond what the readOnlyHint annotation implies.

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 longer than average, but it is organized into scannable sections and front-loads the core purpose. The verbose parameter is explained both in the prose and in the Args block, creating slight redundancy, but every sentence contributes essential 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?

Given the tool's complexity, the description is complete: inputs, prerequisites, computational assumptions, excluded cases, output modes, and structured return fields are all covered. An agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema description coverage is 0%, so the description carries full responsibility for explaining parameters. It fulfills this with an Args block that defines monthly_budget, additional_purchase with its default, and verbose with its output-mode distinction. This is substantially more informative than the bare schema.

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

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

The description opens with a specific verb and resource: calculate an avalanche-method debt payoff schedule, then names the YETI multiplier. It unambiguously distinguishes this tool from the many reporting and account-management siblings by stating its exact scope.

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

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

The description gives clear actionable context: it explains the prerequisite of setting APRs via set_account_slot, describes auto-discovery, and instructs when to use verbose=true. It does not name an explicit alternative tool, but no sibling provides the same function, so exclusions are less critical.

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: true, and readOnlyHint: false, so the mutation risk is covered structurally. The description adds value by disclosing the specific safeguards (deletion blocked when the account has children or transactions), which is meaningful behavioral context beyond the annotations. It does not contradict the annotations, and the idempotent hint is consistent with a delete operation.

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

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

The description is compact: one core sentence stating the action, one sentence on safeguards, and a terse Args block. It is front-loaded with the primary purpose and avoids redundancy. Slightly padded by the formal 'Args:' header, but overall efficient with no wasted sentences.

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

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

For a single-parameter destructive tool with an output schema (so return format is covered elsewhere), the description addresses the main concern—what blocks deletion—and documents the input format. However, it does not state that deletion is permanent when allowed, what happens to related data, or whether this cascades, which matters for a destructiveHint: true tool. Adequate but leaves the irreversibility implication implicit.

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

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

With 0% schema description coverage, the description carries the full burden of explaining the sole parameter, and it does so well: 'Account ref to delete (full path, %short GUID, or full 32-char GUID)' specifies the accepted formats. This compensates for the schema's bare string definition and gives the agent actionable input syntax.

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

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

The description states a specific verb and resource ('Delete an account from the chart of accounts'), which clearly distinguishes it from entity-based siblings like delete_budget, delete_party, and delete_job. However, it does not explicitly differentiate from the closely named delete_account_slot tool, leaving the agent to infer that 'account' refers to the chart-of-accounts entity rather than a slot. Still specific and unambiguous about the core action.

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 provides no guidance on when to use this tool versus alternatives such as deactivate_many or update_account, nor does it state when not to delete. The only context is the safeguard note ('children or transactions' block deletion), which is a behavioral constraint rather than usage direction. An agent gets no help choosing among the many delete_* siblings.

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

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

Beyond the destructiveHint and idempotentHint annotations, the description discloses exact side effects: only the named key is deleted, other slots/account/transactions are untouched, and failures change nothing. It also documents the reserved '/' error condition for hierarchical slots.

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 front-loaded with purpose and side effects, then covers errors, related tools, and arguments. Every sentence contributes necessary operational detail without repetition or filler.

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

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

The description covers behavior, failure modes, alternatives, and both parameters; an output schema exists, so return-value format need not be repeated. Nothing essential is missing for an agent to invoke this tool safely.

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

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

With 0% schema description coverage, the description fully carries parameter meaning. It enumerates the three accepted account reference forms and explains the key constraint (no '/' because user slots are flat), adding material guidance absent from the input schema.

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

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

The description opens with a specific verb and resource: 'Remove one custom metadata slot from an account.' It sharpens scope with 'only the named key is deleted' and explicitly distinguishes itself from get_account_slots and set_account_slot.

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

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

It states the operation is permanent and surgical, and for the alternatives it says 'get_account_slots lists the removable keys; set_account_slot re-creates one.' This tells an agent when to use this deletion tool versus reading or adding slots.

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 description goes well beyond the annotations by disclosing that the action is permanent with no undo or archive, errors idempotently when the name does not match, and leaves transactions and account balances untouched. The annotations already flag destructive and idempotent behavior, but the description adds critical nuance about scope and consequences.

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 well-structured and front-loaded with the core action and consequences. Every major point earns its place: permanence, side-effect scope, missing-name behavior, and the retirement alternative. It loses a small amount for repeating 'exact, case-sensitive' in both prose and the parameter line, but overall it is tight and readable.

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

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

For a one-parameter destructive tool, the description is complete: it explains what is deleted, what is not deleted, what happens on a missing name, and when to prefer a non-destructive alternative. The presence of an output schema covers return-value expectations, so nothing essential is missing.

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

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

Schema coverage is 0%, but the description compensates by defining 'name' as 'Budget name (exact, case-sensitive).' This adds real semantic value beyond the bare string type. It does not discuss edge cases like empty strings or whitespace, but for a single simple string parameter the guidance is sufficient.

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

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

The description opens with a specific verb and resource: 'Delete a budget and every per-period amount set on it.' It clearly names the object and the full scope of the deletion, which distinguishes it from sibling tools like list_budgets or get_budget without needing to open the schema.

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

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

It explicitly tells the caller when not to delete: 'To retire a budget while keeping its numbers readable, simply stop reporting on it instead of deleting.' It also points to list_budgets as the companion tool for checking existing names, which is practical and specific.

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

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

Annotations already convey destructive and non-read-only behavior, so the description goes beyond them by clarifying that only unposted documents qualify and that posted documents require unposting first. It also explains the party_type collision behavior, which is non-obvious and valuable. It doesn't explicitly state that deletion is permanent or idempotent, but the destructive and idempotent hints cover that baseline.

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 core action is front-loaded, the critical posted/unposted caveat follows immediately, and the Args section maps cleanly to the schema properties. Every sentence earns its place, including the brief rationale for the constraint.

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, conditional delete operation, the description covers the object type, the precondition (unposted), the prerequisite action for posted documents, the parameter semantics, and the edge case around party_type. With an output schema present and annotations covering safety, nothing material is missing for an agent to invoke this 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 description coverage is 0%, and the description fully compensates by explaining each parameter: document_type lists valid values, id gives an example format, and party_type describes its conditional necessity and collision scenario. This is exactly the kind of semantic context the schema does not provide.

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 ('Delete') and resource ('UNPOSTED customer invoice, vendor bill, employee voucher, or credit note'), with explicit scope. The qualifier 'UNPOSTED' cleanly differentiates this from unpost_document and makes the tool's sole purpose unmistakable.

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

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

The description explicitly tells agents when not to use this tool ('Posted documents are on the books') and names the alternative path ('unpost_document first'). It also notes a blocking condition ('payments block unposting'), giving concrete routing guidance without leaving room for guessing.

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?

Beyond the destructiveHint annotation, the description discloses that the tool refuses by default to prevent data loss, and that force=True re-parents linked invoices to preserve history. This is exactly the kind of behavioral context an agent needs and the annotations alone do not provide.

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 well-structured and every sentence earns its place: it states the operation, the default protection behavior, the force behavior, and the alternative tool. The Args section is clean and directly maps to the schema parameters.

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 description covers the core operation, the data-loss prevention default, the force behavior, parameter semantics, and the relevant alternative. An output schema exists, so not explaining return values is acceptable. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 0%, so the description carries full responsibility for explaining parameters. It defines job_id as a Job ID and force as the flag that re-parents linked invoices instead of refusing, adding meaning well beyond the raw schema types and defaults.

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 immediately states the operation ('Delete a job') and then explains the key behavioral nuance around linked invoices, distinguishing this tool from update_job and other job-related tools. It clearly identifies both the action and the resource.

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

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

The description explicitly says to use update_job(active=False) instead when keeping the job in place but marking the project done. It also explains when force=True should be used, giving the agent concrete decision criteria for choosing this tool or an alternative.

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?

Beyond the destructiveHint annotation, the description discloses the critical failure condition: deletion is blocked while the party has documents, with a rationale ('the audit trail outranks tidiness'). This adds behavioral context not present in the structured 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 compact and front-loaded with the primary action, followed by two high-value behavioral notes and a concise argument list. Every sentence earns its place with no redundancy.

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

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

For a destructive 2-parameter tool with an output schema present, the description covers purpose, usage, failure conditions, alternatives, and parameter semantics. An agent has enough to select and invoke the tool correctly without additional context.

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

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

Schema coverage is 0%, so the description fully compensates. It explains that party_type is required because 'ID counters collide across types' and gives a concrete format example for id ('000001'). This adds meaning the bare schema lacks.

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

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

The description opens with a specific verb and resource: 'Delete a customer, vendor, or employee.' This clearly distinguishes from sibling tools like update_party, list_parties, and get_party. The scope of the operation is immediately obvious.

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 provides explicit guidance: prefer update_party(active=false) when retiring a party while preserving history, and notes that deletion is blocked when documents exist. This tells the agent when not to use delete_party and which sibling to use instead.

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

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

Annotations already declare destructive and idempotent behavior. The description adds valuable context about how the tool behaves when multiple prices exist on the same commodity+date, explaining that source is needed to disambiguate. This goes beyond the annotation hints.

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 front-loaded with the primary purpose, then provides targeting and disambiguation rules in a logical order. The Args block is structured and every line contributes useful examples or constraints, with no redundant 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?

Given the destructive and idempotent annotations, plus the presence of an output schema, the description covers all essential invocation details: how the price is identified, when source is required, and what each parameter means. No critical information is missing for an agent to call this tool correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It clearly defines all four parameters with concrete examples, format expectations, and the conditional requirement for source. This fully compensates for the empty 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?

Clearly states a specific action ('Delete a single price entry') and identifies the resource by its composite key (commodity, namespace, date). This distinguishes it from sibling tools like create_price, create_prices, and get_prices without ambiguity.

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?

Provides precise guidance on when the optional source parameter is required for disambiguation. It doesn't name alternatives, but there is no direct deletion alternative among the siblings, so the usage context is sufficiently clear.

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 mark this as destructive and idempotent. The description adds meaningful behavioral context by explicitly stating that previously created transactions from the schedule are unaffected. This clarifies the exact scope of destruction beyond what the annotations alone 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?

The description is compact and front-loaded, with the key effect stated immediately after the main action. The Args section is somewhat redundant given the schema already describes guid, but it is brief and does not bloat the definition.

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

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

For a single-parameter delete tool, the description covers the essential behavior, the boundary of its effect, and the parameter meaning via schema. The output schema exists and annotations cover safety traits, so no critical operational context is missing.

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

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

The schema already documents guid with 100% coverage, including the 32-char hex or 8+ char prefix. The description's Args line essentially restates the schema without adding new semantic meaning, so it meets the baseline but does not exceed it.

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

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

The description opens with a clear verb and resource: "Delete a scheduled transaction." It further distinguishes the tool's scope by stating it does not affect transactions already created from the schedule, which is relevant given the sibling delete_transaction tool exists. No ambiguity about what this tool acts on.

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 intended use is implied by the name and opening sentence, but the description does not explicitly state when to choose this over alternatives like update_scheduled_transaction or delete_transaction. The note about not affecting existing transactions is useful context but does not provide explicit when/when-not routing 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?

The annotations already mark this as destructive and non-read-only, and the description adds valuable specifics: the refusal behavior, the SQL-based reference check, that voided invoices still pin taxtables, and the required remediation. This goes well beyond what 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?

The description is front-loaded with the action, followed by the most important behavior and prerequisite, then the argument definition. Every sentence earns its place and there is no filler.

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

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

For a one-parameter destructive tool with an output schema, the description supplies the needed failure condition, persistence nuance, and remediation step. No missing information that an agent would need to call it correctly is apparent.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter meaning. The Args section defines 'name' as 'Taxtable name,' which is sufficient for the single required parameter and adds a small amount of domain context beyond the schema's generic 'Name' title.

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

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

The description opens with a specific verb and object, 'Delete a sales-tax table,' which immediately distinguishes it from siblings like create_taxtable, list_taxtables, and update_taxtable. The resource is unambiguous, and the parameter name reinforces the target.

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 states a clear precondition and failure mode: deletion is refused while any Entry row references the taxtable, and those entries must be removed or re-assigned first. It does not explicitly name a sibling tool as an alternative, but the when-to-use/when-not-to-use context is strong.

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?

Beyond the annotations (destructive, idempotent), it discloses the all-or-nothing batch validation, that a bad GUID removes nothing, the response shape, and the safeguards around reconciled splits and invoice posting records. This is rich behavioral context that annotations alone do not provide.

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 organized with a clear lead sentence, safeguard notes, batch behavior, response format, and an Args section. Every sentence contributes essential operational detail without padding.

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

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

For a destructive tool with batch semantics, safeguards, and a response shape, the description covers all invocation-critical aspects. The output schema exists, and the description still usefully summarizes the list response. Nothing needed for correct invocation 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?

With 0% schema description coverage, the description carries the parameter documentation burden. It explains GUID format and prefix support, that guid can be a list, and what force does. This adds meaningful semantics beyond the bare schema types and defaults.

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

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

The description opens with a specific verb and resource: 'Delete one transaction by GUID — or several in one call.' It clearly distinguishes the deletion operation from sibling transaction tools like void_transaction, update_transactions, and replace_splits, and covers both single and batch use.

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

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

The description gives clear operational context: deletion is blocked for reconciled splits unless force=true, and invoice posting records require unpost_document first. It does not explicitly contrast with alternatives like void_transaction, but the preconditions and override behavior are specific and useful enough to guide correct usage.

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 description discloses atomic all-or-nothing saves, exact transcription requirements, sign conventions derived from account type, safety gate 'opening + sum(lines) == closing', independent force-flag effects, duplicate-detection behavior, auto-fill behavior, and read-back verification after commit. This richly supplements the annotations, which only mark the call as non-readOnly, non-open-world, idempotent, and destructive.

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?

Although long, the description is tightly organized into labeled sections: workflow, transcription rules, input grammar, safety, and output formats. The most important usage model is front-loaded, and the detailed examples and field enumerations are necessary given the tool's complexity. No sentence is 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 high-complexity tool with 9 parameters, zero schema parameter descriptions, a TSV input grammar, two execution modes, and safety-critical behavior, the description is essentially complete. It covers all required fields, explains both dry-run and commit output shapes, lists refusal conditions, and gives a runnable minimal input example. The presence of an output schema does not create any notable gap.

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

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

Schema description coverage is 0%, but the description compensates completely. Every parameter is explained: account ref formats and allowed types, statement_date as the reconciliation date, exact balance semantics, the full TSV grammar for lines, and the meaning and default of each boolean flag. The example line block conveys the required format better than a schema description could.

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

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

The description opens with a specific verb and resource: 'Enter a COMPLETE bank/card statement in one atomic call,' and immediately differentiates the tool by including create, claim, and reconcile behavior in a single save. This clearly separates it from generic transaction creation or standalone reconciliation tools among the 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?

The 'WORKFLOW' section explicitly prescribes a two-call pattern: dry_run first, adjudicate MATCH/AMBIGUOUS rows, then commit with dry_run=false. It also gives explicit conditions such as 'fix the book first if they disagree,' explains when force_base and force_duplicates are appropriate, and warns when the call will reject. This is unusually concrete operational 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?

Beyond the readOnlyHint annotation, the description states 'Read-only' and discloses precise error behavior: returns an error object when ref matches nothing and never raises. This is valuable operational context that the annotation alone does not provide.

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 well-structured: purpose first, then safety/error behavior, then sibling routing, then parameter format. Every sentence adds distinct value, and the format is 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 single-parameter read-only tool with an output schema, the description covers purpose, return contents, acceptable ref formats, error behavior, and alternatives. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does thoroughly. The Args section explains the 'name' parameter's accepted forms (full path, %short GUID, full 32-char GUID) with a concrete example, giving an agent the syntax needed to call the tool.

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 ('Get details for one account') and enumerates the exact data returned (type, commodity, description, placeholder flag, GUID, hierarchy position). It differentiates from get_balance and get_account_slots before those tools are even named by clarifying what this tool does and does not return.

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

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

Explicitly routes to alternatives: list_accounts for bulk discovery, get_balance when only a number is needed, get_account_slots for custom metadata. This gives clear when-to-use and when-not-to-use guidance, which is exactly what an agent needs to select among siblings.

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

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

Annotations already indicate read-only and non-open-world behavior. The description adds meaningful behavioral context: slots are key-value metadata, account can be a path/%short GUID/full GUID, and omitting 'key' returns all slots. This complements the annotations without contradicting them.

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 concise and front-loaded: the core action is stated first, followed by a short clarifying explanation and a compact Args block. Every sentence earns its place with no repetition or filler.

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

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

For a simple read-only tool with a single required parameter, the description covers the account reference formats, the optional key semantics, and general slot context. The output schema exists, so return values are already specified elsewhere. Nothing essential is missing.

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

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

Schema description coverage is 0%, so the description bears the full burden for parameters. It clearly explains the 'account' parameter's accepted reference formats and the optional 'key' parameter's default behavior, far exceeding the schema's bare field names.

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

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

The description opens with 'Read slots (custom metadata) from an account', a specific verb and resource, and clarifies slots as key-value pairs. This clearly distinguishes it from sibling set_account_slot and delete_account_slot, which perform mutations.

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 read-only wording and slot key-value explanation make the intended use clear against the set/delete siblings, and the account ref formats provide conditions for use. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to select this tool correctly.

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 carry readOnlyHint=true, and the description adds rich behavioral context beyond that: backward-pagination semantics, limit=0 returning count only, the leading indicator format, blank-line separation per write operation, and the fact that reads are not logged. No contradiction with the read-only annotation.

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 longer than average, but each section earns its place: the output-format indicator, the genuinely non-intuitive backward-pagination behavior, and the enumerated args. It is appropriately front-loaded and structured into paragraphs plus an Args block. Slightly verbose but justified by the unusual semantics.

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

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

An output schema exists, so return values need no explanation, yet the description still covers the indicator line. The most error-prone behavior (reverse offset ordering) is fully disclosed, and the read-only annotation is reinforced by the 'Reads are not logged' note. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 0%, so the description must fully compensate. It documents all three parameters with meaning beyond the schema: log_date (YYYY-MM-DD format, defaults to today), limit (page size, 0=count only), and offset (entries to skip back from most recent, 0=newest). This fully compensates for the zero-coverage schema.

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

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

The description uses a specific verb-resource pair ('Read audit log entries for a date') and adds concrete detail about what is returned (human-readable text, blank-line separated entries, 'Showing X-Y of Z' indicator). This clearly distinguishes it from the many sibling tools, none of which are audit-log readers.

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

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

The description explicitly contrasts with 'the row-list tools' by explaining that the window anchors to the most recent entry and that offset pages backward — important guidance for a non-obvious API. It also states that reads are not logged. However, it does not name specific alternative tools or give explicit when-not-to-use conditions, so the guidance is contextual rather than prescriptive.

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 readOnlyHint annotation already signals a safe read operation. The description adds meaningful behavioral context by disclosing that future-dated transactions, scheduled payments, and accrued interest are excluded by default, and that passing a future as_of_date changes the balance projection. No contradiction with annotations.

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

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

The description is well-structured: a one-sentence purpose, a concise behavioral note, then an Args block. Minor redundancy exists ('Defaults to today's date' and later 'Defaults to today'), but overall it is efficient and 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 an output schema present and both parameters well documented, the description covers what an agent needs to invoke the tool correctly. The main gap is that balance computation semantics beyond future-date exclusion are not described, but this is not essential for basic invocation.

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

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

Schema description coverage is 0%, but the description fully compensates by documenting both parameters: account_name includes acceptable formats (full path, %short GUID, full 32-char GUID) and as_of_date specifies ISO format and default behavior. This adds significant meaning beyond the bare schema field titles.

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: 'Get the balance of an account as of a specific date.' This clearly distinguishes the tool's core function from account metadata tools like get_account or get_book_summary, though it does not explicitly name sibling alternatives.

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

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

The description gives clear usage guidance around the date behavior: it defaults to today, excludes future-dated transactions, and instructs when to pass an explicit as_of_date to project forward. It does not explicitly discuss alternative tools or exclusion conditions, but the when-to-use context is strong.

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=true, so the read-only nature is established. The description adds useful context about the response being a 'single text response' and enumerates the contents, but it does not disclose any additional behavioral traits beyond 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?

The description is compact and front-loaded with the core purpose, followed by a concise summary of return contents and a clear usage instruction. Every sentence earns its place with no filler.

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

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

With zero parameters, a read-only annotation, and an output schema present, the description provides everything an agent needs to invoke this tool correctly. It clearly states what will be returned and when to use it.

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

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

The tool takes zero parameters, so no parameter documentation is needed. The description still adds value by defining the tool's scope ('entire GnuCash book'), which makes the absence of parameters sensible.

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 clearly states a specific verb ('Get') and resource ('compact overview of the entire GnuCash book'), giving agents an immediate understanding of the tool's purpose. It differentiates itself from granular sibling tools like get_account or list_transactions by emphasizing the whole-book scope.

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 'Use this first to orient yourself' explicitly provides a clear usage context, positioning this tool as the initial orientation step. It does not explicitly enumerate alternatives or when-not-to-use cases, but the guidance is strong enough for an agent to select it appropriately among siblings.

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

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

Annotations already mark the tool as read-only, so the description's main behavioral contribution is the output-shape disclosure: compact text collapses uniform periods, while verbose=true returns structured JSON. This adds meaningful context beyond the annotations. It doesn't mention error behavior, but for a read-only retrieval tool the output behavior is the key trait.

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 well-organized and front-loaded: purpose, output behavior, then parameter details. Every sentence contributes useful information, and the verbose explanation is concise while still covering the important distinction. No fluff or repetition.

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

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

For a two-parameter read-only tool with an output schema, this description is quite complete: it explains the default and verbose output, the structure of the verbose result, and the purpose of each parameter. Minor gaps like exact name-matching behavior or error handling are not critical given the simplicity of the 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 0%, so the description must carry parameter semantics. It fully compensates: 'name' is explained as the budget name, and 'verbose' gets a detailed explanation of both states including the default and the resulting output format. This goes well beyond the bare boolean/string schema.

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

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

The description clearly states the verb and resource: 'Get full details of a budget including all budget amounts.' This is specific and readable. It doesn't explicitly differentiate from siblings like get_budget_report or list_budgets, but the full-details framing and output details make its scope reasonably clear.

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

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

The description gives clear guidance on when to use verbose=true versus the default compact text output, even explaining the tradeoff between token efficiency and machine-readable structure. It does not explicitly mention when to choose this tool over similar siblings, so it falls just 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?

The description goes beyond the readOnlyHint annotation by explaining the default compact text-table output with ⚠ markers on categories exceeding budget, and the toggle to verbose structured JSON. It also notes the token-efficiency rationale for the default, giving the agent useful behavioral context for choosing output formats.

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 structured with a clear purpose line, output summary, and an Args section where every parameter gets a scannable bullet. Each sentence serves a distinct purpose, and the verbose/format guidance is front-loaded before the parameter details.

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

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

Given the tool's complexity, the description covers all invocation-relevant behavior: default output format, verbose mode, period options, account filtering, and child-account inclusion. The presence of an output schema means return structure is already specified elsewhere, so no additional return documentation is necessary.

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

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

With 0% schema description coverage, the description fully compensates by documenting every parameter: budget_name, period (including the None default, integer range, 'ytd', and 'all' options), account, include_children, and verbose. The period parameter especially benefits from concrete allowed values that the raw schema 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?

The first sentence, "Compare actual spending against budget," names a specific verb and resource, clearly distinguishing this from budget configuration tools like get_budget or create_budget. The mention of compact text tables with warning markers further reinforces that this is a reporting tool rather than a CRUD operation.

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 makes it clear the tool is for comparing spending to budget and provides detailed period semantics, but it does not explicitly state when to prefer this over sibling report tools such as spending_by_category, vendor_spending_report, or get_job_report. Usage is implied rather than explicitly routed with alternatives and 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 mark this as read-only, and the description adds meaningful behavioral context: it returns all entries with quantities, prices, and totals, names the document kind in the response `type` field, and explains the open/posted/paid status vocabulary. This goes well beyond the annotations and helps the agent interpret results correctly.

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 front-loaded with the core purpose, then moves to return behavior and status semantics, then parameter details. Each sentence earns its place, and the Args block is structured, direct, and free of fluff.

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

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

Given the read-only annotation and the presence of an output schema, the description covers everything needed to call the tool correctly: document scope, return contents, status meaning, ID format, and optional parameter roles. Error/not-found behavior is not described, but this is a minor omission relative to the otherwise complete guidance.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it delivers: id is explicitly the human-readable ID, not the internal GUID; document_type is explained as a disambiguator for per-type counters; party_type is scoped to credit notes. This is more informative than the raw schema.

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

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

The description uses a specific verb and resource: 'Get full details for a customer invoice, vendor bill, employee voucher, or credit note, including line items.' It also distinguishes itself from related tools by pointing to list_documents and get_outstanding_documents for definitions and unpaid lists.

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

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

The description gives clear context and points to alternatives: 'full definitions live on list_documents' and 'the unpaid list is get_outstanding_documents.' It does not explicitly say 'use get_document when you need a single document's line items' or 'do not use it for lists,' but the purpose and pointers make the intended usage reasonably clear.

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?

Beyond the readOnlyHint=true annotation, the description discloses meaningful behavioral details: drafts are included with billed + outstanding and paid=0, totals are currency-keyed, and per-invoice breakdowns are returned. This gives an agent an accurate model of what the report contains and how numbers are computed.

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 compact and front-loaded: the first sentence gives the tool's purpose, the second paragraph adds behaviorally important details about currencies and drafts, and the Args line is minimal but useful. No redundant prose or filler.

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

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

Because an output schema exists, return shape details are already covered elsewhere. The description supplies the missing context: what the totals key on, how drafts are treated, the per-invoice breakdown, and the one parameter's format. Nothing required for correct invocation is missing.

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

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

The input schema only provides the name and type for job_id, so the description carries the burden at 0% schema coverage. The description adds a brief semantic explanation and an example ('Job ID (e.g., "000001")'), which is sufficient for a single simple required parameter.

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

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

The description names a specific resource ('Per-job summary') and precise metrics ('billed / paid / outstanding totals across all linked invoices, plus the per-invoice breakdown'). This clearly separates it from sibling report tools like get_budget_report or vendor_spending_report without needing to inspect schemas.

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

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

The description makes the intended context clear: this is the job-level invoice report, including draft and posted invoices. It does not explicitly state when not to use it or name alternatives like get_budget_report, so it falls short of full routing guidance, but the scope is unmistakable.

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=true, and the description does not contradict that. It adds useful behavior beyond annotations: the exact return fields (date, value, type, source) and the null-when-no-price behavior, which an agent needs to interpret the response correctly.

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 compact and scannable: a one-line summary, a short Args section, and a Returns section. Every sentence contributes useful information, and no filler or repetition is present.

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 read-only lookup tool, the description covers all elements needed to invoke it correctly: required parameters, optional parameter semantics, return shape, and the null case. The read-only safety profile is already in annotations, and the return contract is stated explicitly.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining the three parameters. It provides a concrete example for commodity and namespace and clearly explains the currency default and when to pass it explicitly. This fully compensates for the schema's bare names.

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

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

The description states a clear action and object: 'Get the most recent price for a commodity,' with commodity, namespace, and currency parameters. It is specific enough to be distinguishable from price-mutating siblings like create_price and delete_price, but it does not explicitly contrast with get_prices, so it falls short of full sibling 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?

No guidance is given about when to choose get_latest_price over get_prices or other siblings. The only usage-related context is the currency default behavior, which explains how the optional parameter behaves rather than when to use this tool versus alternatives.

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 mark the tool as read-only, and the description reinforces this by specifying it 'Returns' data rather than mutating state. It adds useful behavioral detail about the response contents (all splits, summary fields), which goes beyond the annotation metadata.

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 well-structured with a clear purpose line, an Args section, and a Returns section that lists key output fields. It is somewhat repetitive with the schema's parameter description, but every section adds useful navigation value.

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 read-only lookup tool with an output schema and readOnly annotations, the description is largely complete. It covers input format and return structure, though it does not describe error behavior for unknown or invalid GUIDs, which 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 schema already documents the guid parameter fully. The description repeats the parameter information without adding new semantic meaning, so the baseline score of 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 states a specific action ('Get detailed information') on a specific resource ('a lot'), making the tool's purpose clear. It implies differentiation from list_lots by focusing on a single lot's detailed data, but it does not explicitly name or contrast with sibling 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?

Usage is implied: call this when you have a lot GUID and need full details including splits and summary. There is no explicit guidance about when not to use it or which alternative to choose, such as list_lots for enumeration or calculate_lot_gain for gain calculations.

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 mark the operation read-only, and the description adds substantial runtime behavior beyond that: the 'Showing X-Y of Z' summary line, compact one-line-per-doc format, action columns, most-overdue-first sorting, pagination with offset, and limit=0 count-only semantics. No contradiction with annotations.

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

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

The description is long but every part earns its place: overview, use-case, output format, sorting, pagination, verbose mode, and a per-parameter Args section are cleanly organized and front-loaded with the core purpose. There is no filler.

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

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

For a six-parameter tool with no schema descriptions, the description supplies nearly all needed call context: result shape, sorting, paging, count behavior, and output-mode switch, and an output schema exists for structured returns. The omission of the employee party_type option is the only material completeness 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?

With 0% schema description coverage, the description carries the full parameter burden and documents limit, offset, verbose, party_type, customer_id, and vendor_id with concrete meanings and edge cases such as limit=0 and default/max limits. The only gap is that party_type schema also allows 'employee', but the Args text only mentions filtering by customer/vendor despite employee vouchers being in the overview.

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

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

The description names a specific verb and resource set: posted customer invoices, vendor bills, employee vouchers, and credit notes with outstanding balances. It also explicitly distinguishes itself from list_documents and get_document as the authoritative unpaid list, so an agent can tell what it does without ambiguity.

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