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

With no annotations provided, the description carries the transparency burden and does disclose the key side effect: the directives are appended and committed. 'One validated commit' adds useful behavior around atomicity/validation, though it does not go into authorization, reversibility, or failure behavior.

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

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

The description is compact and front-loaded: the core behavior appears in the first sentence and the usage scenario in the second. There is 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?

Given the tool's moderate complexity, an output schema, and a clear scope statement, the description is mostly sufficient for an agent to select it. The main gaps are parameter-level detail and explicit comparison to sibling tools, but these are minor for batch-selection purposes.

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

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

Schema coverage is 0%, and the description does not explicitly explain how beancount_text or message map to the call. The tool purpose strongly implies beancount_text contains the directives, but the 'message' parameter is completely undocumented and the input format for beancount_text is left to inference.

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

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

The description states a specific action ('Append arbitrary Beancount directives') and the commit behavior, and distinguishes the tool from siblings by listing the directive types it handles in batch ('opens, balances, transactions and prices'). This makes its purpose clear and separable from add_transactions/open_accounts.

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

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

The description explicitly says 'Use for batch setup' and gives the concrete scenario ('set up my whole situation'). It implies when to prefer this over single-purpose siblings, but does not explicitly name alternatives or state when not to use it.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses validation via bean-check, atomic commit semantics ('only committed if valid'), no partial writes on failure, and the balancing requirement for postings. This gives the agent confidence about side effects and failure behavior.

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

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

The description is compact and front-loaded with the core purpose, followed by concise behavioral notes. Every sentence earns its place: purpose, validation/commit behavior, and prerequisite.

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

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

For a single-parameter append operation with an output schema, the description covers the key contextual gaps: what is appended, how validation works, what happens on failure, posting balance requirements, and the prerequisite for opening accounts. No critical information is missing.

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

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

Schema description coverage is 0%, so the description must explain the parameter. It does: the parameter is described as raw Beancount syntax, and the text must be valid and balanced. While no explicit example or detailed format is given, the meaning of 'beancount_text' is clearly conveyed.

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

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

The description begins with a specific verb 'Append' and identifies the resource: 'one or more transactions (raw Beancount syntax) to the book.' It clearly distinguishes this from sibling tools like open_accounts and get_ledger by specifying the append action and the Beancount syntax requirement.

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

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

The description gives clear usage context by explaining when validation occurs and explicitly instructs 'Open any new accounts first (open_accounts).' It does not explicitly list when not to use the tool or name alternatives, but the prerequisite guidance is actionable and sufficient.

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 no annotations provided, the description carries full behavioral burden and handles it well. It explicitly warns not to compute own figures, not to extrapolate past the coverage window, and explains how to interpret `sufficient: false`. It also explains why only complete months are averaged, giving concrete reasoning about partial-month distortion.

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

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

The description is front-loaded with the core purpose and follows with a useful list of output categories and important behavioral constraints. It is slightly repetitive ('Read this and report it' near 'Do NOT compute your own figures'), but every section earns its place and the length is appropriate for the complexity.

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

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

The tool takes no parameters, so the main need is clarity about what the agent should expect and how to handle edge cases. The description covers outputs, constraints, and the meaning of sufficient: false. It could be even stronger with a one-line statement about when to choose this over generate_report or balances, but the absence of parameters and presence of an output schema make this sufficient.

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

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

The input schema is empty (0 parameters), so there are no parameter semantics to clarify. The description adds meaningful information about what the tool produces, which compensates for the lack of any input surface. No parameter documentation is needed here.

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

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

