document_series_list

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

No annotations are provided, so the description carries the full burden. It correctly implies this is a read-only listing operation ('List all document series'), which sets expectations of a safe, non-mutating call. However, it doesn't describe return structure, pagination, ordering, or whether the type filter is mutually exclusive or combinable with company filtering. The description is accurate but not deeply transparent about behavioral details.

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 two sentences plus an illustrative parenthetical. It's efficient and front-loaded with the core purpose ('List all document series for the active company'), then adds contextual color about what series represent. The extra sentence about numbering prefixes and tracked numbers earns its place by helping the agent understand the domain. No wasted words.

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?

No output schema exists, but this is a list endpoint with 0 required parameters and simple optional filtering, so complexity is low. The description adequately covers what the tool does, the filter dimension, company scoping, and domain context. An output schema would help clarify return structure, but for a straightforward list tool this is reasonably complete.

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 100%, so the schema already documents both parameters well (type enum with explanation, companyId with UUID override note). The description adds some value by explaining the type values map to document types (invoice='FAC', proforma='PRO', etc.), which goes slightly beyond the schema. The companyId override is mentioned in both schema and description. Baseline 3 is appropriate given high schema coverage.

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 lists document series for the active company with optional type filtering. It adds contextual detail explaining what document series are (numbering prefixes for invoices, proformas, credit notes, delivery notes) and what data each series tracks (current/next available number). It distinguishes itself from sibling tools like document_series_create/update/delete through the list verb, though it doesn't explicitly contrast with a 'get' variant since none exists.

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 clearly explains when to use it (listing series, optionally filtered by type) and mentions the companyId override for selecting a company. However, it doesn't provide explicit guidance on when NOT to use it or contrast with alternatives like document_series_create/update/set_default/delete. The context is implied rather than spelled out regarding interplay with series management tools.

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