MainBook Bank Statement Converter

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

The description goes beyond annotations by stating that the tool 'spends page credits' and is 'not read-only,' which is critical behavioral context not inferred solely from readOnlyHint=false. It also reveals the job-based polling nature of the operation, giving an honest preview of side effects and resource consumption.

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 incredibly concise: two sentences that front-load the primary action and workflow, then add a crucial caveat about page credits and read-only status. Every word adds value, with no repetition of structured schema fields.

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, job-based workflow, output schema), the description provides a high-level framework for understanding the full operation. It is complemented by the highly detailed schema and sibling tools, though it does not explicitly mention the return value behavior (e.g., JSON inline vs. file paths) beyond saying 'return structured data' – the schema covers that, but a direct pointer would have made it more complete.

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

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

The input schema already provides 100% coverage of all parameters, including detailed descriptions for file_url, file_path, output_path, result_type, idempotency_key, and timeout_seconds. The tool description itself adds no additional parameter-level semantics beyond what the schema already contains, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: converting one PDF bank statement via the complete workflow. It distinguishes itself from siblings by explicitly covering the full end-to-end process (create, upload, start, poll, return), whereas get_conversion, list_conversions, and output_folder are specialized for other steps.

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

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

The description provides clear context for when to use this tool: when you need to convert a PDF and obtain structured data from the full workflow. It does not explicitly name alternatives like 'use get_conversion if you already have a job_id,' but the phrase 'complete MainBook workflow' and the sibling tool names make the intended usage and boundary reasonably clear.

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

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

The annotation readOnlyHint=true already indicates a safe read operation. The description adds useful behavioral context by specifying that every value is measured in PDF pages, which is important for interpreting results. No side effects or auth requirements are mentioned, but these are sufficiently covered by the annotation.

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

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

The description is a single sentence of 11 words, front-loaded with the action and resource, and efficiently adds the unit of measure. There is no filler, redundancy, or unnecessary detail.

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

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

The tool is simple with no parameters, a readOnlyHint annotation, and an output schema. The description fully covers the essential information: what is returned and the unit of measurement. Additional return structure details would be provided by the output schema, which exists.

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

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

There are zero parameters, and schema coverage is 100% (vacuously). The description adds no parameter details, but per the rubric, the baseline for 0 params is 4, and there is nothing further to clarify.

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 the specific verb 'Return' and identifies the resource 'MainBook credits' with three specific types (total, reserved, available). Adding the unit 'PDF pages' provides additional clarity, making the tool's purpose unambiguous and distinct from sibling tools focused on conversions and output folders.

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

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

The description does not explicitly state when to use this tool versus alternatives. It simply states what it does, so the use case is implied (checking balance) but no exclusions or comparisons to sibling tools are provided.

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

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

Annotations provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, but the description adds meaningful behavior: when successful it returns JSON inline or saves files locally over stdio; HTTP mode returns safe download instructions. This goes beyond the annotations by explaining output transport modes and the timeout-follow-up behavior. However, it doesn't specify authentication/permission requirements or details on what 'safe download instructions' entails, so not a 5.

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

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

Three sentences, each earning its place: first states core purpose, second details output behavior and modes, third gives direct usage guidance. Front-loaded with action verb, no fluff, clearly structured for an agent to parse quickly.

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

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

For a tool with 3 params, an output schema, and a clear follow-up role, the description covers the essential behavior: purpose, output modes, when to use, and parameter context. The output schema handles return value structure, and sibling context clarifies tool selection. No major gaps; the timeout-follow-up scenario adds completeness beyond raw requirements.

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

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

Schema coverage is 100%: all three parameters (job_id, output_path, result_type) are documented with descriptions and default values. The description adds context that output_path is only available over stdio and inside allowed folders, which enriches schema. Baseline 3 is appropriate because schema already covers parameter meanings; description adds marginal value for output_path but minimal for others.

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

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

The description clearly states the verb 'Get' and the resource 'current state of one MainBook conversion,' distinguishing it from siblings like list_conversions (which lists all conversions) and convert_bank_statement (which initiates a conversion). It also specifies response handling (inline JSON, XLSX/CSV local save, HTTP download instructions) and the intended post-step workflow.

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 says 'Use this after convert_bank_statement times out,' providing a concrete when-to-use scenario. It also differentiates from alternatives by describing different output modes (stdio vs HTTP), which helps an agent choose this tool over sibling tools like list_conversions or get_balance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds important behavioral context: it returns only one cursor page at a time and requires the caller to continue pagination with the next_cursor. It does not contradict annotations.

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

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

Two succinct sentences with no filler. The first sentence states the action and scope, and the second provides the key follow-up instruction for pagination.

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

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

The tool is a simple paginated list with a clear output schema and good annotations. The description covers the essential behavior (one page, cursor continuation, account visibility) and does not need to explain return values because the output schema is present.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by linking the cursor parameter to the pagination workflow ('Pass the returned next_cursor to continue'), clarifying how the parameters interact beyond the schema's individual descriptions.

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

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

The description clearly states the tool lists conversion jobs visible to the MainBook account, using specific verb 'List' and resource 'conversion jobs'. It distinguishes from siblings like get_conversion by indicating this returns a page of multiple jobs rather than a single 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 explains the pagination flow: list one cursor page and pass the returned next_cursor to continue. It does not explicitly name alternatives or exclusions, but the context is clear and actionable.

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

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

The description clearly discloses the read vs. change behaviors, the special 'next_to_source' reset value, and the 'allowed' folder constraint. This adds context beyond the annotations, which only indicate non-read-only, idempotent, and non-destructive.

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 core purpose and then provide specific usage instructions. No redundant information or fluff.

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

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

For a simple tool with one optional parameter and an output schema, the description covers all key behaviors: reading, changing, resetting, and the allowed-folder restriction. No critical gaps detected.

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

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

The schema already documents the 'path' parameter with 100% coverage, including its default and description. The description adds minor nuance about the no-path read behavior and the 'allowed' qualifier, but doesn't significantly extend schema semantics.

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

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

The description states a specific verb ('Read or change') and resource ('default local result folder'), clearly distinguishing it from sibling tools focused on conversions and balances.

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?

Explicit usage instructions are given for both modes: calling with no path to inspect, and passing an allowed folder or 'next_to_source' to change. It doesn't mention alternatives, but none are needed among siblings.

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