Beancount.io

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

Goes well beyond the annotations by naming the failure modes (UNBALANCED, VALIDATION_FAILED) and the exact conditions that trigger them, plus the escape hatch via allowInvalid. It also discloses that the commit message is derived from the entries and that one posting may be elided. Minor gap: no statement on whether the batch is atomic when a mid-list entry fails.

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

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

One dense paragraph that front-loads the core action and the entry-type list, then moves to constraints and errors. Every sentence carries information, though the validation clause is packed into a single run-on sentence that is harder to parse than necessary.

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 6-parameter mutation with an output schema present, this covers behavior, error codes, auth/pinning prerequisites, and preview mode. It leaves only batch atomicity and the alias parameters unaddressed, both of which the schema or output schema partially absorb.

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

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

With only 50% schema description coverage, the description compensates well: it explains allowInvalid's purpose, ledger's pinned-credential default, dry_run's preview semantics, and the lowercase budget interval values. It does not document the dryRun/allow_invalid alias parameters, which the schema does cover.

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

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

States a specific verb (append) and resource (ledger entries) and enumerates the ten entry types accepted, which is far more than restating the name. It does not explicitly distinguish itself from the sibling appendLedgerText, so an agent must infer the structured-vs-raw split from the title alone.

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?

Useful conditions are given: ledger is required unless the credential is pinned, and dry_run previews without committing. However, it never says when to prefer this over appendLedgerText or the other write siblings, leaving the main routing decision to inference.

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

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

Adds substantial behavior beyond annotations: max 50 directives, routing by type and date with path overrides, rejection of non-directive text and new bean-check errors unless allowInvalid, and dry_run producing diff/errors without committing. It also notes that commit messages are composed automatically, so there is no message argument.

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

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

Front-loads the core action, then covers routing, limits, validation, dry-run behavior, sibling contrast, and commit-message behavior in dense but efficient sentences. The syntax link is appropriately placed at the end.

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

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

Complete for a mutation tool with annotations and an output schema: it explains validation, routing, limits, dry-run behavior, and key parameter effects. Return-value details are not required because an output schema exists.

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?

Adds clear meaning for key parameters: text is Beancount directive syntax with indented postings, path overrides automatic routing, dry_run returns a diff and projected errors, and allowInvalid permits invalid content. Schema coverage is 71%, and the description supplies the most important semantic context 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?

States a specific verb and resource: appending Beancount directive text as file content, with postings indented. It also distinguishes itself from updateLedgerFiles, making the scope clear enough to select without opening the schema.

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

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

Explains the main usage context, routing/date-order behavior, the 50-directive limit, refusal conditions, and explicitly contrasts with updateLedgerFiles. It does not address when to choose addLedgerEntries instead, so it stops short of fully exhaustive sibling 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 establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the disclosure burden. The description adds useful context about what is returned, but does not describe runtime behavior such as performance characteristics, error handling, or authorization requirements beyond the schema's ledger restriction note.

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. Each clause contributes either the core purpose or a concrete output 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?

With an output schema present, annotations covering safety, and full schema coverage for the single parameter, the description provides sufficient context for an agent to call the tool correctly. It succinctly summarizes the diagnostic value without duplicating structured fields.

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 sole parameter's meaning, owner/name format, and default behavior are already fully documented in the schema. The description adds no parameter-level guidance beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('Check one ledger's validity') and enumerates the concrete outputs: bean-check errors with file/line, entry counts per directive type, and the latest commit. This distinguishes it from sibling ledger tools that list, create, or mutate ledger data.

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

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

