bankstatementparser-mcp

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the bar is lower. The description adds that it resolves format from content and filename, and raises ValueError if undetected, which is useful context beyond 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?

Concise with clear sections (Args, Returns, Raises). Every sentence earns its place; no 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 the tool complexity and 100% schema coverage with output schema, the description fully covers what the tool does, its inputs, output, and error conditions. No gaps.

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%, baseline 3. The description adds meaning by noting content is inline (not file path) and filename's extension is primary hint, along with defaults and recognized extensions. This goes beyond the schema.

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

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

The description clearly states it detects which bank statement format an inline payload is, using specific verb 'detect' and resource 'format'. It distinguishes from siblings by referencing parse_statement for subsequent actions.

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 when to use (when you hold statement text but do not yet know its format) and what to do next (call parse_statement instead of calling again). Provides clear context and 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying the return value (format identifiers) and directing to a resource for human-readable details.

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?

Concise three-sentence description. Front-loaded with the main action, each sentence serves a purpose: states function, gives usage guidance, and describes return 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?

Given no parameters and an output schema exists, the description is complete. It explains what the tool returns, how it fits with sibling tools, and where to find additional info.

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 in schema, so description doesn't need to explain them. It adds context about what the tool returns, meeting the baseline for zero 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?

Description clearly states 'List every bank statement format identifier this server can parse.' Uses specific verb and resource, and distinguishes from siblings by mentioning it's a precursor to detect_format and parse_statement.

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 'Use this first to discover the valid format strings before calling detect_format or parse_statement.' Also references an alternative resource for more detailed information.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds genuinely useful context beyond them: format resolution precedence (filename extension vs explicit format override), truncation semantics (transactions possibly truncated while transaction_count stays full), and the ValueError raised for unsupported or undetectable formats. The Returns section also documents the exact response shape. No contradiction with annotations.

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

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

The description is front-loaded with a one-line purpose, followed by compact usage guidance and terse Args/Returns/Raises sections. Every section earns its place; the Returns and Raises blocks carry real behavioral information rather than padding or repeating the schema.

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

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

Given 4 parameters, a 6-value format enum, and 4 sibling tools, nothing an agent needs to invoke this correctly is missing: required content semantics, format inference and override, limit behavior, return structure, error behavior, and alternative tools are all covered. The output schema covers return values, and the description reinforces them regardless.

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

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

Schema coverage is 100% and the schema descriptions are already rich (format enum values, accepted payload types, extension list), so the baseline is 3. The description nudges above baseline by adding the behavioral consequence of `limit` in the Returns section (transactions may be truncated but transaction_count is the full count) and by tying format failures to the Raises clause.

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 line 'Parse an inline statement payload into transaction rows and a summary' names a specific verb, resource, and delivered artifacts. It also differentiates from siblings by clarifying that this tool provides full transaction detail plus balances, while summarize_statement and validate_statement cover the reduced-scope cases.

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 when to use this tool ('Use this to read the full transaction detail plus the statement balances') and gives concrete switch criteria: use summarize_statement when only balances/totals are needed, and validate_statement to merely confirm a payload parses. Alternatives are named, so an agent needs no 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?

Annotations already declare readOnlyHint, idemponentHint, and destructiveHint=false; the description adds meaningful behavioral details beyond annotations, including that Decimal values are stringified in the result, that ValueError is raised for unsupported/undetectable formats, and that the input must be inline text rather than a file path. No contradiction with annotations.

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

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

The description is front-loaded with the primary purpose and usage guidance, and the Args/Returns/Raises sections are compact. It earns a igh score, though the Args section slightly duplicates richer schema descriptions, keeping it from a perfect 5.

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 a full input schema, output schema, strong annotations, and explicit sibling routing, the description covers what the tool does, when to use it, what it returns, and what can go wrong. Nothing essential is missing for an agent 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?

Schema description coverage is 100%, and each parameter already has a thorough description, including the format enum and filename extension behavior. The Args section in the description is a concise restatement but does not add significant meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb plus resource: 'summarize an inline statement's balances and totals only.' It clearly distinguishes this tool from parse_statement by noting that it omits per-transaction rows, so an agent can select correctly even before reading schemas.

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 explicit when-to-use guidance ('when you need just the opening/closing balances, currency, and other summary fields') and explicitly names the alternative ('use parse_statement instead') for full transaction detail. It also clarifies format detection behavior and the role of filename vs format.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds valuable behavioral context beyond those flags: it never raises on parse error, returns a structured pass/fail, includes transaction count on success, and never returns row data. This meaningfully informs agent expectations around failure handling and output scope.

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 well-structured with a clear purpose statement, usage guidance, Args, and Returns sections. Every sentence earns its place, and the most important behavioral constraints (no rows, no raise) are front-loaded before the alternative tool mention.

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 validation tool with rich annotations, a fully described schema, an output schema, and explicit sibling guidance, the description is complete. An agent knows what it validates, when to call it, what it returns, how it behaves on failure, and which sibling to use when actual data is needed.

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

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

Schema description coverage is 100%, so the schema fully documents content, filename, and format. The description's Args section largely restates this existing information without adding new semantic depth beyond what the schema already provides. This is the appropriate baseline for a fully self-documenting schema.

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

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

The description uses a specific verb-resource pair ('Dry-run parse an inline statement') and immediately clarifies what it does and does not return (pass/fail with transaction count, never rows). It also distinguishes itself from parse_statement by naming it explicitly, so an agent can separate the two tools without opening their schemas.

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 states exactly when to use this tool: to confirm a payload is well-formed before committing to a full read. It also names the alternative action ('To actually read the transactions use parse_statement'), which provides an explicit selection rule between siblings.

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