List customers

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

Annotations already cover readOnly/idempotent/non-destructive, so the description wisely spends its budget elsewhere: it discloses the projected-out fields, the required entity, and that returned data egresses to the client and its model provider. The free-text/untrusted-input warning is behavioral context an agent cannot get from any annotation or schema field.

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?

Front-loads the operation and scope in the first two sentences, then handles projection, prerequisites and the trust caveat in order. Dense but no filler; the security sentence is long but each clause carries a distinct warning.

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?

With an output schema present, the description correctly avoids explaining return shape and instead spends space on projection, prerequisites and data-handling risk. The main residual gap is the absence of any sibling routing given that list_accounts, list_vendors and run_query are adjacent for similar data.

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 coverage is 100%, so limit, active, entity and updated_since are already fully documented in structured form, and the description's "active=null" note merely restates the schema. It adds no syntax or format detail beyond what the schema provides, so the baseline 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?

States a specific verb and resource ("List a company's customers with their balances") and immediately bounds the payload via field projection ("no tax ids, notes or contact fields"). It never names a sibling, so an agent must infer the split from list_vendors/list_accounts/run_query on its own, which keeps it 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?

Gives one concrete invocation rule ("Pass active=null to include inactive") and a prerequisite ("requires an explicit 'entity'"), but never says when to choose this over run_query or list_accounts for customer-ish data, nor when it is the wrong tool.

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