The description clearly states the tool's function: 'Review the book and return COMPUTED facts about it as JSON' and enumerates the specific fact categories (coverage, income/expense, runway, category shares, etc.). It does not explicitly differentiate from siblings like get_ledger or balances, but the emphasis on 'computed facts' and the listed outputs make the tool's role distinct enough.

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 this tool is for retrieving pre-computed assessment facts rather than raw ledger data or user-computed figures. However, it never explicitly says when to choose this over siblings such as get_ledger, balances, or generate_report, nor does it state exclusions like 'use balances for raw account balances instead'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by stating that the tool blocks until approval, decline, or expiration, and that success saves the connection and switches all countbean tools to that book. This gives the agent a clear model of the side effects and waiting semantics.

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 highly concise: two short sentences, front-loaded with the step sequence and ending with the key side effect. Every sentence earns its place without redundant or generic filler.

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

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

Given the tool's zero-parameter interface and the availability of an output schema, the description is complete. It explains what triggers the wait, what it blocks on, and what happens on success, which is all an agent needs to safely invoke this tool in the correct flow position.

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

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

The tool has zero parameters and the schema is empty with 100% description coverage, so the baseline of 4 applies. The description adds context about the originating code from `start_device_authorization`, but no parameter documentation is needed because none exist.

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

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

The description clearly identifies the tool as 'Step 2' in a device authorization flow: waiting for user approval of a code from `start_device_authorization`. This distinguishes it from siblings like `start_device_authorization` (which initiates the flow) and `connect_book` (which may establish a connection by other means).

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

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

The description explicitly places the tool in sequence ('Step 2') and references `start_device_authorization` as the prerequisite, giving clear usage context. It describes the blocking wait and post-success behavior, but it does not explicitly state when to avoid this tool or name alternative connection methods.

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?

No annotations are provided, so the description carries the behavioral burden. It discloses that the tool performs a read-style query ('Show balances'), groups by account, and supports regex filtering. It does not explicitly state side-effect freedom or auth requirements, but the wording makes the query nature sufficiently clear.

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

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

Two concise sentences with no filler. The main purpose is front-loaded, and the parameter explanation immediately follows in the second sentence.

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

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

With only one optional parameter and an output schema available, the description covers what the tool does and how to filter. It does not discuss edge cases like empty results or regex syntax details, but these are not critical for a tool this simple.

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

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

The input schema only provides a type and default for account_filter, with 0% schema description coverage. The description fully compensates by explaining that account_filter is a BQL regex and providing concrete examples like 'Assets' and 'Expenses:Food'.

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: 'Show balances grouped by account'. It clearly states the core behavior and the optional filtering. It does not explicitly distinguish itself from sibling tools like list_accounts or get_ledger, 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?

The usage context is implied: use this tool when you need balances grouped by account, optionally narrowed by a regex. However, it gives no explicit guidance about when not to use it or which sibling tool might be a better fit, such as list_accounts or run_query.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It lists output-related fields but never states that the operation is read-only, whether it requires an authenticated connection, or what happens when no book is active. This is a meaningful gap for an agent deciding whether it is safe and appropriate to 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?

The description is a single sentence with every word contributing: the verb, the resource, and the included summary fields are all present. There is no padding or redundant detail, 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?

For a no-parameter status tool with an available output schema, the description covers the resource and the main summary contents well. The only notable omission is an explicit connection prerequisite, but that is reasonably inferred from the phrase 'current book' and the sibling connect_book/connection_status tools.

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

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

The tool has zero parameters, so parameter semantics are not a concern; the description's 'current book' phrasing correctly communicates that the tool acts on the established book context rather than taking inputs. The zero-parameter baseline of 4 applies.

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

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

The description opens with a specific verb, 'Summarise', and identifies the resource as 'the current book', then enumerates the summary contents: location, account count, balances, and last commits. This makes its role as an overview tool reasonably clear, though it does not explicitly contrast itself with sibling tools like balances or list_accounts.

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 a use case: returning an overview of the currently connected book. However, it does not state when to prefer this tool over more focused siblings such as list_accounts, balances, get_ledger, or history, nor does it mention prerequisites like needing an active book connection.

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 no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses persistence, live verification before saving, the exact storage location and permissions (~/.countbean/credentials.json with 0600), immediate effect without restart or environment variables, and optional reuse of a previously connected book.

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

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

