beel_list_accounts

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond that: it communicates the lifecycle status transitions (PROVISIONED → CLAIMED → ACTIVE), the inclusion of access_level and claim link state, and that results are 'Newest first'. This meaningfully enriches the agent's understanding of what the call does and how results are ordered.

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—two sentences plus an endpoint line—and front-loaded with the most important information (what it returns, lifecycle status). Every sentence adds value: the return fields, ordering, filtering options, and endpoint. No fluff or 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?

Even though there is no output schema, the description explains the key returned fields (status, access_level, claim link state) and the ordering. It does not explicitly mention pagination (cursor/limit) behavior in the description, but the schema covers those parameters. For a list operation, the description is largely complete, though a mention of pagination would make it flawless.

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 documentation covers 75% of parameters, with detailed descriptions for limit, cursor, status (enum with lifecycle explanation), and external_ref. The description repeats that status and external_ref can be used to narrow/filter, but adds no new meaning beyond the schema. Since coverage is high, the description does not need to compensate much, so baseline 3 is appropriate.

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 a specific action ('Returns the accounts you provisioned') and specifies exactly what is returned (lifecycle status, access level, claim link state). It is clearly distinct from list_* siblings like beel_list_customers or beel_list_invoices because it is explicitly about provisioned accounts, and from beel_get_account which is presumably a single-account fetch.

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 provides concrete filtering instructions: 'Narrow the list with `status`, or look one up by the `external_ref`'. It gives clear context for when to use parameters, but does not explicitly compare to alternative tools (e.g., 'use get_account for a single account'), so it's not fully explicit about alternatives. Still, the usage context is clear enough for parameter selection.

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