read_account_history

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. Beyond that, the description discloses genuinely useful traits: provider created dates are not timezone-converted, a page limit or missing history is never treated as complete, and incomplete errors are surfaced alongside the data. What it lacks is any mention of auth/permission needs or pagination mechanics for continuing past the limit.

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 short and front-loads the core purpose and date-range contract. "Returns every selected payment, exact cursor coverage and incomplete errors" is densely packed and slightly awkward to parse, but there is no filler.

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?

There is no output schema, so the description must characterize return values, and it does so loosely (selected payments, cursor coverage, incomplete errors) without explaining shape. Combined with zero schema coverage on account_id and an unstated relationship to sibling financial tools, it is adequate but leaves real 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 description coverage is 0%, so the description must carry the parameter burden. It clarifies the date range as a half-open ISO interval [start,end) and implies that page_limit caps results without guaranteeing completeness, which is valuable. However, account_id is never explained at all, leaving one of three required parameters undocumented.

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 opens with a specific verb and resource: "Read all exposed Payment pages for one account." It adds a scope boundary ("Does not read other banks or cards") that helps separate it from broader financial tools. The phrase "exposed Payment pages" is somewhat jargon-y, and no sibling such as review_financial_records is named, so it falls short of a 5.

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?

Usage is only implied: the tool reads payment history for a single account over a date range, and the description rules out other banks or cards. There is no explicit when-to-use statement and no comparison to alternatives like review_financial_records, which an agent would likely consider for similar data.

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