The description is front-loaded with the core purpose and then adds valuable operational details. It is slightly longer than needed, and the instruction to paste both values on one line is a bit ambiguous, but most sentences earn their place by explaining behavior or parameter usage.

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 no annotations and 0% schema parameter coverage, the description covers the common invocation path well: required key, optional book id, persistence, and effect timing. The missing control_url explanation and lack of failure-mode detail keep it from being fully complete, but an agent has enough to call it correctly in the standard case.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It does explain api_key (the cbk_ key shown once) and book_id (the bok_ id, optional if already connected), but control_url is completely unaddressed. This leaves one of three parameters under-specified despite strong coverage of the other two.

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

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

The description opens with a specific verb and resource: 'Connect this plugin to a hosted Countbean book, permanently.' It clearly distinguishes itself from siblings like disconnect_book and connection_status by signaling this is the establishment action, not a teardown or status check.

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

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

The description gives clear context for when to use the tool: during initial setup, with the key from the book's page, and before other operations take effect. It does not explicitly name alternatives like disconnect_book or connection_status as contrasts, but the workflow is unambiguous enough for an agent to select it appropriately.

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?

No annotations are provided, so the description carries the disclosure burden. It usefully reveals precedence behavior (Environment > .env > saved connection), and 'Show' implies read-only, but it does not explicitly state that the tool has no side effects or how it behaves on failure.

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

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

The core action is front-loaded in the first sentence. The second paragraph adds useful situational context but uses rhetorical framing that is slightly longer than necessary; still, the description remains compact and readable.

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

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

For a zero-argument diagnostic tool with an output schema, the description covers what the tool reports and why it matters. It does not enumerate output fields, but that is appropriately delegated to the output schema.

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

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

The tool has zero parameters and 100% schema description coverage, so there is nothing for the description to add. The baseline of 4 applies because parameter semantics are fully handled by the empty schema.

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

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

States a specific verb ('Show') and resource: the currently connected book and the winning config. This clearly differentiates it from generic status tools by focusing on which configuration won.

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

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

Gives a clear diagnostic trigger: use when something looks wrong and you need to know which configuration was selected. It does not explicitly name sibling alternatives like book_status, but the situational context is strong enough for an agent to select it.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that the tool creates a resource ('Initialise'), that the book is 'empty' and 'git-backed', and that it errors on duplicate creation. This goes beyond a bare 'create' statement and gives the agent useful operational expectations.

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

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

The description is extremely concise: two sentences, with the core action front-loaded and the key constraint in a single follow-up sentence. Every word adds value and there is no redundant or filler content.

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

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

For a simple creation tool with two optional parameters and an output schema present, the description covers the essential behavior and a critical failure mode. It could be slightly more complete by clarifying the meaning or allowed formats of 'name' and 'currency', but overall an agent has enough context to invoke it correctly.

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

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

The input schema provides only parameter names ('name', 'currency') with defaults but no descriptions, and the description does not explain either parameter. While the names are somewhat self-explanatory in context, the description adds zero semantic detail, leaving the agent to infer what values are appropriate for each optional parameter.

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

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

The description states a specific verb ('Initialise') and a concrete resource ('a new, empty cloud book (git-backed Beancount ledger)'), making the tool's function immediately clear. It also implies the distinction from the sibling connect_book, which targets existing books, so an agent can tell them apart.

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

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

The description gives a clear usage constraint: 'Safe to call once per book; errors if a book already exists at the location.' This tells the agent when to invoke it (creation) and warns against duplicate calls, though it does not explicitly name connect_book as the alternative for existing books.

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 no annotations, the description carries the behavioral disclosure burden. It discloses the key consequence: the key stays valid after this operation, and points to a separate path for actual revocation. This meaningfully clarifies the tool's non-destructive nature beyond what the name alone suggests.

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 one compact sentence with a parenthetical that earns its place. It front-loads the primary behavior and then gives the crucial limitation and alternative without extra clutter.

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

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