The phrase 'in one call' clearly signals the tool's role as a consolidated validation/diagnostic endpoint, which gives an agent enough context to know when to use it. However, it does not explicitly name alternatives or state when not to use it versus tools like listLedgerEntries or getLedgerContext.

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 create semantics (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description is free to add what they don't say: the auth refusal, template content differences (STARTER with no transactions vs SAMPLE with demo transactions), and the setup/template exclusivity rule. Note the mild tension between idempotentHint=false and the requestId idempotent-retry option, though the latter is clearly opt-in so this is not a 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?

Two sentences, front-loaded with the required parameter and ownership scope, then the optional surface and the refusal rule. The nested parenthetical for template is dense but each clause carries a distinct constraint rather than repeating the schema.

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

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

For a create tool with annotations, an output schema, and 67% parameter coverage, this covers what the schema can't: default template behavior, exclusive setup option, credential restriction, and retry semantics. Only the setup preset vocabulary (personal@1, blank@1, etc.) and capability values are left entirely to 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?

With 67% schema coverage, the schema already explains name, private, template, and description. The description still adds real meaning by stating the mutual-exclusion rule between setup and template and by framing requestId as idempotent-retry support, which the schema leaves as a bare string. The nested setup object's preset/capability semantics remain undocumented.

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?

A specific verb plus resource ("Create a ledger") with explicit ownership scope ("owned by the authenticated user"). The description covers the full creation surface (name, template, setup, requestId) and the refusal condition, so an agent can distinguish it from listLedgers, updateLedger, and deleteLedger without opening the schema.

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

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

Gives concrete calling conditions: name is required, setup is mutually exclusive with template, and the call is refused for ledger-pinned credentials. It does not point at alternatives for previewing a setup (previewLedgerSetup exists as a sibling), so the routing guidance is incomplete.

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

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

Goes well past annotations by disclosing all-or-nothing semantics ('one atomic commit'), a hard 1 MiB UTF-8 byte cap applied to both commits and dry runs, and that a dry run performs the identical refusal path while returning a unified diff per touched file plus a bean-check verdict. The annotations only declare non-read-only, non-destructive, non-idempotent; the description supplies the real behavioral contract.

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

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

Two dense sentences, front-loaded with the action and atomicity, with the limit and dry-run behavior following in priority order. Every clause carries information, though phrases like 'the same refusal as the commit' are slightly awkward and could be tightened.

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

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

With an output schema present, the description need not enumerate return values, yet it still characterizes dry-run output, which is the risky path agents will wonder about. It leaves open whether existing paths are overwritten or rejected and any approval/credential requirements tied to `description`, but the core write contract 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?

Schema coverage is 83%, so most parameters are already documented, but the description still adds meaning the schema lacks: dry_run's return shape (diff per file, bean-check verdict, same refusals as commit) and the byte limit that governs the content field. It does not clarify the dryRun/dry_run and message/description aliases or the ledger resolution rule, so it stops short of full 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?

States a specific verb and resource ('Create new text files') plus the transactional scope ('one atomic commit') and encoding ('plain UTF-8'), which separates it from updateLedgerFiles, appendLedgerText, and renameLedgerFile. An agent can tell this is a create-only, multi-file write without opening the schema.

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

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

The dry_run sentence implies the preview-then-commit pattern, which is useful context for choosing this tool's mode. However, it never says when to use this versus updateLedgerFiles, appendLedgerText, or renameLedgerFile, nor any exclusion such as 'do not use for existing paths' beyond the word 'new'. Usage is implied rather than stated.

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

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

Annotations already disclose that this is a non-read-only, non-idempotent, non-destructive mutation. The description adds useful context about the baseBranch default and SERVICE_UNAVAILABLE failure behavior, but it does not warn about duplicate PR creation or explain permission/ledger constraints in detail.

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 tightly packed sentences with the core action first, followed by required inputs, default behavior, and error behavior. There is no redundant restatement of the tool name or title.

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

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

For a seven-parameter mutation tool with low schema description coverage, the description gives enough to call it correctly: required fields, changes structure, baseBranch default, and error behavior. The output schema handles return values, though some parameter nuances remain delegated to 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 description coverage is only 29%, so the description must compensate. It names the required parameters, describes the changes array shape, and states the baseBranch default, but it does not explain all parameter semantics, especially ledger and fastForward, beyond what their schema descriptions already provide.

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

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

The description states a specific verb and resource: propose file changes as a pull request. It is clearly distinguishable from sibling operations like mergePullRequest and rejectPullRequest.

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

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

The purpose implies when to use it, but the description does not explicitly contrast it with mergePullRequest, rejectPullRequest, or other file-management tools. No exclusions or prerequisite workflow guidance are provided.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond that: it discloses the bean-check validation gate, the VALIDATION_FAILED error shape with per-error naming, that re-dating a balance-assertion dependency counts as a new error, and that the commit message is synthesized rather than supplied. That is exactly the context an agent needs before committing a destructive write.

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 dense sentences, front-loaded with the operation and its addressing scheme before the validation caveat. Each sentence earns its place, though the alias/argument notes slightly overlap with what the schema already spells out.

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 single-record delete with annotations and an output schema present, the description covers the gaps that matter: how to address the record, what gets validated, how to override, and how to preview. Nothing an agent needs to call this safely 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 88%, so the schema carries most parameter documentation. The description still adds provenance the schema lacks — which upstream call produces entry_hash and which produces sha256sum — plus the negative signal that no message argument exists. It does not touch ledger scoping or the dryRun/allow_invalid aliases, which are schema-only.

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

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

States a specific verb and resource with precise scope: delete ONE entry's source text, not the entry itself. It also names the addressing pair (entry_hash from listLedgerEntries, sha256sum from getEntryContext), which is enough for an agent to separate it from updateEntrySource and the plural deleteEntrySources without opening a schema.

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

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

Clear about the precondition (you must already hold the hash and sha256sum from prior calls) and about the override path (allowInvalid: true) and preview path (dry_run). It does not explicitly name the sibling alternatives — updateEntrySource for editing versus deleteEntrySources for batch deletion — so the when-not condition is left 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?

Adds substantial behavior beyond the destructive annotation: commit-message composition, no message argument, deleted-count return, bean-check validation refusal with VALIDATION_FAILED and named errors, allowInvalid override, and dry_run preview. This tells the agent exactly how the write can fail and how to bypass the refusal.

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

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

Dense but front-loaded with the core operation, and every sentence carries operational value. The long paragraph could be slightly easier to scan, but it is not padded.

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

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

Complete for a destructive batch mutation with an output schema: it covers entry identity, commit behavior, validation refusal, override, preview, and return shape. The remaining schema details, such as ledger targeting and aliases, are handled by 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 already high, but the description adds useful semantics for entries: accepted hash spellings, sha256sum pairing, and the relationship to listLedgerEntries output. It also explains allowInvalid and dry_run behavior beyond schema 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 verb and resource: deleting several entries' source text in one commit. The batch nature is clear, but it does not explicitly distinguish itself from the singular deleteEntrySource 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 batch context and dry_run preview imply when to use it, but there is no explicit guidance on choosing it over deleteEntrySource or updateEntrySource. Validation and allowInvalid behavior are explained, yet alternative-tool selection is left 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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, but the description adds genuinely useful context: the deletion is permanent and includes history, which qualifies the blast radius. It still omits whether owner permission is required, whether collaborators lose access, and whether the operation can be undone by any means.

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

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

One front-loaded sentence with zero filler; the permanent/irreversible nature is stated immediately. Nothing in it is wasted.

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

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

The tool is simple (one optional parameter, output schema present, rich annotations), and the description covers the core action and its permanence. For an irreversible destructive operation, however, it should at least note permission requirements or the effect on collaborators and existing entries.

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% with a single well-documented parameter (owner/name format, defaults to the credential's ledger restriction), so the schema carries the semantics. The description adds nothing about the ledger identifier, leaving the baseline 3.

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

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

Names a specific verb (permanently delete) and resource (a ledger) plus the scope of the deletion ('including its history'). It is clear on its own, but it never distinguishes itself from sibling leaveLedger, which an agent could easily confuse with deleting a ledger, so it falls short of a 5.

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

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

There is no statement of when to use this versus leaveLedger, updateLedger, or deleteLedgerFiles, and no prerequisites such as required ownership or confirmation. The agent must infer usage entirely from the tool name and annotations.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial context: atomic commit behavior, BAD_USER_INPUT refusal naming includers, the 1 MiB UTF-8 limit including dry runs, and dry-run preview contents with unified diffs and bean-check verdicts.

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

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

The description front-loads the purpose and then adds only operationally relevant constraints. It is dense and has some long sentences, but every clause about sha, includes, size limits, and dry runs earns its place for a destructive 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?

Given the output schema exists, the description need not explain return values. It covers deletion behavior, refusal conditions, include resolution rules, size limits, and dry-run previews, leaving no critical gaps for an agent invoking this destructive 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 high at 83%, so the schema already documents most parameters. The description still adds meaning by tying sha to readLedgerFiles and by detailing what dry_run actually returns beyond the schema's generic preview wording.

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

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

States a specific verb and resource ('Delete files') plus the distinctive scope 'in one atomic commit'. The refusal mechanics and include handling make it clearly distinguishable from sibling tools like updateLedgerFiles or renameLedgerFile.

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?

Explains key preconditions clearly: pass sha from readLedgerFiles to avoid overwriting concurrent changes, remove includes from including files before deletion, and use dry_run for preview. It does not explicitly name when to choose this over sibling mutation tools, so it falls 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known from structured data. The description adds the meaningful outcome that discarded transactions are 'never imported' (permanent exclusion), but the dry_run sentence largely repeats the schema's own dry_run description ('Validate and report what would change, without changing anything'). No mention of what happens to already-imported or unknown IDs.

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

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

Two sentences, zero filler, with the mutation outcome front-loaded before the dry-run note. Nothing to trim.

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

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

An output schema exists, so return values needn't be explained, and the schema documents all five parameters including ledger scoping and aliases. The description covers purpose and preview mode; the only minor gap is guidance on where transaction IDs come from, which the schema already handles.

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

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

Schema description coverage is 100%, including the important note that transactionIds must come from listStagedBankTransactions `transactionId` rather than `id`, and the ledger scoping default. The description adds nothing beyond dry_run, so the baseline 3 applies.

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

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

States a specific verb ('Remove') and resource ('staged bank transactions') plus the consequence ('never imported'), which is more than a restatement of the name. It implicitly contrasts with importing, but never names the sibling importStagedBankTransactions or listStagedBankTransactions that an agent would need to distinguish it from.

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 mention of dry_run implies 'preview before committing,' which is useful implied usage. However, there is no explicit statement of when to choose this over importStagedBankTransactions or how to obtain the IDs, leaving the agent to infer the workflow.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's marginal job is the two-step protocol, which it does state. It adds that the URL is user-bound and the params only preserve metadata, but omits key behavioral facts for a 'temporary' credential: URL lifetime, reusability of the presigned PUT, and whether metadata is reflected into objectKey.

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

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

Three short sentences, each doing distinct work: what is created, what the optional params do, and how to complete the flow. The core action is front-loaded with zero filler.

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

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

An output schema exists, so return structure needn't be explained, yet the description helpfully names uploadUrl and objectKey to tie the response to the workflow. For a two-optional-parameter tool the coverage is nearly complete; only the expiry semantics of the 'temporary' URL are missing.

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

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

Schema coverage is 0%, so the description must carry the parameters, and it does: both are marked optional and their effect is explained as metadata preservation rather than path control. That is meaningful added semantics, though it doesn't show format expectations or examples.

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

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

States a specific verb and resource — 'Create a presigned PUT URL' — plus the scope qualifier 'bound to the current user'. That is unambiguous and unlike any sibling, though it never addresses near-neighbors such as createLedgerFiles, so an agent could still wonder when a direct upload path applies.

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

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

The description gives real operational context: upload bytes to uploadUrl, then use objectKey in an ingestion workflow. That clarifies the intended place in a pipeline. It stops short of exclusions (e.g., when to prefer a different file-creation path) or expiry/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 annotations already establish read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond them. It explains that a `generated_from` result is a copy sharing the source's slice and sha256sum, so editing or deleting the copy would affect the source and every other copy. That is exactly the kind of side-effect information an agent needs before using the hash with a mutation tool.

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

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

The description is dense but appropriately sized for the tool's complexity. The core purpose is front-loaded, followed by addressing details and then the `generated_from` warning. Some sentences are packed with multiple constraints, but each carries operational value.

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

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

The tool has an output schema, full input-schema coverage, and rich annotations, so the description does not need to repeat return structure or safety hints. It still covers the critical contextual gaps: hash provenance, alias naming, resource equivalence, and the danger of acting on generated copies. Nothing essential for correct invocation appears 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 parameters are already documented structurally. The description still adds useful semantics by tying `entryHash` and its alias `entry_hash` to listLedgerEntries output and to the mutation tools that consume the same hash, plus the `sha256sum` relationship. It does not add much about the `ledger` parameter, but the schema covers that.

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: 'Read the source context around one entry.' It distinguishes this tool by explaining the entry-hash addressing returned by listLedgerEntries and ties the same hash to updateEntrySource and deleteEntrySource, making its role clear against ledger-level 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 gives clear usage context: get the hash from listLedgerEntries output, and use the same hash for updateEntrySource or deleteEntrySource. It also provides an important exclusion for generated entries by telling the agent to address the `generated_from` entry instead, though it does not explicitly contrast this tool with the entry-context resource.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond that by disclosing truncation behavior — lists may be truncated and counts accompany them so large ledgers don't flood context — which an agent needs to interpret results correctly.

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

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

Two tightly written sentences: the contents come first, the truncation/counts caveat second. No filler and nothing is buried.

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

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

With an output schema present and annotations covering the safety profile, the description covers what is needed to call and interpret the tool. The only shortfall is the absence of routing guidance relative to sibling read tools, which is minor for a discovery 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?

Schema description coverage is 100%, including the ledger default behavior and the payeeLimit default of 50, so the schema does the heavy lifting. The description adds only indirect context ('truncated lists') and no format or syntax details beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Read a ledger's working vocabulary') and then enumerates exactly what comes back: attributes, open accounts, currencies, payees, years, source files. That enumeration clearly separates it from siblings like listLedgerEntries or getEntryContext, which target individual entries rather than the ledger's vocabulary.

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

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

The phrase 'in one call' implies this is the broad discovery/orientation tool, but the description never says when to prefer it over getEntryContext or listLedgerEntries, nor does it state any prerequisites. Usage is inferable but not explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the mutation profile is known. The description adds real value by explaining that dry_run validates and reports without committing, but it is silent on the consequence of idempotentHint=false — whether re-running with the same transactionIds creates duplicate directives or is deduplicated — which is exactly the risk an agent needs flagged for a ledger write.

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

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

Two sentences, front-loaded with the write action and followed by the dry-run caveat. No filler and nothing redundant with the schema.

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

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

An output schema exists, so return values need not be explained, and the schema documents ledger/filename defaults thoroughly. However, for a financial write with idempotentHint=false, the description omits what happens to staged rows after import and whether a repeat run duplicates entries, leaving a meaningful gap for the agent's decision-making.

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

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

Schema description coverage is 100%, including nested item fields and the transactionId-vs-id distinction, so the schema carries the parameter burden. The description only gestures at targetAccount ('booked against the given target account') and adds nothing about ledger, filename, or alias precedence, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Write staged bank transactions into the ledger as directives') and clarifies that each is booked against a target account. It implicitly separates this from addLedgerEntries or insertReceiptTransaction by naming 'staged bank transactions' as the input domain, but it never names an alternative tool explicitly.

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

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

The only usage guidance is embedded in the dry_run sentence, which explains what a non-committing run does. There is no explicit statement of prerequisites (that rows must first come from listStagedBankTransactions), no when-not-to-use, and no pointer to the sibling that discards or lists staged rows.

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 establish that this is a non-readonly, non-idempotent, non-destructive mutation. The description adds useful context beyond that by saying it promotes a temporary receipt into receipt storage and 'Applies immediately,' clarifying that the operation is an immediate state change.

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

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

The description is short, front-loaded with the core action, and structured in three clear sentences. The middle sentence listing input fields is somewhat redundant with the schema, but overall it remains efficient.

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

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

Given the available annotations and output schema, the description provides enough context to understand the mutation, the temporary receipt workflow, and the ledger pinning rule. It does not need to explain return values because an output schema exists.

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 mentions all three top-level parameters and summarizes the nested input fields, but much of this repeats what the schema already exposes. It reinforces the receiptObjectKey and ledger/pinned semantics, though it adds limited detail beyond the schema's own 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 names a specific action and resource: promote a caller-owned temporary receipt into receipt storage and append the confirmed transaction. It also ties the operation to receiptObjectKey, which clearly distinguishes it from generic siblings such as addLedgerEntries or parseReceipt.

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 receipt-specific workflow is implied by 'temporary receipt' and 'confirmed transaction,' and the ledger/pinned credential requirement is stated. However, the description does not explicitly say when to use this instead of addLedgerEntries or other receipt/ledger entry tools, so routing guidance is only implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered structurally. The description adds that only the caller's own membership is affected, but says nothing about consequences: whether entries/history are preserved, what happens if the caller is the owner, or that rejoining requires a new invitation.

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

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

A single front-loaded sentence with no filler; the scoping qualifier ('own access ... they collaborate on') is placed where it does the most work.

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

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

Output schema and rich annotations relieve the description of explaining return values and safety. However, for a destructive, non-idempotent membership mutation it omits key edge cases (owner cannot leave, effect on shared entries, need to be re-invited), so it is only minimally sufficient.

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

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

Only one parameter and the schema documents it at 100% coverage, including the owner/name format and the unpinned-credential default. The description adds no meaning beyond that, which is acceptable at this coverage level but leaves nothing extra.

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

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

States a specific verb and resource ('Remove ... access to a ledger') plus the scope that matters: the authenticated user's own access, on a ledger they collaborate on. This implicitly separates it from deleteLedger and removeLedgerCollaborator, though it never names those siblings, so an agent must still infer the boundary.

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

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

The context of use is implied by 'a ledger they collaborate on,' but there is no explicit when-to-use/when-not rule and no routing to removeLedgerCollaborator (removing someone else) or deleteLedger (deleting the whole ledger). Usage is inferable but not guided.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered. The description adds one useful behavioral nugget — that the returned ids feed downstream tools — but says nothing about result shape, ordering, or behavior when no bank is linked (the output schema covers the payload).

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

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

A single sentence that leads with the verb and resources and packs the downstream-id note into a tight parenthetical. No restatement of the title and no filler.

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

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

For a simple idempotent read-only listing tool with full annotation coverage, a documented single param, and an output schema describing the return payload, the description supplies everything an agent needs to select and 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?

Only one optional parameter (ledger), and the schema documents it at 100% coverage including the unpinned-credential default. The description adds nothing about it, which is acceptable given the schema does the work, but there is no added meaning.

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

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

States a specific verb (list) and both resources (bank connections and their accounts), plus names the exact identifier fields returned (item_id, account_id). This clearly separates it from siblings like listStagedBankTransactions or reconcileBankAccounts, which operate on staged transactions or reconciliation work rather than the connection inventory.

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 the usage context by flagging that these are the ids that bank sync, import, and connection tools consume, which tells an agent to call this first in those flows. It stops short of explicitly naming which sibling to call instead or stating exclusions, so it lands just below the top band.

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 establish read-only, idempotent, non-destructive behavior, so the description need not repeat safety semantics. It adds useful behavioral context by stating pagination via limit/offset and that total counts every match, though it leaves return-shape details to the output schema.

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

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

The description is compact and front-loaded, leading with the core action and then covering filtering, pagination, total count, and the entry_hash relationship. Every clause contributes useful information without excess prose.

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 seven-parameter optional-filter listing tool with full schema coverage, annotations, and an output schema, the description supplies the needed framing. It covers purpose, filtering scope, pagination, total behavior, and the entry_hash linkage without needing to restate schema details.

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 carries the detailed parameter semantics, including filter syntax and defaults. The description helpfully groups the parameters by filtering and pagination, but it does not materially add syntax or 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?

The description uses a specific verb and resource: 'List journal entries.' It also explains that each entry includes the entry_hash consumed by getEntryContext, updateEntrySource, and deleteEntrySource, making the tool's output and downstream role clear.

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

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

It clearly frames the tool as a filtered, paginated journal-entry listing and notes that it returns the same data as the journal resource. That gives useful context, but it does not explicitly compare against alternatives such as runBqlQuery or state when not to use this listing 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 safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral facts: the listing is non-recursive and results are ordered directories-first. Neither trait is derivable from the annotations or schema, and both affect how an agent must loop through the tree. No pagination or empty-directory behavior is described.

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

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

A single tightly packed sentence with zero filler, front-loading the core action and appending the two constraints that matter most (depth and ordering).

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 a full output schema and rich annotations, the description supplies the key missing context (non-recursive depth, sort order). Minor gaps — behavior on a nonexistent path, large-directory handling — are not covered but are not essential to calling it correctly.

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

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

Schema description coverage is 100%, so both parameters (ledger, dir_path) are already documented including the root/'.' convention. The description contributes only the implied notion that dir_path selects a single level; baseline 3 applies.

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

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

States a concrete verb and resource ('List files and directories in the ledger repo') plus scope ('one directory level at a time') and ordering ('directories first'). The listing-versus-reading distinction from siblings like readLedgerFiles is implied by 'List' but no sibling is named 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?

'One directory level at a time' implies an iterative navigation workflow, which is useful guidance for traversal, but there is no explicit statement of when to use this versus readLedgerFiles or how to recurse into a listing. Usage is inferable rather than stated.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds meaningful context beyond that: credential scoping, the pinned-credential single-ledger case, and default pagination behavior when parameters are omitted.

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

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

Two compact sentences with no wasted text. The core scope and the key credential-pinning distinction are 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?

Given the output schema exists and annotations cover safety traits, the description provides everything needed to select and invoke the tool correctly: scope, pagination omission behavior, credential pinning, and downstream 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?

Schema coverage is 100%, so the schema defines both parameters fully. The description still adds value by clarifying that omitting both `page` and `limit` returns every reachable ledger, which is a semantic detail beyond the schema's default notes.

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

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

The description states a specific verb and resource ('List the ledgers') and precisely bounds the scope by credential reach. It further distinguishes behavior for pinned versus unpinned credentials, so an agent can tell this apart from siblings like checkLedger or createLedger without opening the schema.

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

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

It clearly establishes when the tool returns all ledgers (page and limit omitted) and explains its role as the source for the `ledger: owner/name` parameter used by other ledger tools. It does not explicitly state when to prefer a different sibling, but the usage context is strong and unambiguous.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds a critical behavioral detail beyond annotations: each row has both id and transactionId, and the latter is the identifier required by import/discard tools. It does not discuss pagination or result-size behavior, but the core ID semantics are disclosed.

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

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

Two compact sentences: the first states purpose, the second front-loads the critical transactionId distinction and mentions the optional filter. There is no redundant restatement of the title or annotations.

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

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

With an output schema present, the description need not explain return values, and annotations cover the safety profile. It adequately explains the non-obvious identifier contract and the optional accountId filter. Only minor gaps remain, such as whether staged results are paginated or account-scoped by default.

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 ledger but leaves accountId undocumented. The description compensates by explaining that accountId is an optional filter, adding meaning beyond the bare schema string. The ledger parameter is already well described in 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: list bank transactions staged for import. It also names the downstream import and discard tools, making the tool's role distinguishable from generic ledger or bank-connection 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 staged-for-import framing implies this is used before calling importStagedBankTransactions or discardStagedBankTransactions, and the transactionId note reinforces that. However, it does not explicitly state when not to use it or how it relates to siblings like syncBankTransactions or listBankConnections.

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, but the description adds the concrete payload: an existing mapping is replaced, which tells the agent this is an overwrite rather than an additive link. It omits permission/auth requirements and any warning that all parameters are optional, keeping it below 5.

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

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

One sentence, zero waste, action front-loaded and the destructive consequence attached with a semicolon. Nothing redundant or padded.

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

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

An output schema exists and annotations carry safety semantics, so the description needn't explain returns. However, with zero required parameters and duplicate alias parameters, the description should clarify what happens when ledgerAccount or accountId is omitted, which it does not.

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 ledger, accountId, ledgerAccount and their aliases are fully documented in structured fields. The description adds no parameter meaning beyond that, which is acceptable at high coverage but earns only the baseline.

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

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

States a specific verb ('Point ... at') and both resources (linked bank account, ledger account), so the agent knows exactly what the tool does. It does not name or contrast with the nearest sibling (reconcileBankAccounts), so it stops short of a 5.

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

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

There is no when-to-use guidance, no prerequisites (bank connection must exist, ledger must exist), and no mention of alternatives such as reconcileBankAccounts or setBankAccountCurrency. The tool's purpose is inferable, but the agent gets no routing help.

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

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

Annotations already declare destructive=true and idempotent=false. The description adds useful context by stating the merge applies immediately and documenting two failure modes: RESOURCE_LIMIT_REACHED and SERVICE_UNAVAILABLE naming the failed step.

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

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

The description front-loads the core action, then adds immediacy and error behavior without filler. Every sentence contributes useful operational context.

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

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

With an output schema present and annotations covering destructive/idempotency, the description supplies purpose, immediate effect, and error behavior. It omits merge preconditions such as required approvals or mergeability, which is a minor gap for a destructive merge 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 both ledger and prNumber are already documented in the input schema. The description does not add syntax or format details for either parameter beyond what the schema provides, making 3 the baseline.

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

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

The description states a specific verb and resource: "Merge a pull request into its base branch." This clearly distinguishes the action from siblings like createPullRequest and rejectPullRequest.

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 immediate application wording implies this is the final merge action, but the description does not explicitly say when to use it versus rejectPullRequest or what PR preconditions must be met. Usage is implied rather than fully guided.

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 safety hints, and the description adds useful behavior beyond them: parsing consumes AI quota and does not write ledger entries. This clarifies cost and side-effect boundaries without contradicting the annotations.

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

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

The description is three tight sentences with the core action front-loaded. Each sentence adds useful information: what it does, parameter provenance/format meaning, and quota/side-effect constraints.

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

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

An output schema exists, so return values need not be described, and the annotations cover safety hints. The description still supplies the key operational context an agent needs, though it could be more explicit about accepted file formats and sibling alternatives.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It explains that s3ObjectKey comes from the upload operation and that fileFormat names the format, with examples such as csv, pdf, xlsx, and json.

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: parse a caller-owned temporary upload into transaction rows. It is clear what the tool does, but it does not explicitly distinguish itself from nearby siblings such as parseReceipt or importStagedBankTransactions.

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

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

It gives an important prerequisite by saying s3ObjectKey comes from the upload operation, but it does not explicitly say when to use this tool versus parseReceipt or importStagedBankTransactions. Usage is implied rather than fully guided.

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 context the annotations cannot express: token consumption ('Consumes extraction and recommendation tokens'), a no-write guarantee ('without inserting entries'), and a caller-ownership/auth scoping constraint ('caller-owned'). These reconcile why readOnlyHint=false but destructiveHint=false, which would otherwise be puzzling.

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

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

Three short sentences, each carrying distinct load: what is parsed, the ledger credential rule, and the side-effect/cost profile. Nothing is padded and the core action is front-loaded.

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

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

An output schema exists, so return values need no explanation; what remains — required permission, cost, and absence of writes — is all covered. For a 2-parameter read-adjacent tool this leaves no material 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 coverage is already 100%, so baseline is 3; the description nonetheless adds the accepted file types ('image/PDF') and the credential-dependent requiredness of ledger, which the schema states tersely. It stops short of explaining objectKey format details or failure behavior for expired temp objects.

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

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

States a specific verb and resource ('Parse the caller-owned temporary image/PDF named by objectKey') plus the outcome ('recommend accounts'). The clause 'without inserting entries' separates it from the mutation sibling insertReceiptTransaction, and 'receipt' separates it from the generic parseFile.

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

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

Gives conditional selection guidance for the ledger parameter: 'Pinned credentials may omit ledger; others must select it.' It also clarifies the boundary against entry-creating tools via 'without inserting entries', though it never names insertReceiptTransaction as the follow-up alternative explicitly.

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, idempotentHint=true, and destructiveHint=false. The description adds useful context beyond those annotations by stating that nothing is created and by naming the returned preview artifacts, though it does not discuss auth or rate limits.

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 tight sentences with no wasted wording. The core preview/no-creation behavior is front-loaded, followed by the useful createLedger compatibility note.

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 preview tool with an output schema, the description covers the essential purpose, side-effect profile, and return categories. The main remaining gap is that the complex nested setup parameter is only cross-referenced to createLedger rather than further explained.

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 0% description coverage, so the description must carry extra meaning. It adds a useful semantic link by saying the setup object is the same as createLedger's, but it does not explain the nested setup fields, preset enum, accounts, capabilities, or historyStart beyond what the schema structurally exposes.

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

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

The description gives a specific verb and resource: preview a ledger setup without creating anything. It also states what the preview returns and explicitly contrasts with createLedger by saying it accepts the same setup object, so an agent can distinguish it from creation 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 clearly implies when to use this tool: to inspect the files, account list, and validation result before creating anything. It names createLedger as the related alternative, though it does not explicitly exclude other validation tools such as checkLedger.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real behavioral content: content is raw text, line numbers and totalLines are returned alongside rather than embedded, and non-UTF-8 files return lossy: true with U+FFFD substitution and refused edits. That lossy/edit-refusal rule is exactly the kind of constraint annotations cannot express. It stops short of describing per-file error behavior when a path is missing.

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, front-loaded with the core action, then return shape, then the token-limit advice and the encoding edge case. Every sentence carries distinct information with no restatement of the title or schema.

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

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

An output schema exists, so return values needn't be re-explained, but the description still usefully flags the lossy/UTF-8 case and the token-limiting strategy. Minor gaps remain: behavior on a nonexistent path and whether the files array is processed atomically or partially.

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. The description adds the rationale for start_line/end_line ('to limit tokens for large files') and clarifies that line spans are 1-based, but says nothing about the `ledger` parameter or multi-file result ordering, so it barely exceeds the schema.

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

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

States a specific verb+resource — read beancount ledger files — and adds batch scope ('one or more ... in a single call'), which tells an agent this is not a single-file read. It does not, however, name a sibling such as listLedgerFiles to make the discovery-vs-read distinction explicit.

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

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

The only usage guidance is operational: 'Use start_line/end_line per file to limit tokens for large files.' There is no statement of when to prefer this over listLedgerFiles or listLedgerEntries, nor any exclusion or prerequisite (e.g. how to obtain a valid path).

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=false, but the description adds genuinely new detail: exactly what is removed (no-longer-shared accounts plus their staged transactions) and that dry_run reports changes without applying them. It still omits whether the deletion is reversible and whether currently shared accounts are touched, which matters for a destructive operation.

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

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

Two tight sentences with the effect stated first and the dry-run caveat second — front-loaded and free of filler. The second sentence partially duplicates the dry_run schema description, but it earns its place as the safety valve for a destructive call.

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

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

With an output schema present and rich destructive/openWorld annotations, the description needs only to convey the destructive scope and preview mode, which it does. The remaining gap is that no parameter is strictly required (required: 0), yet the description never signals what a call without itemId would reconcile.

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 itemId, ledger, both dry-run spellings, and the item_id alias are all documented structurally; a baseline of 3 applies. The description restates only the dry_run behavior already present in the schema and says nothing about itemId selection or the ledger fallback to the credential's restriction.

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 operation — re-reading which accounts a linked bank shares and deleting the ones no longer shared, along with their staged transactions. That is far more informative than the name alone and distinguishes it from pure listings like listBankConnections. It does not, however, explicitly contrast itself with nearby siblings such as refreshBankConnection, syncBankTransactions, or discardStagedBankTransactions.

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 trigger condition is only implied: reconciliation matters when a bank stops sharing accounts, and dry_run is offered for a no-op preview. There is no explicit 'use this instead of X when Y' routing among the many bank/transaction siblings, leaving the agent to infer whether this or syncBankTransactions/discardStagedBankTransactions is the right call.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and idempotentHint=true, so the external-call and mutation-of-stored-state profile is covered structurally. The phrase 'from the bank' reinforces the live external call, but nothing is said about latency, rate limits, failure modes if the bank credential has lapsed, or what happens to the stored status on error — context that would matter for a non-read-only outbound call.

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

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

A single front-loaded sentence with no filler, and the key constraint ('health status', not transactions) is immediately visible. It is arguably over-terse given the available space, but nothing is wasted.

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

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

An output schema exists, so return values needn't be explained. Still, for a tool with zero required parameters sitting next to syncBankTransactions and unlinkBankConnection, the description omits the selection guidance and the meaning of the optional aliased parameters that an agent needs to call it correctly.

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

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

Schema coverage is 100% and all three parameters are documented in the schema, so baseline applies. The description adds nothing about the itemId/item_id alias overlap or when the ledger override is needed, leaving that entirely to the schema text.

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

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

States a specific verb ('Re-read'), resource (linked bank connection) and the field affected (health status), which is clear. It does not, however, distinguish itself from nearby siblings such as syncBankTransactions or listBankConnections, so an agent must infer that this refreshes status only rather than transactions.

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

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

The description gives no condition for when to call this versus syncBankTransactions (fetch transactions) or listBankConnections (read cached records). There are no stated prerequisites despite all parameters being optional, so the agent gets no routing guidance at all.

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 useful clarity beyond the annotations by stating 'Never edits the ledger' and describing the return as each source's status. This helps reconcile the non-read-only annotation with the reassurance that no ledger edits occur, though external side effects are only implied by the openWorldHint annotation.

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

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

The description is front-loaded and efficient: it states the action, return behavior, safety boundary, and parameter condition in three tight sentences. Nothing is wasted.

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

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

The tool has only one parameter, rich annotations, and an output schema. The description covers the action, return focus, non-editing behavior, and ledger requirement, leaving no material gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the input schema already documents the ledger parameter fully. The description's 'required unless pinned' restates the schema's defaulting behavior without adding significant new parameter semantics.

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: it re-fetches the ledger's managed price feeds and returns each source's status. The phrase 'managed price feeds' clearly differentiates this from sibling refresh actions such as refreshBankConnection.

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 by saying 'now' and clarifying that ledger is required unless pinned, but it does not explicitly state when to use this instead of related refresh or sync tools. The agent must infer the triggering condition.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description earns some credit for 'applies immediately,' which tells the agent there is no staging or confirmation step, but it omits what closing implies (whether the branch is preserved, whether it can be reopened, or what collaborators see).

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

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

A single front-loaded sentence that states the action, its mechanism, and its timing with no waste.

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

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

For a two-parameter mutation tool with full annotations and an output schema, the description gives enough to select and call it correctly. The only shortfall is the absence of any note on post-rejection state or permissions.

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

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

Schema description coverage is 100%, including the nuanced defaulting behavior of the ledger parameter and the meaning of prNumber, so the schema carries the parameter semantics. The description adds nothing about either parameter and does not need to.

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

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

States a specific verb (reject) and resource (pull request) and clarifies the mechanism: closing without merging. The phrase 'without merging' implicitly separates it from the sibling mergePullRequest, though it never names that sibling directly.

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

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

Usage is only implied by the contrast with merging; there is no explicit statement of when to reject versus when to merge or close by other means, and no mention of preconditions such as required permissions or PR state.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds no behavioral context beyond restating removal: it does not say whether access is revoked immediately, whether this removes the collaborator entirely, or what authorization is required.

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

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

The single sentence is front-loaded and free of waste. However, it is so terse that it omits useful context rather than being optimally concise.

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

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

This is a destructive mutation with an output schema and 50% parameter coverage, yet the description provides no authorization requirements, side effects, or guidance on related tools. It is not complete enough for an agent to invoke it confidently.

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

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

Schema coverage is only 50%: the ledger parameter is documented but collaborator has no description. The description does not clarify the collaborator format or whether ledger is optional/defaulted, so it fails to compensate for the schema gap.

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

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

The description uses a specific verb and resource: "Remove a collaborator's access to a ledger." It is clearly distinct from add/set collaborator siblings and leaveLedger, though it does not explicitly name those 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?

There is no guidance on when to use this versus setLedgerCollaborator, leaveLedger, or other access-management tools. It also omits prerequisites such as ownership or admin rights needed to remove a collaborator.

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 substantial behavior beyond the annotations: atomicity of the commit, the refusal condition tied to include directives, the coupling with updateIncludes, the credential-pinned ledger omission rule, and the dry_run preview path. This is exactly the kind of operational context an agent needs before a mutation.

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

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

Four short sentences, front-loaded with the core action, followed by refusal semantics, credential nuance, and preview mode. No filler or repetition.

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

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

With 8 parameters, 50% schema coverage, and an output schema present, the description covers the behaviorally significant facts an agent needs. The only gap is the alias duplication (dryRun/dry_run, message/description), which could cause confusion but is at least documented 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 only 50%, but the description carries the important semantics: updateIncludes exists to rewrite include lines in the same commit, ledger can be omitted for pinned credentials, and dry_run previews. It does not address the message/description and dryRun/dry_run alias pairs, which the schema alone documents.

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

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

States a specific verb (move/rename) and resource (oldPath → newPath) with the key constraint that content is preserved in one atomic commit. This clearly separates it from deleteLedgerFiles or updateLedgerFiles, though no sibling is named 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?

Gives concrete conditional guidance: it refuses when oldPath is still `include`d unless updateIncludes rewrites those lines, and dry_run previews without committing. No explicit alternative-tool routing, but the preconditions are clear enough to select it confidently.

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

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

Annotations already declare readOnly, idempotent and non-destructive, and the description adds real behavioral context beyond them: truncation at 1,000 lines or 100 KB with a trailing truncation line, and the fact that long queries travel in a POST body with no URL-length ceiling. It omits what happens on an invalid query (error shape) and any ledger-permission/auth notes.

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

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

Front-loaded with what the tool does, then progressively adds grammar, column vocabulary, row-granularity semantics, truncation limits, and the reference link. Each sentence carries distinct operational information; the column list is long but directly actionable for query construction.

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 free-form query tool with an output schema, the description covers grammar, supported columns, result granularity, and truncation, plus a canonical reference link. The remaining gap is the relationship to runBqlQueryStructured, which matters given how many sibling tools exist.

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 both `query` and `ledger`. The description adds grammar and column vocabulary for the query string but says nothing about the `ledger` parameter (owner/name format, defaults, pinned-credential behavior), so the appropriate baseline is 3.

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

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

States a specific verb and resource — execute a BQL query against the user's ledger and return results — and immediately narrows scope with the supported statement/column grammar. It never names the sibling runBqlQueryStructured, so an agent cannot tell from the description alone which of the two to pick.

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

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

Usage is implied through the practical hint to 'add LIMIT or a narrower WHERE to see the rest' and through the row-granularity warning, which tells the agent how to shape a query for a desired result. But there is no explicit when-to-use guidance versus listLedgerEntries or runBqlQueryStructured, and no when-not 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 readOnly, idempotent, non-destructive and closed-world, and the description complements that with genuinely non-obvious context: the query travels in a POST body, so there's no URL-length limit, and the query contract matches REST JSON and GraphQL queryShell. That is real added value 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?

Three short sentences, each earning its place: what it returns, the shared query contract, and the POST/URL-length property. Front-loaded with the outcome and free of filler.

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

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

With annotations covering safety, an output schema covering return types, and full schema descriptions, the description only needs to add transport/protocol context, which it does. The missing piece is routing guidance versus the runBqlQuery sibling.

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

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

Schema description coverage is 100%, including the ledger default/credential-restriction note, so the schema already carries parameter meaning. The description adds no parameter-level detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource (Execute BQL) and describes the output shape precisely: a typed table with column names, types, and rows, or a structured text result. It does not explicitly distinguish itself from the sibling runBqlQuery, which an agent would need to know to pick correctly.

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

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

Usage is only implied by the phrase 'typed results' – one can infer this is the choice when structured/typed output matters. There is no explicit when-to-use, when-not, or comparison against runBqlQuery or any other 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the agent knows this is a write that overwrites the current value. The description adds that it 'replaces the current value,' which reinforces the destructive trait, but it doesn't mention permissions, validation requirements, error behavior, or consequences for related records.

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

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

A single short sentence with the destructive replacement behavior front-loaded. It is efficient, though it could be slightly more informative without becoming bloated.

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

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

Given the tool has full schema coverage, an output schema, and annotations covering safety/idempotency, the description is minimally adequate. However, for a destructive mutation on a linked bank account, the absence of any usage context or prerequisite warnings leaves a noticeable gap.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the ledger credential restriction, currency example, and the accountId/account_id alias relationship. The description adds no parameter-level detail beyond the schema, which is the expected baseline when coverage is high.

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

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

States a specific verb+resource: setting a linked bank account's currency. It's distinguishable from siblings like mapBankAccount, listBankConnections, or refreshBankConnection which deal with different bank-connection operations. However, it doesn't explicitly say which sibling to use for adjacent tasks (mapping vs. setting currency), leaving some 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 gives no guidance on when to use this tool versus alternatives like mapBankAccount or refreshBankConnection, nor any prerequisites such as requiring an existing linked account. Only implied usage comes from the verb 'set'.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds the permission tiers but does not explain what makes it 'destructive' (e.g., permission escalation or revoking access on downgrade) or the credentials required. A 3 is warranted with annotations carrying the disclosure burden.

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

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

A single front-loaded sentence with zero waste that captures both the add and update behaviors. Appropriately sized for the tool's scope.

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

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

An output schema exists so return values needn't be explained, and annotations cover safety. However, for a destructive mutation the description omits what happens to an existing collaborator, whether lowering permission revokes access, and the unpinned-ledger defaulting behavior mentioned 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 67%; the ledger and permission parameters are described in the schema, including the read/write/admin enum and the default behavior. The description repeats the permission values without adding syntax, format, or default details, and 'collaborator' format is undocumented in both. Baseline 3 fits where the schema does most of the work.

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

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

The description states a specific verb (add/update) and resource (ledger collaborator), and the 'add or update' framing communicates the upsert nature. It is distinguishable from removeLedgerCollaborator by implication, though no sibling is named 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 'add ... or change an existing ... permission' wording implies when this is used, but it never names the alternative (removeLedgerCollaborator) or states when-not to use it. No prerequisites or conditions are given.

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

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

Annotations already declare non-destructive, idempotent, non-read-only; the description adds the per-user scoping ('for the authenticated user') and the credential-pin default, which are not in the annotations. It stays silent on error behavior for unknown/unauthorized ledgers, but that is a modest gap given an output schema exists.

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, the action semantics first and the target-selection detail second. Every clause carries information; nothing is padding.

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

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

With annotations covering the safety/idempotency profile and an output schema handling return values, the description only needs to explain intent and the ledger default, which it does. Only edge-case behavior (invalid ledger, missing permission) is left unstated.

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 50% — the boolean 'starred' has no schema description, and the description compensates by defining both values precisely. For 'ledger' it reiterates owner/name and the pin default, mostly matching rather than extending the schema text.

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

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

States a specific verb-and-resource pair ('Set starred ... to star a ledger or unstar it') scoped to 'the authenticated user'. No sibling tool in the list touches starring, and the description makes the two-way toggle 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?

Explains exactly how to invoke for each intent: starred:true to star, false to unstar, and that ledger selects the target. It doesn't address preconditions (e.g., ledger must exist, permission to star) but no competing alternative exists to route against.

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

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

Annotations declare readOnlyHint=false, so the tool clearly writes something; the description usefully resolves the ambiguity by saying the write lands in staging and 'nothing is written to the ledger' — important context an agent cannot get from the hints alone. It adds the dry_run reporting behavior as well. It leaves idempotentHint=false unexplained (what happens on a repeat sync, duplicate staging rows?) and says nothing about the external bank call implied by openWorldHint.

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 clauses, both front-loaded: the action and destination come first, then the ledger-safety assurance and the dry_run note. Nothing is redundant and no sentence could be dropped without losing 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?

An output schema exists, so return values need no explanation, and the description covers the one thing an agent must not get wrong: this is a staging write, not a ledger mutation. What's missing is what happens to already-staged transactions across repeated syncs and whether the ledger parameter is truly optional in practice, which matters given five optional parameters.

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

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

Schema description coverage is 100% and all five parameters, including the dry_run/dryRun and itemId/item_id aliases, are already documented in the schema. The description's only added parameter meaning is that dry_run 'reports what would be pulled', which largely restates the schema text. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Pull new transactions from a linked bank') plus the destination ('into staging'), which lets an agent separate it from ledger-writing siblings like importStagedBankTransactions or insertReceiptTransaction. It stops short of naming the downstream sibling explicitly, so the differentiation is inferential rather than declared.

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

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

