get_banks

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It does mention that the list is 'paginated' and includes '[GET /banks]', indicating a read-only HTTP GET operation. However, it does not discuss authentication requirements, rate limits, error handling, or what data fields are returned, leaving several behavioral aspects undisclosed.

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, with a front-loaded purpose ('List Banks') and additional detail in a single line. It suffers only from slight redundancy between 'List Banks' and 'Retrieve a paginated list of banks', but overall it is appropriately sized and well-organized.

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?

This is a simple list tool with only pagination parameters, which are fully documented in the schema. The description conveys the essential behavior: listing banks with pagination, and adds the contextual filter 'available for open banking payments'. Without an output schema, it does not describe return fields, but for a basic list operation the description is sufficient for an agent to select and 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 100%: both 'page' and 'page_size' have explicit descriptions in the input schema. The tool description adds only the term 'paginated', which does not enrich meaning beyond the schema. Therefore, the description adds minimal value beyond the structured fields, and the baseline of 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 'List Banks' and 'Retrieve a paginated list of banks', clearly specifying the verb (retrieve/list) and resource (banks) with a specific context ('available for open banking payments'). This distinguishes it from sibling tools like get_payins or get_accounts, which operate on different resources.

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 is provided on when to use this tool versus alternatives. The description explains what the tool does but does not mention any exclusions, prerequisites, or suggest sibling tools for different scenarios. The 'open banking payments' context is the only hint, but it is not developed into usage guidance.

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