stub

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

No contradiction with annotations (readOnlyHint=false, destructiveHint=false). The description conveys a write operation but does not disclose side effects such as reindexing or total recalculation, which are mentioned only in parameter descriptions. The behavior is generally expected for an 'add' 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 two sentences, concise and well-structured. It front-loads the core action and target, then adds the pairing note. No unnecessary detail 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?

The description provides enough context for the core add scenario, including document types and item identification. It does not explain output (no output schema), which is acceptable. The parameter descriptions fill in most contextual gaps. Minor omission: the description does not mention that the tool can also update via providing an id, but that is covered in the parameter semantics.

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?

All 14 parameters have detailed descriptions, including aliases, precedence rules, decimal-fraction rate clarification, and internal use. The schema description coverage is 100%, and the parameter docs add significant guidance beyond names and 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 description clearly states the action (add a sales-tax/VAT line), the target (a single line item on a document), and the document types. It also mentions the pairing with the update tool, providing a clear purpose.

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

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

The description names the sibling update tool, but does not explicitly distinguish when to use this tool versus other sales-tax tools like add_entity_salestax. It implies document-item scope but lacks an explicit 'use this when' or 'don't use that' statement.

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 indicate readOnly=false and destructive=false, and the description confirms this is a mutating 'Add' operation. However, the description does not disclose additional behavioral traits such as optimistic-concurrency behavior, validation rules, or whether a parent document must already exist.

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

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

The description is a single, clear sentence with no filler. It includes useful examples of document types in parentheses, making it concise and scannable.

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 minimal and relies heavily on the input schema for context. It does not mention key operational constraints—such as the need for a parent quinvoice, how line totals are derived, or interaction with tax/cost fields—so despite the rich schema, the high-level description leaves some contextual 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?

The input schema has 100% coverage with detailed per-parameter descriptions, so the baseline is 3. The main description does not add extra meaning to the parameters; it only labels the operation generically, while the schema carries the semantic weight.

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 tool's function: adding a line item to a document, with explicit document types (invoice, quote, bill). The verb 'Add' and the resource 'line item' are specific enough to distinguish this from update or delete 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 implies usage—it says 'Add' and targets line items—but it does not explicitly contrast with sibling tools like update_document_item or delete_document_line. The parameter description for 'id' mentions 'Required on update_document_item; omit on add_document_line,' which provides indirect guidance but not a full when-to-use statement.

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 a write operation (readOnlyHint=false, destructiveHint=false), but the description adds no behavioral context beyond the action itself. No mention of side effects, prerequisites, or how the addition affects existing tax calculations.

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 two short sentences, front-loading the primary purpose and then providing a concise usage alternative. No wasted words.

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

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

For a single-add tool with a rich schema and clear sibling distinction, the description is sufficient. It states the purpose and usage guidance; the schema covers parameters. A slightly more detailed behavioral note would be nice, but not essential.

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 has 100% parameter description coverage, so the description does not need to explain parameters. The baseline of 3 applies; the description adds no extra meaning beyond the schema.

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

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

Clearly states the action: 'Add a sales tax to an entity.' The verb 'add' and resource 'sales tax' are specific, and the mention of the plural sibling add_entity_salestaxes distinguishes it from the batch 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?

Explicitly guides when to use this tool vs. the alternative: 'To add several taxes at once, prefer add_entity_salestaxes.' This tells the agent to use this tool for a single tax addition, which is a clear usage direction.

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?

Describes non-deduplication ('does not deduplicate... adds another copy') and error behavior ('returns an {:error true} map rather than throwing'), providing useful insights not present in the sparse annotations.

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

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

Four sentences, each carrying essential information with no filler: purpose, deduplication behavior, error handling, and alternatives.

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?

Covers core behavior, edge cases (duplicate ids, missing entity), and alternative routes, but does not specify the success return value; however, no output schema is provided, so this 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 descriptions fully cover all three parameters (entity, entityid, taxids) with clear meanings; the tool description adds no extra parameter detail beyond what the schema already 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?

Clearly states it adds multiple sales taxes to one entity by their ids, and distinguishes from sibling tools (add_entity_salestax for a single tax, add_salestax_to_entities for applying one tax across many entities).

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

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

Explicitly names alternative tools and when to use them: 'To add a single tax to one entity use add_entity_salestax; to apply one existing tax across many entities use add_salestax_to_entities.'

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 readOnlyHint=false and destructiveHint=false. The description only says 'Add', which is implicit from the tool name and annotations. It does not disclose additional behavior such as validation of the parent entry, effect on totals, or failure modes. No extra transparency beyond the annotations.

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

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

The description is two concise sentences, front-loading the core purpose and immediately providing sibling context. No wasted words.

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

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

For a simple mutation with 5 clear parameters, the description provides enough to understand the operation. However, it omits any mention of parameter requirements (all are listed optional in schema) and does not explain return behavior or error conditions. Adequate but not fully complete.

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

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

The schema descriptions already cover each parameter with 100% coverage, so the description adds little. It does not clarify that entryid, accountid, and one of debit/credit are logically required even though the schema lists no required parameters. This is a minor gap but not severe given the parameter descriptions.

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

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

States a specific action ('Add a line') on a specific resource ('existing journal entry') and clearly distinguishes from sibling tools by naming update_journal_line and save_journal_entry. The purpose is unambiguous.

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

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

Explicitly tells when to use this tool versus update_journal_line (pairs with) and save_journal_entry (for whole new entry). It does not cover other potential alternatives or prerequisites, but the given guidance is clear and actionable.

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 this is a write operation with no destructive intent. The description adds that it works as a single transaction and applies an existing tax definition, but it does not disclose potential side effects such as overwriting existing tax assignments or partial failure 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 concise, uses only two sentences, and front-loads the core purpose. Every clause adds relevant information, with no filler or redundancy.

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

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

For a simple bulk update tool, the description provides sufficient context: what it does, what it applies to, and what it does not support. No output schema is present, so return-value details are not required, though a note on success/failure behavior could make it slightly more complete.

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

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

The schema descriptions fully cover all three parameters with clear meanings. The tool description mostly restates the schema rather than adding new semantic detail, such as constraints on tax IDs or behavior when multiple entity IDs are invalid.

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 action: applying one existing sales tax to several income or expense records in a single transaction. It also explicitly distinguishes this tool from invoice/bill line-item tax handling, making its 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 description gives clear usage context by specifying that invoices/bills use line-item tax and are not supported here. It implies the appropriate alternative for those cases, though it does not explicitly name a sibling tool.

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

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

Annotations already cover readOnlyHint=false and destructiveHint=false. The description adds no behavioral details beyond the basic action, such as side effects, error conditions, or return values. It is consistent with the annotations but does not go beyond 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 a single, clear sentence that is concise and well-structured. It avoids unnecessary words and effectively communicates the tool's purpose.

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

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

The tool is relatively simple with three required parameters, all described. However, the description omits any mention of output or success/failure feedback, which could be important for an agent to confirm the attachment process. It is adequate but not fully comprehensive.

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 100% coverage for all three parameters with clear descriptions. The tool description itself adds no additional parameter semantics, so the baseline score 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 clearly states the action: attaching a file to an entity, with examples like invoice and expense. It is specific and distinguishes from file-related sibling tools such as list_files or remove_file.

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 explicit guidance on when to use this tool versus alternatives. It lacks context about prerequisites (e.g., file must be uploaded first) and does not contrast with other file operations.

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 provide destructiveHint=true, and the description adds the specific destructive scope: it clears all tags from one entity. This goes slightly beyond the annotations but does not disclose additional behaviors such as irreversibility or effects on related data.

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

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

The description is a single front-loaded sentence with no wasted words. It communicates the core operation efficiently.

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 two-parameter tool with no output schema, the description, full parameter descriptions, and destructive annotation are largely sufficient for an agent to select and invoke the tool correctly. It lacks only a brief mention of related set operations or consequences.

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

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

Schema description coverage is 100%: both 'entity' and 'entityid' are described with examples. The description adds no additional parameter meaning beyond what the schema already provides, 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 states a specific verb ('Clear') and resource ('all tags from an entity'), clearly distinguishing it from sibling tools like set_entity_tags or set_entity_tags_bulk. The scope (all tags) is explicit.

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

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