Usage is only implied by the staging/ledger distinction; there is no explicit 'use this before X' or 'do not call when Y' guidance. An agent must infer from the sibling list that importStagedBankTransactions is the follow-up step and that this tool is the entry point of the pipeline. No prerequisites (linked credential, bank connection existence) are stated.

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

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

Annotations already declare the tool as destructive, open-world, and non-idempotent, so the safety profile is largely covered. The description adds that linking is out of scope and that dry_run reports what would be removed, but it does not explain reversibility, auth requirements, or exactly what data is severed.

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 short sentences and front-loads the core action. The linking context is useful, while the dry_run sentence is somewhat redundant with the schema. Overall it is efficient but not maximally tight.

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

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

Given the destructive annotation, full schema coverage, and an output schema, the description supplies the key workflow context that linking is elsewhere and that dry_run is available. It could still say more about consequences and the role of itemId/ledger, but it is broadly complete for invocation.

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

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

Schema description coverage is 100%, so the schema already documents itemId, item_id, ledger, dryRun, and dry_run. The description only mentions dry_run and does not add meaning beyond the schema for the identifier, ledger targeting, or alias parameters. This matches the baseline 3 for high 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 uses a specific verb and resource: "Sever a linked bank connection." It also clarifies that new bank linking happens elsewhere, which helps distinguish this from related bank workflows. However, it does not explicitly name sibling alternatives such as refreshBankConnection or listBankConnections.

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

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