For a zero-parameter tool with an output schema available, the description fully covers what the tool does, its side effect on the key, and what to do if full invalidation is intended. Nothing necessary for correct invocation is missing.

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

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

There are zero parameters, so parameter semantics are trivially satisfied. The description still adds useful context about what gets forgotten, exceeding the baseline for a no-parameter tool.

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

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

The description uses a specific verb and resource: 'Forget the saved hosted-book connection.' It clearly differentiates this from sibling tools like connect_book and connection_status by indicating it removes the local saved connection rather than creating or checking one.

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

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

The description implies when to use this tool: when you want to stop using a saved connection while keeping the underlying key valid. It also gives an explicit alternative—'revoke it on the book's page if you want it dead'—which helps an agent choose between disconnecting and revoking.

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 no annotations, the description carries the behavioral disclosure burden. It does disclose output formats, xlsx sheet contents, and the fact that a file path is returned. However, it omits important behavior around the as_of parameter, prerequisites like a connected book, and file lifecycle details such as overwriting or temporary files.

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

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

The description is compact and front-loaded, with every sentence contributing useful information. The format block is minimal and scannable, and there is 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?

Although the output schema exists and the return path is mentioned, the description is incomplete for invocation because the as_of parameter is unexplained and no preconditions or alternative routing are given. An agent would likely need extra reasoning to use this tool correctly in a nontrivial case.

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

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

Schema description coverage is 0%, so the description must compensate. The 'format' parameter is well explained with concrete options and sheet contents, but the 'as_of' parameter is completely undocumented, leaving a major semantic gap for a financial report tool.

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

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

The description states a clear verb ('Generate') and resource ('financial report from the book'), and adds meaningful detail about supported formats and output. It does not explicitly distinguish itself from sibling tools like balances or assess_book, 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?

No guidance is provided about when to choose generate_report over sibling tools such as run_query, balances, or get_ledger. The description explains what the tool does but not the conditions or context that make it the right choice.

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?

No annotations are provided, so the description carries the disclosure burden. It does disclose the output scope ('full') and format ('plain-text'), and 'Return' implies a read-only operation, but it does not explicitly state read-only behavior, prerequisites such as an active book/connection, or failure modes. This is adequate for a simple getter but not richly transparent.

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

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

One concise sentence with no filler. The verb, resource, and contents are front-loaded, and every word adds 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?

With zero parameters and an output schema present, the description need not explain return values in more detail. The only missing context is prerequisite state (e.g., needing a connected or created book) and an explicit read-only guarantee, but the low complexity makes this sufficient for correct invocation.

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

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

The tool has zero parameters, so the description has no parameter semantics to document; the baseline of 4 applies. The note about accounts, transactions, and prices describes the returned payload, not arguments, so there is no coverage 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 ('Return') and resource ('full plain-text ledger'), and enumerates contents ('accounts, transactions, prices'). It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools like list_accounts, balances, or run_query; the differentiation is only implicit through 'full' and 'plain-text'.

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

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

There is no explicit when-to-use guidance or named alternatives. The phrase 'full plain-text ledger' implies the agent should call it when the entire ledger text is needed, but it never contrasts this with list_accounts or run_query, leaving selection mostly 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?

With no annotations, the description carries the full burden. It usefully explains commit granularity (each AI/human change is one commit) and 'Show' suggests a read-only operation, but it does not explicitly state side-effect-free behavior, ordering, or how the limit parameter affects results.

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 one concise sentence with no filler. It front-loads the core purpose and adds a clarifying detail about commit granularity without unnecessary elaboration.

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, has one optional parameter, and an output schema exists, so not much is missing. However, the description assumes 'the book' refers to the currently connected book without saying so, and it fails to define the limit parameter semantics.

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

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

