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

No annotations are provided, so the description must carry the transparency burden. It does disclose that the operation retrieves/returns data, describes the output structure (full Stripe charge objects with customer IDs, metadata, processing details), and notes the requirement for a Stripe secret key. However, it does not explicitly state that it is read-only or describe error/rate-limit behavior, so some behavioral disclosure is implicit rather than fully explicit.

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 main purpose and each sentence earns its place. It covers the four query types, usage context, exclusions, and the authentication requirement. While longer than two sentences, the added length is justified by the tool's multi-mode complexity and the need to clearly warn against incorrect usage.

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 has only two parameters and no output schema or annotations, the description provides thorough contextual coverage: it explains all query modes, the shape of returned data, applicable use cases, constraints (bank transactions, generic bank history), and the server-side key requirement. An agent would have sufficient information 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?

The schema already covers both parameters (query_type and limit) with descriptions, and schema coverage is 100%, so the baseline is 3. The description adds value by elaborating what each query_type returns (e.g., 'recent_payments returns the latest payment intents with status, amount, and currency'), which goes beyond the schema's simple enum listing.

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 'retrieves live payment data from a Stripe account via the Stripe API' and explicitly lists four query types. It also distinguishes the tool from the sibling 'stripe_payment_records' by noting that this one returns full Stripe objects versus a lighter-weight array.

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 gives explicit when-to-use guidance: 'use stripe_payments when an agent needs to investigate payment failures, audit recent transaction activity, retrieve customer billing records, or check subscription status.' It also provides clear when-not-to-use guidance and names alternative tools: 'Do not use for bank account transactions or PSD2 Open Banking data — use open_banking_transactions instead' and 'Do not use for generic bank account history — use bank_accounts instead.'

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