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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are 'combined' across three sources, which is useful, but it does not describe pagination behavior, result format, or how the combined entries are returned.

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 a single, tight sentence with no filler. The scope of the combined resource is stated clearly and immediately.

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 tool with 8 parameters, no output schema, and a combined result set from three different source types, the description is thin. The agent can infer the call shape from the schema, but it is not told what the combined result looks like, how pagination applies across the different entity types, or when to pick this over the individual list siblings.

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 description provides no parameter explanations. Schema description coverage is only 50%; the undocumented paging parameters (top, page, skip, pageSize) have understandable names and bounds, but the description does not compensate for the missing schema detail or clarify their behavior in combination.

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 uses a specific verb ('Lists') and names the exact combined resource: BRC sales entries, sales invoices, and sales credit notes. This clearly distinguishes it from sibling tools like brc_list_sales_entries or brc_list_sales_invoices.

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 word 'combined' implies the tool should be used when a merged view of these three document types is needed, and that individual list tools might be used for separate lists. However, there is no explicit statement of when to use this tool versus alternatives or when not to use it.

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