Schema description coverage is 0% and the description does not mention the limit parameter. The only parameter is left to be inferred from its name and default value, so an agent may not know whether limit caps the number of commits, the time range, or something else.

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

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

The description names a specific verb ('Show') and resource ('the book's git history'), and the parenthetical clarifies that each AI or human change is one commit. This distinguishes it from sibling tools like run_query, get_ledger, and balances, which deal with current data rather than change history.

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 this tool is for viewing historical changes, but it gives no explicit guidance on when to use it versus alternatives such as get_ledger or run_query. There are no exclusions or conditions to help an agent choose between history and similar read-oriented tools.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. 'List' implies a read-only operation and 'currently open' indicates live state, but the description does not mention ordering, pagination, or whether the result reflects the connected book. This is adequate but not fully transparent.

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

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

The description is a single, front-loaded sentence with no wasted words. Every term adds meaning: 'every', 'account', 'currently open', and 'in the book' all clarify scope and behavior.

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

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

Given the zero-parameter schema and the presence of an output schema, the description is nearly complete. It clearly states what is returned (accounts) and under what condition (currently open), though it could more explicitly reference the connected book or expected output shape, but the output schema likely covers that.

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

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

The tool has zero parameters, so the baseline of 4 applies. The description does not need to explain parameter meaning because there are none to document.

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 ('List') and resource ('every account currently open in the book'), making the tool's function immediately clear. It also distinguishes itself from the sibling 'open_accounts' by focusing on enumeration rather than creation or modification.

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

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

The description provides clear context: use this tool to get the current set of open accounts. It does not explicitly name alternatives or when not to use it, but for a zero-parameter list operation this context is sufficient.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says the tool 'adds' directives to the book, implying mutation, but does not explain validation behavior, handling of duplicate accounts, idempotency, or failure modes. The example helps but does not compensate for the lack of behavioral context.

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

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

The description is two sentences with no filler. The purpose is front-loaded, and the example earns its place by illustrating exact input format.

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

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

For a single-parameter tool with an output schema available, the description is minimally viable: it gives the purpose and an example. But it lacks usage comparisons with add_directives and fails to describe any behavioral constraints, leaving the agent to guess about validation and edge cases.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented beancount_text parameter. The example '2026-01-01 open Assets:Checking USD' gives a concrete format, which is useful. However, it does not clarify whether the string may contain multiple directives or how comments/whitespace are handled.

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

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

The description names a specific verb and resource: it adds account open, close, or commodity directives to the book. The example further clarifies the exact directive format. It does not explicitly contrast with sibling tools like add_directives, but the scope is clear enough.

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

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

Usage is implied by the directive types listed: open, close, and commodity. However, there is no explicit guidance about when to use this tool instead of add_directives or add_transactions, and no exclusions 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?

There are no annotations, so the description carries the full transparency burden. It discloses that the tool never writes, returns JSON, flags values below the confidence floor rather than returning them, reads the book's open directives, and validates account/currency issues early. This is exceptionally transparent for a mutation-adjacent 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 long but appropriately dense for a 19-parameter tool with no annotations. It front-loads the core purpose and bolds the most important behaviors. A little phrasing is colorful rather than purely functional, but each sentence adds 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?

It covers the high-risk aspects: no writes, flagging behavior, receipt currency/account alignment, and the downstream approval flow. The output schema covers return shape. The main gap is lack of explicit instruction that the required receipt_sha256 comes from the prior stage_receipt step and slight ambiguity around line_items_json structure.

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

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

Schema description coverage is 0%, so the description must compensate. It meaningfully explains the confidence floor, confidence fields, expense_account/paid_from_account, and exchange_rate semantics. However, it leaves a few non-obious params like receipt_sha256, line_items_json, and operating_currency without explicit explanation, so it is not fully complete.

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

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

The description opens with a specific verb and resource: 'Turn what you read off a staged receipt into a PROPOSED transaction.' It also explicitly differentiates itself from the write path by saying 'It NEVER writes' and pointing to add_transactions as the subsequent commit step, so an agent can distinguish it from 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 gives a clear workflow: supply the reading and per-field confidences, review flagged fields, then pass the returned beancount to add_transactions unchanged. It also states operational rules such as the confidence floor being raisable but never lowerable and exchange_rate being taken from the card statement, never invented.

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 no annotations provided, the description carries the full burden — and it exceeds it. It discloses that the tool never writes, returns JSON proposals, flags ambiguous rows with '!' that must not be silently promoted, preserves import-id metadata for deduplication, and instructs the agent to open accounts_to_open and show counts first. This is comprehensive side-effect and workflow disclosure far beyond a typical description.

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

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

The description is long but every section earns its place given 13 parameters and zero schema coverage. It is well-structured: scope first, non-writing behavior second, then the two required parameters, then a bolded post-processing checklist, then a compact overrides list. Key warnings ('THIS TOOL NEVER WRITES', 'NOT a path', 'Keep the ! flags') are front-loaded and emphasized.

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

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

For a tool with 13 parameters, no annotations, and 0% schema coverage, the description is complete. It covers the tool's purpose, its safety profile (read-only), the two required parameters, the meaning of every override, and the critical post-processing obligations. Though an output schema exists, the description still explains the essential result fields (mapping, ambiguities, accounts_to_open, counts) because they dictate agent action steps.

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

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

Schema description coverage is 0%, so the description must compensate — and it does thoroughly. 'content' is explained as base64-encoded bytes or pasted text (not a path), 'account' gets a real-world example ('Assets:Checking'), and every override is listed with its value set: amount_shape ('signed' | 'debit_credit' | 'balance'), columns with a JSON example, date_format as strptime, decimal_separator ('.' or ','), sign ('normal' | 'inverted'), and opening_balance with its purpose. This fully compensates 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 opening sentence states a specific verb and resource: 'Parse a bank statement (CSV or OFX/QFX) into PROPOSED transactions.' It differentiates itself from the sibling add_transactions by explicitly declaring 'THIS TOOL NEVER WRITES' and that it 'returns proposals as JSON.' An agent can immediately distinguish it from all 19 sibling tools.

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

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

The description explicitly names the alternative and the condition that selects it: 'add_transactions is still the only way anything reaches the book.' It also explains that content is 'NOT a path' because the hosted agent has no shared filesystem, clarifying an important usage constraint. The 'WHAT YOU MUST DO WITH THE RESULT' section further instructs the agent on the proper follow-up 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?

With no annotations, the description carries the burden and usefully discloses that the revert is non-destructive in the sense that it creates a new commit rather than rewriting history. It does not address edge cases like conflicts or failed reverts, but the core safety-relevant behavior is stated.

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

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

A single, well-formed sentence that front-loads the operation and its effect without extraneous detail. Every word earns its place.

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

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

The description explains the core operation and the output schema covers return values, but the lack of commit-format guidance and absence of usage alternatives leave some context gaps for a tool with one required parameter.

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

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

Schema coverage is 0%, and the description adds almost no detail about the 'commit' parameter beyond calling it 'specific'. It does not specify the expected format (SHA, ref, etc.) or any constraints, so an agent has to infer how to identify the commit.

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 precise verb ('Revert'), a resource ('a specific commit'), and the resulting behavior ('creating a new commit'). This is unambiguous and distinct from the sibling tools, none of which perform revert-like operations.

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

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

It clearly establishes when to use the tool: to undo a specific commit. It does not explicitly compare with alternatives or state when not to use it, but no obvious revert alternative appears among the siblings and the context is clear enough.

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

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

No annotations are provided, so the description alone must convey behavioral traits. It does disclose that the operation returns CSV-style rows, which describes the response shape, and the word 'query' suggests a read-only operation. However, it does not state whether this mutates the ledger, what errors occur on invalid BQL, or whether any connection/book must be active.

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 crisp sentences: a definition and a representative example. The main action is front-loaded and there is no filler, so the description is appropriately concise for a single-parameter 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?

The description is adequate for a simple query tool, and the presence of an output schema relieves it from detailing return values. However, it omits context about which book the query runs against and whether a connection is required, which is relevant given the connection-oriented sibling tools.

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

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

Schema coverage is 0%, so the description must compensate. The example `SELECT account, sum(position)...` demonstrates valid BQL syntax and clarifies that `bql` is the query string. Still, it does not explain the full scope of BQL constructs, placeholders, or constraints, so the parameter meaning is only partially enriched.

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

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

The description opens with a concrete verb phrase 'Run a Beancount Query Language (BQL) query' and specifies the output format ('return CSV-style rows'), making it immediately distinguishable from sibling tools like list_accounts or balances. The example query adds concrete context for what kinds of statements are accepted.

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 the tool is for executing arbitrary BQL, but it does not state when to prefer it over sibling tools such as list_accounts, balances, or get_ledger, nor does it mention any prerequisites (e.g., an active connection). No when-not guidance is present.

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 no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers substantial detail. It warns that the tool does not look at the image, so the agent must read it itself, and it clarifies that declared_name is used for nothing else. It also discloses the return payload (bucket key and content hash) and the intended downstream handoff.

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

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

The description is front-loaded with the core purpose and the critical 'call first' instruction. Each sentence contributes: parameter distinctions, return value, downstream handoff, and the warning to read the image. The brief rationale about evidence adds context without bloating the definition.

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

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

For a tool with an output schema already present, the description covers all operational context: when to call it, how to choose parameters, what it returns, what to do with the result, and what the tool does not do. It is complete enough for an agent to invoke stage_receipt correctly without needing additional documentation.

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

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

Schema description coverage is 0%, so the description must explain all three parameters, and it does. file_path is defined as a photo or PDF on the machine via the plugin path; content_base64 is for chat agents with no shared filesystem; declared_name is explicitly marked as recorded-only and not used for type or storage decisions. This fully compensates for the empty 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?

The description opens with a specific verb and resource: 'Store a receipt photo or PDF as evidence and return a reference to it.' This clearly distinguishes the tool from its sibling propose_receipt_transaction, which is explicitly named as the later step. An agent can immediately understand what the tool does and what it does not do.

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

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

The description gives explicit when-to-use guidance: 'Call this FIRST, before proposing anything.' It also tells the agent exactly what to do with the result: 'Pass both to propose_receipt_transaction.' The either/or parameter guidance for file_path vs content_base64 provides clear selection criteria based on the agent's environment.

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 no annotations, the description carries the burden and does well: it states the call returns IMMEDIATELY with a short code and link, does not wait for approval, and warns that a combined tool would expire. It doesn't mention rate limits or auth prerequisites, but the core non-blocking behavior is clearly 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?

Front-loaded with purpose, then behavior, then rationale. The design explanation is somewhat lengthy but earns its place by preventing an agent from calling this as a blocking or standalone connection step.

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 immediate-return flow and next step are well covered, and an output schema exists for return values. However, the meaning of the only parameter is missing, and the relationship to connect_book is not clarified, leaving a real 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 description coverage is 0% and the description never mentions control_url. The agent is left to guess what this optional string means and how to populate it. The sole parameter is completely unexplained.

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

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

Opens with 'Step 1 of connecting a hosted book: get a code for the user to approve', naming a concrete verb and resource. It also positions itself against await_device_approval, so an agent can clearly distinguish this step from the waiting step.

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

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

Explicitly instructs the agent to show the returned code and link to the user, then call await_device_approval to wait. The explanation of why the tool is split into two steps reinforces that this call should not be treated as a blocking completion, which is strong usage guidance.

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