No guidance is given on when to use this tool versus alternatives such as set_entity_tags, set_entity_tags_bulk, or delete_tag. The description only states what it does, not when an agent should choose it.

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

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

Beyond the readOnlyHint annotation, the description explicitly states 'READ-ONLY: it converts, never records anything' and details the exact return fields, future-date handling, and the no-rate error shape. This gives an agent a clear behavioral model without needing to call the tool or inspect external docs. 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 a single dense paragraph of roughly 100 words, front-loaded with the core action and rate source before optional arguments and edge cases. Every sentence serves a purpose, and the READ-ONLY note, while echoing the annotation, is a useful reinforcement rather than 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?

Since there is no output schema, the description takes on the burden of documenting the return object, and it does so explicitly: amount, from, to, converted, rate, ratedate, and optional within_tolerance. It also covers the no-rate error case, tolerance bounds, and the connection to find_candidate_transactions, so an agent has all information needed 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?

The schema already covers 100% of parameters, but the description adds meaningful semantics it does not: target is explained as an amount in the 'to' currency such as a bill's balance, tolerance is tied to the default 3% cross-currency matching band, and within_tolerance behavior is defined. This enriches the parameters beyond the structured 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 'Convert an amount between currencies at the OpenExchangeRates rate for a date', giving a specific verb, resource, and rate source. It is immediately distinct from sibling tools like find_candidate_transactions and any ambiguity about what action is performed is eliminated. It even specifies the return payload.

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 usage context: it uses 'the same dated rate find_candidate_transactions matches with' and explains how the target and tolerance parameters are meant for checking bill balances within the 3% cross-currency matching band. It does not explicitly state when not to use the tool or name a direct alternative, but the context is sufficient for an agent to select it for conversion checks.

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 provide readOnlyHint=false and destructiveHint=false, and the description's 'create' action aligns with these. The description also clarifies the nature of the account (ledger vs bank), which helps set expectations. No contradictions or hidden side effects are described, which is appropriate given the simple create 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 two sentences, front-loaded with the core purpose and immediately providing the key differentiation from a bank account. There is no redundant text or unnecessary detail—every sentence earns its place.

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

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

The description provides sufficient context for a create operation: what it creates, what it is not, and where to go for the alternative. Since there is no output schema and the input schema is fully documented, no further context is needed at the tool level.

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 covers 100% of the 14 parameters with descriptive text, including examples (e.g., role: 'tax', 'taxprovision', 'salestax') and explanations of nested relationships (parentid, defaultid). Since schema coverage is high, the baseline is 3, but the parameter descriptions are detailed and add practical meaning, justifying a 4.

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 tool's purpose: 'Create a new chart-of-accounts ledger account' and distinguishes it from a bank account. The verb 'create' and resource 'account' are explicit, and the clarification about it not being a bank account removes 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?

The description explicitly says 'Not a bank account — for that use create_bank_account,' which directly guides the user away from misuse and points to the correct sibling tool. It does not explicitly mention when to use this tool over update_account, but the creation context is clear enough for a write operation.

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 non-destructive write, and the description adds transparency by noting that the 'amount' field is ignored and that legacy link fields should be avoided in favor of dedicated endpoints. This gives the agent a realistic expectation of 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 a single well-structured paragraph that leads with the core purpose, then gives usage context and clarifies legacy vs. preferred fields. It avoids redundancy and is appropriately sized for the tool's complexity.

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

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

Given the absence of an output schema, the description sufficiently covers what the tool does and key behavioral nuances (disposal, depreciation defaults, legacy fields). It doesn't enumerate every parameter, but the schema does, so the combination is complete.

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

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

All 18 parameters have descriptions in the schema, and many include additional semantic context (e.g., depreciation type examples, default for disposeddate, decimal format for rate). This goes beyond basic parameter listing, helping the agent choose 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 clearly states the tool creates a new fixed asset, elaborates on what qualifies as an asset, and distinguishes it from update/delete operations. It also explains the core behavior of linking to the originating expense for cost basis.

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 guidance on when to use the tool (recording a capital purchase to depreciate) and references alternative endpoints for unlink operations. It could be slightly more explicit about not using it for non-capital expenses, 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 indicate this is a mutation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the semantic distinction of being a real money-movement account, but does not disclose any additional behavioral traits such as side effects, reversibility, or required fields for a successful creation. Given the annotations cover the safety profile, the description adds modest value but could have mentioned that creation is a write operation that persists an account.

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

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

The description is a single, well-crafted sentence that front-loads the core purpose ('Create a new bank account for the business') and immediately follows with the critical distinction ('Not a chart-of-accounts ledger account'). Every word earns its place, with no fluff or repetition. Excellent conciseness.

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 20 parameters and no output schema, the description provides minimal guidance on how to use the tool effectively. It doesn't outline typical creation flows, which fields are commonly required (even though none are marked required), or what the response contains. The schema descriptions are thorough, but the overall context for an agent—such as whether openingbalance is needed for reconciliation or how confirm interacts—is missing. The description could have summarized typical usage or mentioned that it returns the created account details. It is adequate but not complete for such a complex tool.

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

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

Schema description coverage is 100%, so the schema already documents all 20 parameters in detail. The description does not add any parameter-specific meaning beyond the schema. Per the rubric, the baseline is 3 when the schema carries the load; the description adds nothing extra here, so a 3 is appropriate.

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

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

The description clearly states the verb (create) and the resource (bank account), and immediately distinguishes it from a chart-of-accounts ledger account, which is a key differentiator from the sibling tool create_account. This gives an agent precise understanding of what the tool does and what it is not.

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 notes 'Not a chart-of-accounts ledger account,' which steers the agent away from using this for ledger entries. It does not explicitly mention when to use this versus update_bank_account, but the verb 'create' makes that obvious. The context of reconciliation and cashflow also gives a usage signal. Slightly more explicit guidance on when to use it instead of other create tools would push it to a 5.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the basic write-but-not-destructive profile is covered. The description adds useful context about organizing uploaded files, but it does not disclose behaviors like duplicate-name handling, ID generation, or return values. That is acceptable but not exceptional given the annotations.

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

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

Two sentences, no filler. The primary action is front-loaded, and the second sentence provides a valuable routing pointer to update_folder without wasting words.

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

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

For a simple two-parameter create tool with full schema coverage and non-destructive annotations, the description is sufficient. It clearly states the purpose, covers the main alternative, and no critical missing context blocks invocation. A small gap is the absence of return-value or duplicate-handling guidance, but this is not severe for such a straightforward tool.

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

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

Schema description coverage is 100%, so the input schema already fully documents 'name' and 'parentid'. The description adds marginal conceptual context through 're-parent' but does not meaningfully enhance parameter understanding beyond the schema.

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

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