The description gives a clear usage boundary by stating that linking a new bank happens in a browser through the bank's widget, not here. It also notes the dry_run preview behavior. It does not state explicit prerequisites, such as needing itemId or how to choose between unlink and refresh.

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 destructiveHint=true and idempotentHint=false already declared, the description still adds substantial context: the commit message is auto-composed with no message argument, the returned hash invalidates the request's hash, and the specific error codes (RESOURCE_LIMIT_REACHED, VALIDATION_FAILED, UNBALANCED) are enumerated with their trigger conditions and the allowInvalid escape hatch.

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

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

Front-loads the operation and addressing scheme, then layers error semantics. Dense and information-rich, though several clauses are packed into long sentences that could be split for faster scanning.

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

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

For a destructive write with a complex validation model, the description covers addressing inputs, return value, hash staleness, the two failure classes and overrides, and the dry-run preview. An output schema exists, so return-shape explanation is not required beyond the newEntryHash note.

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?

At 78% schema coverage the schema already documents most parameters, yet the description adds real meaning: where sha256sum and entryHash come from, the alias relationships, and the refuse-vs-allowInvalid behavior tied to that parameter. It does not mention the ledger parameter's unpinned-credential default, leaving one documented gap.

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

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

States a specific verb and resource ('Replace one entry's source text with newContent') and names the addressing inputs from specific sibling tools, which distinguishes it from deleteEntrySource, addLedgerEntries and appendLedgerText without needing the schema.

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

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

Explains the addressing workflow (hash from listLedgerEntries, sha256sum from getEntryContext) and when to use dry_run or allowInvalid, giving clear operating context. It lacks an explicit 'use X instead when...' contrast against delete/add sibling tools, so it stops short of 5.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the description is not required to carry the safety profile. It adds the merge-semantics context, but says nothing about what makes the operation destructive (e.g., renaming side effects on references) or auth requirements, which is the extra context that would earn a 4–5.

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

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

A single sentence, front-loaded with the action and the affected fields, with the omitted-field behavior as a trailing qualifier. 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?

An output schema and annotations reduce the burden, but the description omits the ledger-target concept and any consequence of the destructive rename/privacy change. Adequate for a simple patch tool, but not complete.

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

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

Schema coverage is 75%, so the schema largely documents parameters (including the 'private' public/private semantics and name pattern). The description mirrors three of the four fields but never mentions the `ledger` target parameter (owner/name), which is the key addressing input for an unpinned credential.

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

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

States a specific verb ('Change') and resource ('a ledger') plus the exact mutable fields (name, description, privacy), which clearly separates it from createLedger, deleteLedger, and deleteLedgerFiles. It stops short of naming any sibling explicitly, so 5 isn't warranted.

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?

'Omitted fields stay as they are' gives useful partial-update semantics, implying this is a merge/patch operation rather than a full replace. However, there is no guidance on when to use this versus siblings such as createLedger or on any prerequisites (permissions, whether a ledger must already exist).

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

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

With annotations already declaring destructive=true and idempotent=true, the description adds substantial behavioral detail the annotations cannot convey: atomic commit semantics, the old_string-must-appear-exactly-once rule, sequential application of multiple items to one file, the sha-based refusal on concurrent change, the 1 MiB UTF-8 limit, and exactly what dry_run returns (same refusals plus a unified diff and bean-check verdict). No contradiction with readOnlyHint=false / destructiveHint=true.

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

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

Three dense sentences, front-loaded with the core action, and every clause carries real information. It is slightly over-packed with nested parentheticals, which costs a bit of readability, but there is no filler.

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

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

The tool is a destructive mutation with six parameters and an output schema (return values need not be described). The description still covers atomicity, refusal conditions, size limits, ordering, and dry-run output, leaving no material gap for correct invocation.

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

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

Schema coverage is already 83%, so parameters are largely self-describing; the description's added value is the ordering/chaining semantics ('several items for one file apply in order, each to the text the previous one produced') and the sha-guard purpose, neither of which is in the schema. It does not cover the dryRun/message/ledger alias parameters, which is a minor gap.

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

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

States a precise verb and resource — 'Change existing text files in one atomic commit' — and enumerates the two per-file modes (exact-text replacement vs. full overwrite). The word 'existing' implicitly distinguishes it from createLedgerFiles/deleteLedgerFiles, and the sibling readLedgerFiles is named as the source of the sha guard.

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

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

Clearly explains how to choose between the two item shapes (old_string/new_string vs. content, with sha for optimistic concurrency) and when to use dry_run. It does not explicitly route away from appendLedgerText or createLedgerFiles, so the agent must infer those boundaries, but the operating context is unambiguous.

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