journalize

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

With no annotations, the description must disclose behavioral traits. It states the output is Beancount text and not the live store, and reveals the free allowance sharing. However, it does not mention whether the operation is read-only (implied), any rate limits, or potential side effects, leaving notable gaps.

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

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

The description is exceptionally concise: two sentences that convey purpose, intended use, and a critical restriction. Every sentence adds value, and the key information 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?

Despite the good purpose and conciseness, the description lacks details about return format (beyond 'Beancount text'), does not explain parameters, and omits any mention of size limits or output structure. With no output schema, these gaps hinder full understanding of the tool's behavior.

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% (no parameter descriptions in schema). The tool description adds no information about any of the 5 parameters (public_key, nonce, timestamp, signature, payment_header), failing to clarify their purpose or required format. This leaves agents without necessary guidance to construct valid calls.

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's action: 'Export the full ledger as literal Beancount text'. It explicitly distinguishes from sibling tools by stating it's for a portable snapshot, not the live store, and mentions related report-tier 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?

Provides explicit guidance on when to use (for Beancount export) and a critical constraint: shares a combined free allowance of 2 with get_balance_sheet, get_income_statement, and get_trial_balance. This helps agents make informed decisions about tool selection and usage limits.

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

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

The description discloses that billing is fixed regardless of account existence and that there is no per-error discount, which adds transparency beyond the schema. However, it does not mention side effects or safety (e.g., read-only nature), and since no annotations are provided, the description carries the full burden but leaves some behavioral traits unclear.

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

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

The description is three sentences, with the first sentence clearly stating the purpose. The subsequent sentences add billing context, which is helpful but slightly verbose. Overall, it is concise enough, though the pricing information could be more integrated.

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

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

Given the tool's complexity (6 parameters, no output schema, no annotations), the description is incomplete. It only covers billing behavior and omits critical details like parameter formats, return value structure, error handling, and authentication context, leaving significant gaps for an agent to use the tool correctly.

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

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

The input schema has 6 parameters with 0% description coverage, and the tool description does not explain any of them (nonce, timestamp, signature, account, public_key, payment_header). With no additional meaning provided, the description fails to compensate for the schema's lack of detail.

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 starts with 'Balance of a single account', which clearly specifies the verb (get balance) and resource (single account). It distinguishes itself from sibling tools like list_accounts (which lists accounts) and get_balance_sheet (which is a broader report), so the purpose is specific and well-defined.

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

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

The description explicitly states that this tool has no free-trial allowance, unlike list_directives and list_accounts, providing clear cost-based guidance on when to use this tool versus those siblings. However, it does not differentiate from other balance/report tools like get_balance_sheet, which is a minor gap.

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

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

No annotations exist, so description carries burden. It discloses caching behavior, fixed pricing regardless of cache hit/miss, and shared free allowance. Does not mention authentication or error behavior, but key behavioral traits are covered.

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 concise sentences, but the second sentence ('Settles at the same fixed price regardless of cache hit/miss') is somewhat redundant with the first. Efficient overall, with key information front-loaded.

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

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

With five required parameters, no output schema, and no annotations, the description lacks completeness. It does not explain user requirements, return format, or parameter purposes, leaving significant gaps despite reasonable pricing and caching 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 0%, and the description adds no information about any of the five parameters. Without explanation of nonce, signature, public_key, timestamp, or payment_header, the description fails to aid parameter usage.

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

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

Description clearly states the tool retrieves a 'Full realize() balance sheet', mentioning caching and pricing behavior. It distinguishes itself from siblings by noting it belongs to the 'report tier' with a shared free allowance.

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

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

Explicitly states the shared free allowance with three sibling tools ('report tier'), providing cost context. However, it does not specify when to use this tool over others or any prerequisites.

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 burden. It discloses important internal behavior: always books full history first then clamps output to requested period, never filters input dates, and explains the rationale. It also reveals the combined free allowance limitation. However, it does not describe the return format or any side effects, which limits transparency slightly.

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

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

