report_revenue_summary

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

With no annotations provided, the description carries the full burden of behavioral transparency. It discloses that the tool pages through the full order list, returns a truncated flag for large shops, and aggregates by status while splitting paid/unpaid revenue. It does not explicitly state that it is read-only, but the 'generate a summary' phrasing implies no side effects. Overall, it provides adequate behavioral insight without exhaustive detail.

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 concise and well-structured. It starts with the primary purpose, then provides relevant details about filtering, aggregation, and pagination in a clear, logical order. No unnecessary words or redundancy are present, making it efficient for an agent to parse.

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?

The description gives sufficient context for an agent to use the tool correctly, including the specific date filter, aggregation criteria, and pagination behavior with the truncated flag. It does not describe the exact output schema, but that is acceptable given the absence of an output schema. The description could be slightly more explicit about the response structure, but it is complete enough for typical use.

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 schema descriptions cover all three parameters (startDate, endDate, locationId) at 100% coverage. The tool description adds no additional parameter semantics beyond what is already in the schema. For example, it does not explain that locationId defaults to an environment variable, but that is already in the schema. Therefore, the description provides no extra value for parameter understanding, warranting the baseline score of 3.

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's function: generating a revenue summary for orders invoiced within a date range. It specifies the key filter (invoicedDate) and distinguishes it from order creation date, making the purpose unambiguous. It also differentiates from sibling report tools by focusing on revenue aggregation.

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 implicit usage guidance by emphasizing the invoicedDate filter, which tells an agent when to use this tool instead of other order-related reports. It also mentions pagination and the truncated flag, which helps in handling large result sets. However, it does not explicitly compare to alternative report tools or state conditions for selection, so a minor gap remains.

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