list_payments

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

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context by detailing the shape of the returned data (per-file payment fields and per-currency totals) and equating the tool to the portal's Payments tab. It does not disclose pagination or output limits, but for a read-only list tool this is a minor gap given the annotation coverage.

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 sentences with no filler. The first sentence front-loads the resource and packs in the key return fields and totals; the second gives a precise alternative for the pay action. Every clause earns its place, making the description both compact and information-dense.

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 list operation with two params, a read-only annotation, and no required output schema, this description fully covers what an agent needs: what it returns, the workspace scope, and a pointer to the sibling for payment. Missing details like pagination are not critical for this tool's simplicity.

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 covers 100% of parameters, with descriptions for both origin and workspace_id. The tool description reinforces the workspace scope but adds no new parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate because the schema handles parameter documentation.

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 names a specific verb and resource: it lists the payment schedule for a workspace, matching the portal's Payments tab. It enumerates the exact return content (amount, due date, paid/pending state, payment method, invoice number, totals per currency), which distinguishes it clearly from sibling tools. The closing pointer to pay_invoice further differentiates the list operation from the payment action.

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 clear context for when to use the tool: when viewing the payment schedule for a workspace. It explicitly routes the payment action to pay_invoice, which is a helpful exclusion. However, it does not mention alternatives like list_payment_methods or clarify when one would prefer those, leaving some sibling differentiation implicit.

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