FINLY Balance Report Analysis

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

The description discloses many non-obvious behaviors: raw reports are not persisted, restarting the service ends recovery, external OCR sends data to Google Document AI outside Israel, local-only is the default, and terminal failures never restart the same operation. These add significant context beyond the annotations (readOnlyHint, openWorldHint, etc.), covering data handling, failure semantics, and external interactions.

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

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

The description is dense but not excessively long. It front-loads the main purpose and then details conditions. However, it packs many caveats into a single paragraph, which could be more scannable with bullets. Still, each sentence adds value and the overall length is appropriate for the tool's complexity.

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

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

Given the high complexity (6 parameters, nested objects, external OCR, security considerations, and an output schema), the description is thorough. It covers operational constraints, data privacy, recovery behavior, and legacy paths. The output schema handles return values, so the description focuses on critical usage details, making it complete for an agent to call this tool correctly.

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

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

The description adds meaning for operation and external_ocr, explaining their use cases and constraints. However, the required security_challenge and security_proof parameters lack any explanation, and the schema also has no descriptions for them. With schema coverage at 50%, the description partially compensates but leaves the security fields unexplained, which is a gap for correct invocation.

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

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

The description clearly states the action ('Analyze') and the resource ('PDF, JPEG or PNG balance report'), and specifies the output format ('structured facts and readable Hebrew text/HTML'). This distinguishes it from sibling tools like delete_report_analysis_result and get_report_analysis_result, which have different verbs and purposes.

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 detailed guidance on when to include the operation parameter (for recovery/replay) or omit it (legacy immediate-only), and when external OCR is allowed (with agent attestation or legacy approval). It does not explicitly contrast with sibling tools, but those are clearly different actions (delete, get), so the context for this tool is clear.

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

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

Annotations already cover destructive and idempotent hints, so the description adds value by noting irreversibility ('cannot be restarted') and the URL privacy guarantee. However, it does not disclose whether the operation record itself is deleted or only the result, leaving minor ambiguity.

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 fluff, purpose is front-loaded. Every word contributes to meaning, and the description is efficient.

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

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

With zero schema descriptions and no parameter explanations, the description is insufficient for an agent to correctly invoke the tool without external knowledge. It lacks guidance on obtaining the handle/token and the output format, though the output schema exists to cover return values.

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, but it only mentions 'exact capability' without explaining result_handle or result_token. An agent cannot infer parameter purposes from the description alone, especially since both are required in a nested object.

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 cancels the operation and deletes its encrypted result, which is a clear destructive action. It differentiates from siblings (analyze, get) through the verb 'delete', though it does not explicitly name alternatives. The title reinforces the purpose.

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

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

No explicit guidance on when to use this tool versus get_report_analysis_result or analyze_balance_report. The description only warns that deletion cannot be restarted, but does not state use cases, prerequisites, or exclusions. Usage is implied but not clarified.

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

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

Annotations are all false, so the description carries the burden. It discloses the proof-of-work requirement in detail (SHA-256 with zero first two bytes), critical behavior for correct invocation. It doesn't mention return format or per-use nature beyond single-use challenge, but the proof-of-work detail is significant and 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?

Three sentences, front-loaded with the purpose, and each sentence adds value: core deliverables, approval clarification, and the proof-of-work spec. Minimal waste, highly 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?

Given zero parameters and an output schema that likely describes the challenge structure, the description is largely complete. The proof-of-work algorithm is specified. It doesn't explain what to do with the notices beyond retrieval or how to use the response in subsequent calls, but that may be covered by the output schema and sibling tool context.

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

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

The tool has zero parameters)Skip, so there are no params to describe. Per instructions, with 0 params, baseline is 4. No additional semantic info needed; the description focuses on the output's nature, 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?

The description clearly states it retrieves processing notices, OCR supplier notices, and a proof-of-challenge work—specific resources with clear intent. It distinguishes itself from analysis and result tools by focusing on requirements, though it doesn't explicitly name 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?

It mentions that normal analysis requires no additional FINLY approval, providing a when-to-use condition. However, it doesn't explicitly say when to choose this over siblings or mention alternatives directly, leaving some inference needed.

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

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

Annotations already mark it as read-only and idempotent; the description adds the critical non-recoverable behavior after expiry or restart and clarifies it may return pending status. It also provides extra context by listing operations it does not perform, which goes beyond the annotations.

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

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

Three sentences with no waste: main action first, exclusions second, and the expiry caveat last. Every sentence earns its place.

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

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

Given the output schema and strong annotations, the description covers the core retrieval contract, including pending status and non-recoverability. It lacks explicit parameter semantics, but that is accounted for separately, and the remaining usage conditions are adequately specified.

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 should compensate, but it only says to pass the 'exact operation capability received before upload' without explaining what result_handle and result_token mean. The agent must infer their semantics from names and schema patterns, which is insufficient.

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 names the action (Retrieve) and object (analysis result or pending status), and the phrase 'using the exact operation capability received before upload' defines the scope precisely. The negative list differentiates it from sibling analysis/OCR tools rather than merely restating the title.

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?

Describes when to use it (after upload, with the operation capability) and what it does not do (upload, analyze, call OCR, renew expiry, prove identity), which routes an agent away from the sibling tools. It does not explicitly name the alternatives, so some inference remains.

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