The description is concise with no wasted words. It front-loads the purpose and scoping, then adds behavioral details. Slightly technical language but still clear. Could benefit from structuring parameter explanations separately.

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 complexity (7 parameters, no output schema, no annotations), the description provides good context on period scoping, internal processing, and quota sharing. However, it lacks descriptions for the majority of parameters and does not mention output structure or error conditions, leaving gaps for an agent to infer.

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 parameters. It only covers 'since' and 'until' (ISO date strings, optional) but omits all five other parameters (public_key, nonce, timestamp, signature, payment_header), leaving their purpose unexplained. This is a significant 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 clearly identifies the tool as providing an income statement period-scoped by 'since' and 'until' dates. It distinguishes from sibling tools implicitly by its name and the mention of sharing a combined free allowance with specific report-tier tools (export_ledger, get_balance_sheet, get_trial_balance), but does not explicitly contrast with them.

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

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

The description provides usage guidance about the period-scoping parameters and the shared free allowance, but does not explicitly state when to use this tool over alternatives like get_balance_sheet or get_trial_balance. The mention of the allowance is a constraint, not a selection guide.

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 bears full burden. It discloses that it is priced and audited separately and shares a combined allowance. This provides useful context about resource consumption, but it does not cover other behavioral aspects like side effects, rate limits beyond the allowance, or authentication requirements (though auth params are in 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 consists of two concise sentences that convey key information about scoping, pricing, and shared allowance without extraneous content. It is well-structured and front-loaded.

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

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

Given the lack of output schema and parameter descriptions, the description is incomplete. It provides context on pricing and sibling relationships but fails to describe the return format, parameter details, or when to use this tool over others. The agent would need additional information to invoke the tool correctly.

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

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

Schema description coverage is 0%, and the description fails to explain any of the 7 parameters. The only hint is 'period-scoped', which relates to since/until, but no details on format, requirement, or payment_header. The agent has very little guidance on how to fill the parameters.

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

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

The description states it returns a trial balance scoped to a period, similar to the income statement. It distinguishes itself by noting it is a separate resource for pricing and auditing. However, the description does not use an explicit verb phrase like 'retrieves trial balance', but the tool name implies the action.

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

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

The description mentions that it shares a combined free allowance of 2 with export_ledger, get_balance_sheet, and get_income_statement, implying limited usage and suggesting consideration of other report tools. However, it does not explicitly advise when to use this tool instead of siblings or provide exclusions.

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

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

No annotations provided; description adds 'No booking pass involved' and free call allowance, clarifying read-only nature and usage constraints. Lacks explicit read-only declaration but adequate for a list 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 sentences, no fluff, front-loaded with main purpose. Could integrate parameter hints but remains 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?

Despite clear purpose, lacks parameter explanations, authentication details, response format, and error conditions. With 5 required params and no output schema, description is incomplete.

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%, yet description adds no meaning to any of the 5 parameters (nonce, signature, timestamp, public_key, payment_header). Agent cannot infer their roles or requirements.

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?

Describes listing all opened accounts with specific attributes (currency constraints, booking method). Distinguishes from sibling list_directives by noting 'no booking pass involved' and separate free call allowance.

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

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

Explicitly states 'first 2 calls per registered key are free' and contrasts with list_directives' and report tier's allowances, guiding when to use this tool vs alternatives.

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

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

The description discloses that the tool does not involve booking (no mutation), is paid (with free initial calls), and specifies ISO date format for since/until. Since no annotations exist, this adds value beyond the schema.

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

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

The description is two sentences, front-loading the main purpose and filtering, then adding essential behavioral details. Every sentence contributes meaning without redundancy.

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

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

Given 9 parameters and no output schema, the description covers the core filtering and cost aspects but omits details on authentication parameters, limit semantics, and the response format, leaving some ambiguity.

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

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

With 0% schema description coverage, the description explains the purpose of since, until, and account for filtering, and notes the date format. However, it does not explain the limit, payment_header, or authentication parameters (public_key, nonce, timestamp, signature).

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

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

The description clearly states the tool lists raw directives with optional filtering, and distinguishes itself from sibling tools like submit_directive by noting 'No booking involved' and being the 'cheapest paid tool'.

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

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

The description mentions it is the cheapest paid tool and that first two calls are free, implying cost-conscious use, and provides context about filtering options. However, it does not explicitly state when to prefer this over siblings like list_accounts or get_balance_sheet.

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

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

Discloses all critical behavioral traits: key generation, private key returned once, not stored server-side, unrecoverable, and independent from payment auth. Since no annotations are provided, the description fully carries the transparency 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?

Two sentences with no wasted words. First sentence states action and return. Second sentence covers critical behavioral details and domain separation. Perfectly concise and structured.

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

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

Despite no output schema, the description explains exactly what is returned (private key, once) and its properties. No parameters or complex behavior to document. Sibling tools are unrelated, so the description is complete for this standalone 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?

No parameters exist, and schema coverage is 100% (empty). The description doesn't need to add parameter info, and the baseline for 0 parameters is 4, which is appropriate.

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

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

Clearly states the tool generates a new Ed25519 keypair for ledger identity, distinguishing it from payment auth keypairs. The verb 'Generate' and specific resource 'Ed25519 keypair for ledger identity' make the purpose unambiguous.

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

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

Explains when to use (for ledger identity keypair) and provides important context about key recovery and domain separation. While it doesn't explicitly list when not to use, the sibling tools are clearly unrelated, so the guidance 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?

Despite no annotations, the description discloses key behaviors: atomicity (all or none), pricing (10x single write), mandatory payment, and cap of 1000 directives. It does not mention idempotency, error handling, or authentication needs, which are common for such tools, but it covers the most critical aspects.

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 and front-loaded, with the core purpose in the first sentence. It contains a redundant 'Paid.' at the end, but overall is efficient. Could be slightly tighter without the 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 no output schema, the description does not explain return values, error states, or how to verify success. It also lacks prerequisites like requiring a registered account or key setup. This is a significant gap for a complex batch operation.

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

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

Schema coverage is 0%, and the description does not explain any of the 6 parameters (nonce, signature, timestamp, public_key, directives, payment_header). It only mentions 'directives' implicitly. The description fails to compensate for the lack of schema documentation.

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

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

The description clearly states 'Submit up to 1000 directives atomically', specifying the verb 'submit', the resource 'directives', and the atomicity. It distinguishes from siblings like submit_directive (single) and validate_directive (validation).

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

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

The description provides explicit usage guidance: it mentions pricing relative to single writes, and clarifies that the free-trial allowance from submit_directive does not apply to batches. This helps decide when to use submit_batch vs submit_directive.

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?

Despite no annotations, the description fully discloses the payment model (free then paid), the need for authentication via public_key/nonce/timestamp/signature, and the two-phase submission process. It sets clear expectations about what happens under different conditions.

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

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

The description is a single dense paragraph that packs significant detail. While informative, it lacks structural elements like bullet points or sections, making it harder to parse quickly. Some redundancy exists (e.g., mentioning paid twice).

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

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

The description covers the main submission flow and payment handling. However, it does not describe the success response format, only mentioning 'succeeds immediately'. For a complex paid tool with no output schema, more detail on response structure would improve completeness.

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

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

Schema description coverage is 0%, so the description must compensate. It only explains payment_header usage but does not define the other five parameters (text, nonce, signature, timestamp, public_key) beyond their names. The 'text' parameter's purpose is implied but not specified.

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 explicitly states it submits one Beancount directive and lists all supported types (open, transaction, close, etc.). It clearly distinguishes from the sibling submit_batch by noting that submit_batch is always paid, while this tool has free writes.

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 a detailed workflow: call without payment_header first; if free writes remain it succeeds, otherwise it returns payment details for retry with payment_header. It also explains the free tier (first 20 accepted writes) and that each call needs a fresh nonce.

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

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

Discloses no persistence and signature requirement, but no annotations exist, so description should cover more behavioral aspects like error states or validation scope; it mentions 'full history' but does not elaborate on outcomes.

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 front-load the primary purpose ('free dry-run') and add key constraints efficiently.

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

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

Missing output schema and no parameter details, the description does not explain validation results, error handling, or what 'booking against history' entails, making it incomplete for complex usage.

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

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

With 0% schema coverage and 5 required parameters, the description provides no parameter explanations, leaving agents to infer meanings from names 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?

Clearly states tool as a free dry-run that parses and books text against history without persisting or charging, distinguishing it from submission 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?

Implicitly contrasts with submit_directive by mentioning 'dry-run' and 'without persisting or charging', but lacks explicit when-to-use or when-not-to-use guidance.

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