sales_report

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

With no annotations, the description carries the full burden and does so well: it discloses read-only behavior, passthrough semantics ('returned UNCHANGED'), fail-closed refusal of invalid product_type values, and profit being net pre-tax. The F-2 historical note is a genuinely useful behavioral nuance.

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 dense and front-loaded with the resource name and core behavioral guarantee before parameter details. Minor redundancy ('default here' and repeated 'empty = all') and the long single-paragraph structure keep it from a perfect score.

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?

Despite no output schema and no annotations, it explains the output shape ('columns, rows and report_summary cards'), view semantics, channel/product_type constraints, and read-only nature. Missing date-format details and explicit sibling-tool routing are the only substantive omissions.

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 0%, and the description compensates strongly for view, channel, and product_type by enumerating allowed values and defaults. However, from_date and to_date are required yet receive no format or range guidance, leaving a notable gap.

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 an exact resource ('The POS Sales Report') and states it returns revenue + profit across all channels, returned UNCHANGED. This clearly distinguishes it from siblings like financial_statement, tax_liability, and frappe_run_report without requiring the schema.

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?

It gives clear invocation context by explaining valid values for view, channel, and product_type, including defaults and fail-closed behavior. It does not explicitly name alternative tools or say when not to use it, but an agent can determine the appropriate call from the provided context.

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