The description uses a specific verb and resource ('Create a new folder') and adds purpose context ('organising the business's uploaded files and documents'). It also distinguishes itself from update_folder by explicitly reserving rename/re-parent operations for that sibling.

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 exactly when to use this tool (creating a new folder) and gives an explicit alternative for existing folders: 'To rename or re-parent an existing folder use update_folder instead.' This leaves no ambiguity about tool selection.

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 important behavioral traits beyond the annotations: it is all-or-nothing (atomic), top-level transactionid links all records while per-item overrides, expense accountid can record a payment against a purchase document, and it returns the new ids. This adds substantial operational context not available from the annotations alone.

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

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

The description is concise, using four sentences to cover the core purpose, usage guidance, key behavioral details, and return value. It is front-loaded with the primary purpose and avoids unnecessary 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?

Given the tool's complexity (nested income and expenses arrays with numerous fields) and the absence of an output schema, the description provides only high-level guidance. It covers atomicity, reconciliation, and payment behavior, but does not address many parameters like currency, amount, or supplier behavior, leaving gaps for an agent to infer from 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 explains the top-level transactionid behavior and the special meaning of expense accountid, but does not elaborate on the income and expenses arrays or other parameters. Since the schema has 0% description coverage for the top-level parameters, the description only partially compensates; many parameters remain unexplained beyond their 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 description clearly states the tool's primary function: creating many income and expense records in one transaction. It explicitly distinguishes this tool from its siblings by stating 'prefer this over repeated save_income / save_expense calls', making the unique 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 description provides explicit guidance on when to use this tool ('prefer this over repeated save_income / save_expense calls') and when not to ('per-item salestax is not supported (use save_expense)'). This gives clear usage boundaries and alternative recommendations.

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 indicate non-read-only, non-destructive; they don't explain side effects. The description fails to disclose that passing an id updates an existing tag, instead implying updates should go through update_tag. This hides actual 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 two sentences and tightly packed: it defines the resource, states the primary use case, and differentiates from update_tag, delete_tag, and set_business_tag without extraneous words.

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

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

The description covers when to use the tool and distinguishes it from similar tools, but it omits the id-based update capability, leaving the tool's full behavior ambiguous and potentially causing an agent to misroute updates.

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

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

Schema coverage is 100%, and each parameter has a clear description. However, the description adds no extra parameter guidance and its create-only framing conflicts with the id parameter's update semantics, limiting the value it adds.

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 clearly states 'Create a tag,' but the id parameter description says 'Present → update that tag; omit → create a new one,' which contradicts the stated create-only purpose and the explicit guidance to use update_tag for existing tags.

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 conditions: use for new labels, use update_tag for renames/recollors, delete_tag for removal, and set_business_tag for business segmentation. However, the schema's id-based update behavior makes the 'use update_tag' guidance misleading because create_tag also supports updates.

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 (destructiveHint, readOnlyHint, idempotentHint), the description adds critical behavior: soft-delete semantics, the default refusal due to linked documents, the force override, and the exact effect (moving to bin). This fully discloses side effects and conditions, exceeding what 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 well-structured and information-dense, but it is slightly longer than strictly necessary, repeating the phrase 'linked (non-deleted) quotes/invoices' and 'so linked documents aren't orphaned' twice. Still, every sentence carries meaningful information, and the structure is clear.

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 there is no output schema, the description adequately covers what the agent needs to know: the action, default behavior, override condition, and an alternative. It lacks only an explicit note about return behavior (e.g., success response), but this is not critical given the tool's simplicity and the sibling 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 schema already covers both parameters (id and force) with descriptions, so coverage is 100%. The description adds context by explaining the force parameter's purpose and the default behavior, though it does not introduce new parameter-specific details beyond what the schema provides. The added context justifies a score above the baseline of 3.

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

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

The description states a specific verb and resource ('Delete a customer by id'), clarifies it is a soft-delete to bin, and explicitly distinguishes itself from delete_clients_bulk by noting matching behavior. This makes the tool's purpose unambiguous and differentiates it from the sibling tool.

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 guidance on when to use the tool (default behavior), when to override with force:true, and when to use an alternative (update_client for archiving). It also explains the consequence of the default refusal (preventing orphaned documents), giving the agent clear decision criteria.

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

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

Annotations already carry destructiveHint=true and idempotentHint=true, so the description adds crucial nuance beyond those flags: soft-delete to bin (reversible deletion), transactional all-or-nothing semantics, and two precise failure prerequisites (unknown ids, linked non-deleted invoices). This is exactly the behavioral context annotations cannot express, particularly the distinction between a soft-delete and a permanent delete.

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

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

Three sentences with zero filler: the core operation and soft-delete behavior are front-loaded, followed by failure semantics, then body format and the alternative tool. Every sentence earns its place by adding information neither the schema nor the annotations contain.

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 bulk operation with annotations covering the safety profile, the description covers the operation, transactionality, failure modes, body shape, and the alternative tool. There is no output schema so the success response is unspecified, and the interaction between idempotentHint and retrying an already-binned client is left unresolved — minor gaps in an otherwise complete definition.

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. It shows the exact body shape '{clients: [{id} ...]}' and clarifies that the single parameter is a list of customer IDs. It could add detail on id format or duplicate handling, but the structure is sufficiently specified for a correct call.

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 multiple customers in one transaction,' which clearly differentiates it from the single-customer sibling delete_client. Adding 'soft-delete to bin' further specifies the operation's nature and scope. An agent can immediately identify what this tool does and how it differs from nearby 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 explicitly routes to the alternative: 'For a single customer use delete_client.' It also provides strong when-not-to-use guidance via the all-or-nothing failure conditions — the request fails if any id is unknown or any customer has linked non-deleted invoices — telling the agent which scenarios make this tool unsuitable. The resource term 'customers' also cleanly separates it from delete_suppliers_bulk.

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 significant behavioral detail beyond annotations: it explains that the document and its settling payments are moved to the bin together, that list_binned shows them, and that restore_deleted brings them back. This enriches the destructiveHint and idempotentHint annotations with concrete outcomes and recovery steps.

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 two sentences with no filler. It front-loads the action and scope, then provides critical behavioral details (reversibility and bin) efficiently. Every sentence earns its place.

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

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

The description fully covers what an agent needs to know to call this tool: the effect (delete and move to bin), the associated payments, and how to reverse it. With no output schema, no return value explanation is needed, and the behavioral details are complete for safe usage.

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

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

With 0% schema description coverage, the description must compensate. It mentions 'by id' but does not elaborate on the id format, source, or any constraints. Since the only parameter is a required string id, the description adds minimal meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action 'Delete a document' and specifies the resource types (invoice, quote, credit note, etc.), distinguishing it from sibling delete tools like delete_document_line and delete_expense. The verb+resource structure is unambiguous.

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

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

The description gives clear context on when to use this tool by noting reversibility and the bin system, implicitly guiding an agent that deletion is not permanent and can be undone via restore_deleted. It does not explicitly list exclusions or alternative tools, but the context is sufficient for typical use cases.

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 flag destructiveHint=true and idempotentHint=true; the description aligns with them and adds useful context by requiring the parent document id to update the right document. It doesn't elaborate on side effects like document totals, but this is acceptable given 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?

Three tight sentences cover the operation, key parameters, and alternative tool. There is no filler or repeated schema content.

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 annotations covering safety and a fully documented schema, this description covers the necessary call pattern, clarifies the practical requirement, and routes to the correct alternative. Nothing critical is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the description doesn't need to document every field. It adds value beyond the schema by emphasizing that id is the line id and quinvoice is the parent document id, and by noting quinvoice is required in practice even though it isn't in the schema's required list.

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

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

The description opens with a specific action and resource: 'Delete a line item from a document (invoice, quote, bill, etc.)'. This clearly distinguishes it from sibling tools like delete_document and update_document_item.

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 agents when not to use this tool: 'To change a line rather than remove it use update_document_item (or update_document_items_bulk for several)'. It also gives the key call requirement to pass quinvoice so the correct document is updated.

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 detailing side effects: permanent and irreversible deletion, no linked-record check, ledger recomputation, and consistency of linked bills/transactions. It also includes the expectation to confirm with the user, which is behavioral guidance. This fully discloses the impact of invoking the tool.

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

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

The description is compact and information-dense, covering purpose, side effects, and usage guidance in three sentences. No redundancy or extraneous details are present. The structure is ideal for an agent to quickly grasp the tool's 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 simple delete operation with one parameter and no output schema, the description provides all necessary context: what it deletes, how it behaves (permanent, recomputes ledger), and the required user confirmation. An agent can safely and correctly invoke this tool based solely on the description, including understanding its impact on linked data.

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

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

The schema has a single required parameter 'id' (string), and the description references 'by id' to indicate what the parameter is. Since the schema already fully covers the parameter definition and the description adds no additional semantic details (e.g., format, source, or validation), 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 clearly states the action ('Permanently delete an expense by id') and distinguishes it from other delete operations by specifying the target resource ('expense'). The scope is unambiguous, and the phrasing immediately tells an agent that this tool removes a single expense record.

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 instructs the agent to 'Confirm with the user before deleting,' which is a critical usage guideline for a destructive operation. It also notes that no linked-record check is performed and that the ledger recomputes to maintain consistency, informing the agent about when this tool is appropriate (direct deletion without collateral checks). However, it does not explicitly compare against alternative delete tools (e.g., delete_income, delete_journal_entry), leaving some inference to the agent.

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

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

Goes beyond annotations by explaining immediate irreversibility, the absence of a linked-record check, the ledger recomputation, and the restoration of a linked invoice's outstanding amount. Also instructs user confirmation.

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

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

Two dense but readable sentences cover the action, consequences, and required user confirmation without unnecessary detail.

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?

Covers the essential side effects and confirmation requirement. No output schema exists, so the lack of return-value detail is acceptable; error cases are not mentioned but are not critical for this 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?

The only parameter, id, is referenced as the income record id. Though the schema provides no field description, the tool description makes the parameter's purpose clear enough for a simple identifier.

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

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

Clearly states the action: permanently delete an income record by id. Distinguished from related tools like delete_expense and save_income.

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 guidance: irreversible, no linked-record check, ledger recomputes, and confirm with the user. Does not name alternative tools like restore_deleted or unlink_income_transaction, but the usage context is still 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?

Discloses irreversibility ('Immediate and irreversible') and the limitation on auto-generated entries, which complements the destructiveHint annotation. The instruction to confirm with the user adds practical behavioral context beyond the annotations.

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

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

The description is concise yet complete, with each sentence adding essential information: action, irreversibility, scope, alternative method, and confirmation requirement. No redundant content.

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 simple single-parameter interface, the description fully covers the operation, its side effects, and the correct usage context. No output schema exists, so no return value description is needed.

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 'id' parameter is described generically in the schema, but the tool description enriches it by explaining the id format 'ent...' for manual entries and contrasting with 'ent-1-inv...' type ids. This gives the agent a clear understanding of what value to pass.

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 the action ('Permanently delete') and the target ('MANUAL journal entry by id'), distinguishing from siblings like delete_document or delete_expense. The scope is explicit 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?

Provides explicit guidance on when to use (manual entries only) and when not to use (auto-generated entries, delete the source document instead). Also instructs to confirm with the user, covering the decision-making process.

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 destructiveHint annotation by explaining that deletion affects every user of the business, acts as a retraction rather than a read state, and is irreversible. This fully discloses the behavioral impact.

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, well-structured, and front-loaded with the core action. Each sentence adds useful information without unnecessary verbosity.

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

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

The description provides sufficient context for safe and correct usage, including the tool's scope, irreversibility, user impact, and distinction from a related non-destructive operation. No critical contextual 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?

The only parameter, id, is already described in the schema as 'Id of the message.' The description adds no additional semantic detail beyond restating that deletion is by id, so it does not improve on the schema coverage.

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 action (permanently delete), the resource (in-app message/notification), and the identifier (by id). It also distinguishes the tool from mark_message_read, making its 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 description explicitly contrasts this tool with mark_message_read and warns that deletion is immediate and irreversible, advising confirmation with the user. This gives clear guidance on when to use it and what caution to apply.

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

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

Adds significant context beyond annotations: permanence, and that document lines retain copies of name/price. This reassures about side effects. 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?

Three sentences, each adding distinct value: the action, the dependency behavior, and the absence of a bulk option. Information is front-loaded with the primary purpose.

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 covers all necessary details: permanence, effect on dependent data, and no bulk alternative. No output schema exists, so no return info is needed.

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 only parameter, id, is referenced as 'by id' in the description, which clarifies its role. Schema coverage is 0%, but the description adequately compensates for a single simple 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?

Clearly states the action (permanently delete) and the resource (product by id). The mention of no bulk variant distinguishes it from sibling bulk-delete 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 states when to use this tool: to delete a single product by id, and notes the absence of a bulk variant, preventing search for a non-existent sibling.

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 the tool as destructive and idempotent, and the description adds important behavioral details: soft-delete to bin, refusal when non-deleted links exist, and force override semantics. This gives the agent a clear picture of side effects beyond the annotation flags.

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, with the main action stated first and behavior details efficiently packed into two sentences. No redundant or filler content 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?

Given the moderate complexity of a delete operation, the description provides sufficient context: default behavior, override, soft-delete destination, and the archive alternative. The lack of an output schema is not a gap because the operation's expected side effects are clearly described.

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 covers both parameters fully, so the baseline is high. The description adds meaningful context beyond the schema, especially for force, explaining the default false behavior and the reason linked expenses aren't orphaned, which helps the agent choose the correct value.

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 action: delete a supplier by id with soft-delete behavior. It also distinguishes this tool from the bulk delete and save/archive alternatives by naming delete_suppliers_bulk and save_supplier explicitly.

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

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

The description explains when to use this tool versus alternatives, referencing the bulk counterpart and the archive via save_supplier. It also clarifies the default refusal behavior with linked bills/expenses and how to override it with force:true.

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 destructive and idempotent. The description goes further by disclosing that deletion is a soft-delete to bin, that the operation is transactional and all-or-nothing, and exactly which conditions trigger failure. This is rich behavioral context beyond the annotations with 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?

Three sentences with zero filler. The core purpose and semantics are front-loaded, the body format follows, and the sibling alternative is given last. Every sentence earns its place.

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

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

For a one-parameter destructive operation with no output schema, the description covers all necessary behavioral aspects: soft-delete, transaction semantics, failure conditions, body shape, and the single-supplier alternative. An agent can invoke this tool correctly without needing 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?

The input schema has 100% coverage: the 'suppliers' array and each item's required 'id' are fully documented. The description's 'Body: {suppliers: [{id} ...]}' essentially restates the schema structure without adding new semantic detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Delete multiple suppliers') and the scope ('in one transaction'). It also explicitly differentiates from the single-supplier sibling: 'For a single supplier use delete_supplier.' No ambiguity about what this tool does.

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 says when to use this tool versus delete_supplier, naming the alternative and the condition that selects it. It also states important usage constraints: all-or-nothing behavior, failure on unknown IDs, and failure when linked expenses exist. This leaves no inference to the agent.

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 explicitly states the deletion is permanent and irreversible, which fully discloses the destructive nature of the operation. This aligns with the destructiveHint annotation and provides clear expectations to the agent.

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

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

The description is succinct, with no unnecessary words. It conveys all essential information in two sentences, making it easy to parse and understand quickly.

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 the key aspects: what happens (permanent deletion), the scope (everywhere applied), and the safety precaution (confirm with user). It does not mention return values or additional side effects, but for a simple delete operation, this is sufficient. A minor gap is that it doesn't specify what happens if the tag does not exist, but that is not critical.

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 only parameter 'id' is minimally described in the JSON schema (type string) without additional context in the description. Since the schema already covers the existence and type of the parameter, the description adds no extra semantic meaning, so a 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 clearly states the action (delete), the resource (tag), and the scope (removed everywhere it is applied). It distinguishes itself from sibling tools like create_tag and update_tag without needing to reference them.

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

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

It explicitly advises confirming with the user before deleting, which is a critical usage guideline for destructive operations. This tells the agent when and how to invoke the tool safely.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description reinforces those with 'Permanently delete' and 'This cannot be undone.' It adds a clear irreversibility warning that aligns with, and slightly extends, the structured annotation information.

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

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

The description is a single sentence that front-loads the core action, then adds the permanence warning and the save_variant alternative. Every word 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?

The description covers the main delete semantics and the annotation profile handles safety, but the unresolved id/productid requiredness conflict is left unaddressed. Since there is no output schema, a brief hint about the expected result or confirmation would also improve completeness.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds no parameter-level meaning beyond saying 'by id.' The schema itself contains an odd 'Required in practice' note for id while productid is the only required property; the description does not resolve this ambiguity.

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 the specific verb 'delete', the resource 'product variant', and the identifier ('by id'), and adds 'Permanently' to set expectations. It is clearly distinct from save_variant and other delete_* 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?

It explicitly directs the agent to use save_variant instead when the goal is to create or edit a variant, while framing this tool as the permanent deletion path. This provides an actionable routing rule and a caution about irreversible consequences.

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 valuable behavioral context: snapshot evaluation is immutable, live evaluation reads current books, and constants coercion behavior is disclosed ('Undeclared here, coercion would strip them and the formula would silently evaluate with 0'). This goes beyond what annotations provide, though it doesn't enumerate every possible side-effect (none expected for a read).

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 dense but well-organized: it leads with the primary purpose, then breaks down templates vs. views, then addresses snapshot vs. live. Every sentence contributes useful information, and the examples are concise. It is long, but the complexity (16 parameters, two modes) justifies the length. There is 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's complexity (16 parameters, no required fields, no output schema), the description covers most essential aspects: it explains both evaluation modes, the snapshot behavior, and gives concrete examples of what several views return. It also hints at the output's downstream use ('feeds stub-web's screens render'). However, it does not specify the exact response structure or error conditions, which would be needed for a fully self-contained definition.

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 88%, so most parameters are documented in the schema. The description adds semantic value beyond the schema: it explains the meaning of `view` values with concrete output examples (payables returns every outstanding bill...), clarifies the `source` format, and details the `snapshotid` behavior. It also provides context for `constants` and `mode` that enriches the bare schema 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 opens with a clear, specific statement of what the tool does: 'Resolve a report template OR an insight view against a period.' It explicitly distinguishes two modes (template vs. view) and further differentiates frozen vs. live evaluation, with concrete examples for both. This is far more specific than the tool name and leaves no ambiguity about the tool's core function.

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 strong usage context: it explains when to use a template (statutory or stored) vs. a view, and the frozen vs. live distinction with snapshotid. It also notes the mutual exclusivity of `view` and `template`/`source` ('Provide this OR a template, not both'). However, it does not explicitly contrast with sibling tools like evaluate_report_batch or evaluate_report_session, so the guidance stops short of naming 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?

Beyond the readOnlyHint annotation, the description discloses that the tool requires an open session, that errors are returned inline per slot, and that it leverages a single session dataset build to reduce round trips. These are important behavioral details not present in 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 concise and well-structured, starting with the core capability, then parameter details, then usage guidance. It avoids unnecessary filler and communicates everything needed in a compact format.

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 all necessary context: the batching capability, the parameter structure, the response behavior (what each results slot contains), the session prerequisite, and alternatives for single or one-off evaluations. Despite lacking an output schema, the description sufficiently explains the expected result format, making the tool fully usable.

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 elaborates on the 'requests' parameter, specifying the structure of each item: '{view|source|templateid, periodStart?, periodEnd, ...}'. This adds crucial semantic information that the schema alone (which only says 'items: type object') does not provide, making the parameter fully understandable.

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 that the tool evaluates up to 24 report templates/views in a single round trip, using specific terms like 'evaluate', 'templates/views', and 'session dataset build'. It also distinguishes itself from sibling tools by mentioning the batch nature and session requirement.

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 provides when to use this tool versus alternatives: 'for a single view use evaluate_report_session, or evaluate_report for a one-off outside any session.' It also states the prerequisite 'Requires an open session (open_report_session first)', giving clear guidance on usage conditions.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavior beyond that: it operates on the cached dataset, runs in tens of milliseconds, and is limited to live books. This discloses the mechanism and a key limitation without contradicting 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?

Two sentences carry a dense but well-organized amount of information. The core behavior and performance distinction are front-loaded, and the second sentence covers interactive use and the frozen-period alternative. There is no filler or redundancy.

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

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

For a 15-parameter tool with no output schema, the description covers purpose, speed, and usage boundaries well. However, it never explains how the report session is identified—there is no session parameter in the schema—and periodEnd is marked Required in its parameter description while the schema says required: []. These gaps could confuse an agent deciding how to invoke 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 73% and most parameters already have meaningful descriptions, so the description does not need to re-explain them. It adds context that template/source and view are alternatives and that evaluation uses cached data, but it does not fill gaps for undocumented parameters like version, constants, templateid, and periodStart. Baseline 3 is appropriate.

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

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

The description states a specific action and resource: evaluating a template or insight view against a period from the report session's cached dataset. It also distinguishes itself from /report/evaluate by noting identical answers but much faster execution. An agent can clearly understand what this tool does and how it differs from its sibling evaluate_report.

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 this is for interactive use cases such as period slides, template/view switches, and constant tweaks. It also gives a clear exclusion: frozen periods should use /report/evaluate with snapshotid. This names the alternative and the condition for choosing it, leaving little to inference.

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

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

Although the annotation readOnlyHint=true already indicates the tool does not modify data, the description adds critical behavioral context beyond that: it explicitly states 'READ-ONLY: it suggests a match and the adjusting line, never records either' and explains the implications of cross-currency matches (requires_confirmation=true, FX gain/loss handling). This provides valuable transparency that helps the agent understand side effects and constraints, going beyond the 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 comprehensive but somewhat long. It front-loads the key purpose and criteria, then provides detailed output structure and behavioral notes. While every sentence adds value, the description could be tightened by removing minor redundancies (e.g., repeating the read-only theme). However, it is well-structured and not wordy enough to be penalized heavily.

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 (returns candidates, best match, proposal, handles FX, requires confirmation), the description is remarkably complete. It explains the output structure, confidence thresholds, the proposal types, and the conditions for each. It also covers edge cases (indeterminate FX rate) and example usage. The agent has all necessary information to call and interpret results correctly, and the absence of an output schema is compensated by the description's detailed return format.

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 the parameter documentid with 100% coverage. The description reinforces the format (cont-… or inv-…) and explains what the id represents (invoice/bill/purchase document). While it doesn't add entirely new information beyond the schema, it contextualizes the parameter within the tool's logic, adding slight value over the schema alone.

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

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

The description clearly states the tool's purpose: to surface candidate bank transactions that could settle an outstanding or overdue invoice or bill. It specifies the exact criteria (OPEN transactions within ±7 days, amount matches outstanding balance) and distinguishes it from related tools like settle_bills and record_document_payment, making it 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 provides explicit guidance on when to use this tool: 'Run this whenever you report an overdue/outstanding invoice or bill so the likely payment is offered alongside it.' It also states what the tool is not for (it is read-only and does not record matches, implying use of settle_bills for bills or record_document_payment for invoices) and gives the required input format (document id). This effectively differentiates it from 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?

Beyond the readOnlyHint annotation, the description reveals key behaviors: the call never records matches, it is capped at limit with default 50 and hard max 200, it reports truncated and matched counts, it silently drops foreign/missing ids, and filter fields are ignored when documentids is given. This is rich, useful behavioral disclosure and is consistent with the 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 long but appropriately structured: purpose, selection modes, limits/truncation, return shape, and side-effect disclaimer each earn their place. For a complex tool with 10 optional parameters and no output schema, the density is justified and the core 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?

With no output schema, the description supplies the full return envelope including results, count, matched, truncated, and limit, as well as the paging/narrowing behavior. It also clarifies the read-only nature and names sibling settlement tools, so an agent has everything needed to invoke it correctly and 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantic context by framing documentids vs the list_documents filter set as alternative selection modes and by providing a concrete example combination like type=bill + unpaid + status=overdue. This goes slightly beyond the schema's individual parameter 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 'BULK / multi-document version of find_candidate_transactions' and explicitly states it returns each document with candidate settling bank transactions and best match in one read-only call. This clearly names a specific verb, resource, and scope, and distinguishes it from the single-document sibling tool.

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 says when to use the tool: for many outstanding documents or a large AP/AR backlog where one call replaces one round-trip per bill. It also explains the two selection modes and explicitly routes settlement actions to settle_bills or record_document_payment, making the boundary with alternatives obvious.

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 explicitly stating the tool does not pull transactions, does not make live external calls for bankfeeds, and returns an explanatory message rather than an error when no bank connection exists. This fully sets expectations for side effects and error behavior, making the tool's behavior transparent.

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

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

The description is a single detailed sentence but includes some redundancy (e.g., listing providers and bankfeeds twice with similar wording). It is not overly long, but the repetition of 'bank feed' variants could be trimmed. Overall, it is clear and front-loaded with the core purpose, but slightly redundant in the specifics.

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

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

With no parameters and no output schema provided, the description must convey all necessary context. It does so thoroughly: it names the two return fields, explains their sources (live vs. derived), clarifies the no-transaction/no-live-call behavior, and explicitly states the edge-case outcome (message, not error) when no bank connection exists. This is fully complete for an agent to know when and how to invoke 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?

There are zero parameters, matching the empty schema with full coverage. The description correctly implies no input is required by explaining what the tool returns with no configuration. Since there are no parameters to document, the baseline of 4 is exceeded by the clear statement that no input is needed and that the tool operates on the business's existing profile.

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 tool reports the business's bank-connection profile and explicitly excludes pulling transactions. It specifies the two return categories (providers and bankfeeds) and their distinct characteristics, making the tool's purpose unambiguous. The name 'get_bank_profile_status' is descriptive and the description reinforces its role as a status-only reporter.

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 useful guidance by indicating no transactions are pulled and that bankfeeds are derived from stored state with no live external call. This hints at when to use the tool (e.g., for a lightweight status check). However, it does not explicitly compare to sibling tools like refresh_business_data or other getters, so it's slightly less explicit than ideal.

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, covering the safety profile. The description adds useful behavioral context by revealing that this is a bundling call rather than a distinct data source, but it does not describe response shape, pagination, or any aggregation caveats. The added value is moderate but not extensive.

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

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

Two concise sentences with no filler. The core bundling behavior is front-loaded, and the alternative usage is stated efficiently in the second 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 zero-parameter read-only composite tool, the description sufficiently captures what the call returns and when to use it. The absence of an output schema means a bit more detail about the financial summary or usage context could be helpful, but the current level is adequate 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?

The tool has zero parameters and the schema is empty, so there is no parameter semantics gap to fill. The description accurately reflects the no-input nature; no additional parameter explanation is needed.

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 tool returns a composite overview: profile + financial summary + feature/usage context. It also explicitly names the two sibling tools it bundles, so an agent can immediately distinguish it from get_business_profile and get_financial_summary.

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 guidance: call this tool when you need the combined overview, and call the individual sibling tools when only one part is needed. This directly answers the when-to-use-versus-alternatives question.

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 establishes that this is a read-only operation. The description adds valuable behavioral context by stating that financials are not included, setting expectations about the response scope beyond what the annotation conveys. 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?

Two concise sentences with no redundancy. The core purpose is front-loaded, and the exclusions and alternatives are stated efficiently in the second sentence. Every clause earns its place.

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

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

For a zero-parameter, read-only tool with no output schema, the description is complete: it lists what the response contains, explicitly notes what it excludes, and names the exact sibling tools for related use cases. An agent has enough information 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?

The tool has zero parameters, and the schema confirms no required or optional parameters. With no parameters to document, the description does not need to add parameter-level semantics; the baseline for zero-parameter tools is appropriate here.

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 identifies the tool as retrieving the business's own profile and enumerates its contents (name, contact details, industry, currency, tax rate, plan). It explicitly distinguishes itself from get_financial_summary and get_business_overview, so an agent can tell them apart without inspecting other definitions.

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 usage guidance: financials are excluded, and the agent is directed to get_financial_summary for financials alone or get_business_overview for both profile and financials in one call. This clearly communicates when to use this tool versus the 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?

With readOnlyHint=true already in annotations, the description adds value by detailing what the returned document includes (totals, status, line items, contact, money direction) and clarifying the range of accepted ids across document types. This goes beyond the annotation and helps set expectations for the response content.

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 two sentences with no wasted words. The core action and returned fields are front-loaded in the first sentence, and the second sentence clarifies the input scope efficiently.

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 single-parameter read tool with no output schema, the description discloses the key return fields and the full range of acceptable ids. It does not mention error cases or auth, but these are not critical for correct invocation given the read-only annotation and simple input.

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 only describes the id as 'Document id', while the description adds meaningful semantics: it accepts any business-owned document id, including invoice, quote, and credit-note ids from list_documents and list_invoices. This is useful guidance beyond the 100% schema coverage.

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 one document by id'), lists the returned fields (totals, status, line items, contact, money direction), and distinguishes itself from list_documents/list_invoices by clarifying it accepts the ids those tools 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?

It gives clear context on the accepted scope ('any document id this business owns') and points to list_documents and list_invoices as sources of valid ids, which implicitly signals when to use this tool. However, it does not explicitly state when to prefer alternatives over get_document, such as using list_documents for bulk retrieval.

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 annotation readOnlyHint=true and the verb 'get' make the read-only nature clear. The description also discloses that it returns failure reasons when applicable, providing transparency about the kind of data returned without suggesting 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 a single focused sentence that front-loads the purpose and lists the returned fields without unnecessary detail. It is concise and well structured.

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

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

With no output schema present, the description compensates by enumerating the key output fields (subject, recipients, time sent, time received, and failure reason). This gives an agent sufficient context to know what to expect from the call.

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 fully describes the single id parameter as the identifier of the email history record. The description merely repeats 'by id' and adds no additional semantic detail beyond the schema, so the baseline score 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 clearly states the action (get one sent email's history record), the lookup method (by id), and the specific fields returned (subject, recipients, time sent, time received, failure reason). This is distinct from list_emails, which lists emails rather than fetching a single history record.

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 when a single email history record is needed by id, but it does not explicitly contrast with list_emails or other email-related tools. Guidance is present but only implicit.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds meaningful behavioral scope: it reports monthly aggregates, specifies included financial categories, and states that profile details are excluded. This goes beyond the annotation without contradicting it.

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

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

Two sentences with no filler: the first sentence front-loads the resource and key contents, and the second provides exclusions and routes to alternatives. Every part earns its place.

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

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

For a parameterless read-only tool with no output schema, the description is complete enough: it says what data is returned, what is intentionally omitted, and which sibling tools cover the omitted data. An agent can select and invoke this tool correctly without needing more 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 tool has zero parameters and the schema is empty, so there is no parameter documentation burden. The baseline 4 for parameterless tools applies, and the description appropriately focuses on output scope rather than parameters.

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

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

The description names a specific resource (financial summary) and a clear verb ('get'), then enumerates the exact contents: per-month earnings, profit, cashflow, expense/income rollups, and inventory movement. It also explicitly differentiates itself from get_business_profile and get_business_overview, so an agent can distinguish it from nearby 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 description explicitly states what this tool does not include ('Profile details are not included') and names the alternatives: get_business_profile for profile details and get_business_overview for both in one call. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so 'Read-only' is largely redundant, but the description adds real behavioral context: the entitlement gate that suppresses non-entitled guides and the fact that the result is a set of steps. It does not describe error behavior for a non-existent or unentitled id, which is the remaining gap.

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

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

Three short sentences, front-loaded with what the tool does, then the read-only note, then the precondition. Nothing is padded or restated.

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 tool with an annotation covering safety and no output schema, the description is nearly complete, and 'steps of a single guide' conveys the return shape. It stops short of saying what a failed lookup yields, a minor omission.

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

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

Schema coverage is 100% and the id property already carries an example and the 'as returned in a list_guides row' note, so the schema does the heavy lifting. The description reinforces the provenance of the id but adds no new syntax or format detail beyond 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?

It states a specific verb (Get) and resource (the steps of a single guide) with a clear scope qualifier (by its id). This cleanly distinguishes it from list_guides, which enumerates rather than fetches one guide's steps.

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 agent to call list_guides first and to only request an id that list_guides returned, and it names the failure mode (an unentitled guide is not returned). The sequencing and exclusions are fully specified.

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 annotation declares readOnlyHint=true, and the description does not contradict this. It mentions reading from live or snapshot sources, but does not add additional behavioral details like rate limits or side effects, which is acceptable given the 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 two sentences, front-loads the primary purpose, and uses precise domain terminology. It is concise and well-structured.

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 lists the expected data fields (bucket, direction, capital, etc.) and mentions pagination implicitly via the schema's cursor/limit parameters. It does not describe the output format explicitly, but given the tool's simplicity and the schema coverage, it is sufficiently complete.

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

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

The schema descriptions already thoroughly explain each parameter (e.g., periodEnd is required for live, defaults for snapshot). The tool description adds little beyond a conceptual 'flow filter' reference, but does not improve on the schema's clarity.

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 it returns per-entry sales-tax classifications for a period, and emphasizes it is the single feed every tax report reads. It also distinguishes live vs snapshot modes, making the 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?

It explains that it serves as the single feed for tax reports, and clarifies when to use live books (via period filters) versus a snapshot (via snapshotid). It does not explicitly compare to sibling tools, but the guidance is sufficient for typical use cases.

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 readOnlyHint annotation by explaining what data is contained, including carry-forward/variant/detail codes, personal deduction rules, and trade source-code rules. It also reveals behavioral traits like stability and business-independence, which supports caching and repeated reuse. 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 a single dense sentence that front-loads the core purpose and then enumerates the specific table contents without filler. It is longer than average, but the density is justified by the richness of the data being described; only modest restructuring would improve scannability.

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

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

For a read-only reference lookup with one optional parameter and no output schema, the description is complete: it states what data to expect, the country scoping, the stable read-once usage guidance, and the specific sub-categories the agent will encounter. 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?

The input schema fully documents the single optional country parameter, including its default behavior. The description reinforces the locale-related scope with the ZA example but does not add substantial meaning beyond what the schema already states, so the baseline score of 3 applies.

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

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

The description defines the tool's exact resource: the statutory source codes a locale's returns print, with a concrete example (ZA ITR12) and enumerated sub-tables such as the 4000-series Other Deductions table and rental profit/loss codes. This level of specificity makes it unambiguous even among many 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?

The description gives clear usage guidance: this is reference data that is business-independent and stable, so it should be read once rather than per report. It does not explicitly name alternatives or describe when not to use it, but the guidance provided is actionable and relevant.

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 indicates no side effects, and the description does not contradict that. No additional behavioral details, such as return shape or error behavior, are disclosed, but none are strictly required given the simple read-only nature.

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 includes useful sibling guidance, but the phrase 'stub subscription' and 'pay stub for' is awkward and reduces clarity. The wording could be tightened without adding 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?

The description conveys the tool's main purpose and mentions related tools, which is helpful given there is no output schema. However, it does not clarify what the returned subscription data would include or what 'stub' means in this 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 tool has no parameters, so there is nothing for the description to clarify. Per the baseline for zero-parameter tools, this is adequate.

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 identifies the tool as retrieving subscription/billing line items for the business. It also distinguishes it from related profile and financial-summary tools, though the repeated use of 'stub' makes the wording somewhat confusing.

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 directs users to get_business_profile for profile data and get_financial_summary for trading financials, providing useful when-not-to-use guidance. It only implies when to use this tool, but the purpose statement makes that 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?

The annotation readOnlyHint=true already covers the read-only nature. The description adds that it returns specific member fields but does not mention any additional side effects, authentication, or rate limits. Given the annotation, the bar is lower, and this is sufficient.

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

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

The description is a single, precise sentence with no extraneous information. It is well-structured and front-loaded with the main action.

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

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

With no output schema, the description names the key fields returned (name, email, role, active status), which is adequate for basic usage. It could optionally mention whether it returns all members or only active ones, but it is not a significant gap.

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

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

The tool has zero parameters, so there is nothing to explain beyond what the schema shows. Baseline score of 4 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 clearly states it retrieves the business's team or members with specific fields (name, email, role, active status). It is distinct from other tools by focusing on the team roster.

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 explicit guidance on when to use this tool versus alternatives. While the name and description imply it is for fetching team information, it does not state conditions or preferences.

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 mark this as non-read-only and non-destructive, but the description discloses meaningful behavior: it is atomic, it restores soft-deleted entries rather than duplicating them, it only creates a fresh entry when none existed, and it is idempotent on retry. This is exactly the kind of side-effect information an agent needs beyond structured fields.

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

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

Three sentences deliver the purpose, the core behavioral guarantee, and retry safety without repetition or fluff. The most important information is front-loaded in the first sentence. Every sentence earns its place.

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

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

For a single-parameter invocation with no output schema, the description covers what the tool does, what happens to existing entries, when a new entry is created, and retry semantics. An agent has enough information to decide whether to call it and to predict the outcome of doing so.

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

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

There is only one parameter, ids, and the schema already covers it completely with a description. The tool description adds context about the bulk/atomic nature but not new detail about the parameter itself. Since schema description coverage is 100%, the baseline 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 begins with a specific verb and resource: 'Include (un-ignore) many bank transactions in one atomic call.' It further clarifies by naming its relationship to exclusion and explaining the intended effect on transactions. This makes the tool's purpose unambiguous and distinguishable from the broad sibling list.

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 communicates that this tool is for including previously excluded transactions and that it is the inverse of excluding them. It also explains safe-to-retry behavior, which gives the agent practical usage context. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full alternative routing.

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

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

The description adds a useful behavioral detail (fails cleanly on missing records) beyond the annotations. However, it does not mention whether the operation is idempotent, whether it overwrites existing links, or any other side effects, so transparency is partial.

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 very concise, consisting of two sentences with the core purpose stated first and a relevant failure behavior second. No superfluous content is present, and the structure is effective.

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 four-parameter mutation with no output schema, the description adequately covers the main behavior. It mentions the failure case, but omits details about success return values or constraints on supported pairs (beyond examples), which could be useful but are not critical.

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 provides descriptions for all four parameters (100% coverage), and the tool description does not add significant extra meaning beyond the schema text. The examples in the description (e.g., 'income+transaction') give some context but don't materially enhance parameter understanding.

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 action ('Link two entities') and provides examples of supported pairs, making the purpose understandable. However, it does not explicitly distinguish itself from the sibling tool 'unlink_entities', relying on the verb alone to convey the opposite 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?

It implies usage for creating links between entity pairs and notes the failure behavior, but does not explicitly state when to prefer this over alternatives (e.g., unlink_entities) or mention any preconditions beyond existence of the records.

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 safety profile is covered. The description adds useful behavioral context by clarifying that this tool returns mappings rather than account balances, which is not evident 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?

Two short sentences with no filler. The core definition comes first, and the sibling distinction is provided in the second sentence. Every word earns its place.

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

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

For a zero-parameter, read-only list tool with no output schema, this description is complete. It tells the agent what is returned and how to get the alternative resource, leaving no important gap.

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

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

The tool has zero parameters, so parameter semantics are not a concern. The baseline for zero-parameter tools is 4, and the description adds no irrelevant parameter information.

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 identifies the resource precisely ('chart-of-accounts category-to-account mapping') and explicitly distinguishes it from list_accounts. It lacks an explicit verb in the body, but the tool name supplies 'list', so the purpose is unambiguous.

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

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

The description names the sibling tool list_accounts and states the condition for choosing it instead ('accounts themselves (with balances)'). This gives the agent clear when-to-use and when-not-to-use guidance.

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

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

The readOnlyHint annotation already covers the safety profile, so the description doesn't need to repeat that. It adds scope details (full chart, linked bank accounts, names and balances) but does not disclose additional behavioral traits such as authentication needs, rate limits, or pagination behavior beyond what the schema already documents.

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

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

Two short sentences, front-loaded with the tool's purpose and followed by a targeted alternative. Every sentence earns its place and there is no repetition of schema or annotation information.

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

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

For a read-only list tool with a fully documented schema, the description is complete: it defines the scope, notes included data, and routes to the relevant sibling. Nothing needed to call the tool correctly is missing.

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

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

Schema description coverage is 100%, so every parameter is already described in the input schema. The description adds no parameter-level meaning beyond that, which matches the baseline of 3.

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

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

States a specific action ('List') on a specific resource ('accounts') and defines the result as 'the full chart of accounts including linked bank accounts (names and balances).' It also explicitly distinguishes itself from the sibling tool list_account_mappings.

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?

Names the alternative tool (list_account_mappings) and the exact condition where it should be used instead ('For the category-to-account mapping'). This gives clear routing guidance and leaves little to inference.

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

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

The description aligns with the readOnlyHint annotation and makes no conflicting claims; it adds context that the tool is a public store but does not describe side effects beyond the 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 compact, focused, and front-loads the core purpose and distinction from installed apps without unnecessary detail.

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?

It describes what the tool returns (each app's id, name, description, category, region, and connection config) and clarifies its scope, making it complete for a parameterless read-only listing 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?

The tool has zero parameters, matching the schema; with no parameters there is nothing to explain, so the baseline of 4 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 clearly states the tool lists the public catalogue of integrations (apps) a business can connect, identifies the included fields, and explicitly distinguishes it from installed apps.

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 a clear when-not-to-use by stating this is the public app store, not the business's installed apps, but does not explicitly name an alternative sibling tool.

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

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

Annotations already declare `readOnlyHint: true`, and the description adds the further behavioral detail of deletion-time ordering, plus the non-obvious edge case that payments associated with a deleted document are hidden from this listing and only reappear after restore. It does not contradict the annotation and adds useful semantic behavior beyond 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 two sentences: the first front-loads the main action and scope, the second adds the crucial edge case. There is no filler, and every clause adds information directly useful to deciding and invoking the tool.

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

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

For a zero-parameter, read-only list operation without an output schema, the description covers everything an agent needs: what is listed, what is excluded, and the ordering. The payment caveat also prevents a realistic misunderstanding about what shows up in the result set.

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

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

The tool has zero parameters, so there is nothing for the parameter schema to explain. The absence of any parameters is accurately reflected by the empty `properties` object, and the description does not need to elaborate on parameter usage.

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

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

The description states a specific verb ('List') and a precise resource ('binned soft-deleted records'), then enumerates all covered record types and specifies sorting ('newest deletion first'). It clearly distinguishes this list tool from brothers that list active records (list_invoices, list_clients, etc.) by its exclusive focus on binned items.

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 a clear context: use this to see binned records for the business, and it adds an important functional caveat that binned document payments are not separately listed but will be restored with their document. It does not explicitly name alternatives like `restore_deleted` or state 'when not to use it', but its purpose itself implies the use case.

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 adds valuable behavioral context: archived customers are included and carry 'archived: true', with the note that archiving hides nothing server-side. This clarifies a potentially surprising behavior. The description also implies pagination via schema but doesn't repeat it. Overall, it adds meaningful behavioral disclosure beyond the 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 two sentences with no fluff. The core purpose is front-loaded, and the archive behavior is succinctly appended. Every word adds value; there is no redundancy or irrelevant detail.

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 5 parameters and no output schema, but the schema itself thoroughly documents each parameter. The description covers the main output fields and the archive behavior. It doesn't explain the return structure (e.g., pagination fields) but the schema does, so the description is adequately complete for an agent to call it correctly. Minor gaps like mentioning the default limit are already in the schema.

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

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

Schema coverage is 100%, meaning all parameters (to, from, limit, query, cursor) have detailed descriptions. The tool description itself does not add further parameter semantics beyond what the schema provides. Per calibration, high coverage leads to a baseline of 3, and the description does not need to compensate.

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 action ('List'), the resource ('customers'), and the specific fields returned (id, name, email, invoiced/outstanding totals). It distinguishes itself from sibling tools like list_suppliers or list_accounts by explicitly naming 'customers' and the business context. The archive behavior is also clearly noted, adding specificity.

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 state when to use this tool versus alternatives (e.g., list_suppliers, list_invoices). It provides context about including archived customers but offers no guidance on when this tool is preferred or when another list tool should be used. The purpose is clear, but there's no explicit routing 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?

Beyond the readOnlyHint annotation, it discloses pagination behavior (50 per page, 200 max), newest-first ordering, the meta.total/truncated pitfall, and that it reads both document stores. It also explains that rows carry totals/outstanding/status fields, which matters because there is no output schema.

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

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

Although long, every clause earns its place: purpose first, then the pagination warning, filters with examples, row fields, and the handoff to get_document. The potential wall-of-text is justified by a 12-parameter tool and is front-loaded with the most important caveat.

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 list tool with no output schema, it covers pagination, filter combinations, ordering, row contents, and the alternative for full detail. Nothing needed to call the tool correctly or interpret the response is missing.

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

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

Schema coverage is 100%, so the baseline is already strong. The description adds value by grouping the filters, clarifying the query substring semantics, and giving ready-made combinations. It doesn't go deep on every parameter, but the schema already handles those details.

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 the verb ('List') and the exact resource ('the business's documents'), enumerates every document type, and asserts it is the complete authoritative surface reading both document stores. This also distinguishes it from narrower list tools such as list_invoices and from get_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?

It gives explicit routing guidance ('Use get_document for one document's full detail') and concrete composition examples (type=bill + unpaid + status=overdue, or type=invoice + query=<ref>). It does not explicitly name the 'when not to use' cases for sibling list tools like list_invoices or search_combined, but the 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 readOnlyHint annotation, the description discloses behavioral traits: default 30-day time window, override via days/from-date, sorting newest first, filtering by status/kind/entity, and cursor pagination. This adds meaningful operational context without contradicting 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 three sentences, front-loaded with the core purpose, and every sentence adds functional detail (ordering, time window, filters, pagination). No wasted words.

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

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

With 9 optional parameters and no output schema, the description provides a solid overview including defaults and pagination. It does not describe the exact return format, but that is typical for list tools and the schema covers parameter details. Slightly more on response shape would push it to 5.

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

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

Schema coverage is 100%, so parameters are individually documented. The description adds value by clarifying relationships: the 30-day default overridden by days/from-date, and cursor for pagination. This is beyond the schema's per-parameter 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 clearly states the action (list) and the resource (emails the business has sent), with specific details on ordering (newest first) and included data (delivery state and times). This distinguishes it from sibling list tools like list_invoices or list_documents, and from get_email for single records.

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 on when to use the tool: to list sent emails with filtering and pagination. It does not explicitly name alternatives or exclusions (e.g., 'use get_email for a single email'), so it lacks explicit when-not guidance, but the purpose is unambiguous.

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

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

The readOnlyHint annotation already signals no side effects, and the description adds useful behavioral details such as case-insensitive substring filtering, pagination semantics, and the promise that results are never silently truncated. This is transparent about how the tool behaves.

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, front-loaded with the tool's purpose, and uses a second sentence only to clarify sibling-tool boundaries. No unnecessary words or redundant detail are 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?

Despite having no output schema, the description names the key returned fields and the input schema fully documents filtering and pagination behavior. The tool is positioned clearly among related list tools, so an agent has enough context to use 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 main description does not add parameter-level meaning beyond what the input schema already provides. However, the schema descriptions are comprehensive and cover all seven parameters, so the baseline score 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 clearly states the tool lists business expenses with the relevant fields. It explicitly distinguishes this tool from list_income and list_transactions, making its purpose and scope 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 directly tells when to use this tool versus alternatives: recorded expenses here, recorded income via list_income, and raw bank-feed lines via list_transactions. Parameter descriptions also explain filtering and pagination 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?

Annotations already provide readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context beyond the annotations: it states contents are not returned, which prevents the agent from expecting file data, and it clarifies the significance of the 'stub has finished reading it' state. It could also mention pagination or ordering, but for a read-only listing tool, the current disclosure is solid.

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

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

Three dense sentences with front-loaded scope, a clear 'what you get' list, and a routing pointer to sibling tools. There is no filler, and every sentence earns its place.

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

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

For a read-only, zero-required-parameter listing tool with no output schema, the description tells the agent what fields come back, how to widen scope, and how to get file contents. The main gaps are output ordering/pagination and the precise meaning of the 'paired' filter in context, but the schema covers paired and the description covers the essential caller concerns.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents folderid and paired. The description adds a little value by repeating the 'omit for all' semantics in prose, and it names the fields returned, but it doesn't add new parameter meaning beyond the schema. This is adequate, not exceptional.

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

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

The description begins with a clear resource ('The files in a folder') and enumerates what fields are returned (name, type, stub-read status, classification), which distinguishes this as a metadata-listing tool. It does not explicitly differentiate from sibling list tools like list_documents or list_binned, but the folder-scoped phrasing and the exclusions (contents are not returned) give it a reasonably distinct identity.

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 'omit folderid for every file' and tells the agent when to use read_file_columns and fold_file_column instead: when answers about what is inside a file are needed. This is clearer than most sibling definitions, though it does not explicitly enumerate other list tools or say 'use this only when folder-scoped file metadata is needed' as a hard exclusion.

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