reports_sales_analysis

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

No annotations are provided, so the description carries full burden. It reveals the report nature (read-only analysis) and the X-Company header requirement, which is helpful. But it doesn't disclose whether the tool mutates any state, performance/size limits (e.g., large date range behavior), auth scopes needed, or what happens with invalid company context.

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 concise paragraph that front-loads the core purpose before enumerating outputs. Every sentence earns its place — the report contents list and the company header note both add value. Slightly dense but 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?

For a read-only reporting tool with 100% schema coverage and no output schema, the description reasonably covers inputs and expected outputs. However, without annotations and with no guidance on date-range limits, large result handling, or subtleties of the KPI calculations, it leaves room for ambiguity in edge cases. Adequate for a straightforward report tool.

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 all three parameters (dateFrom, dateTo, companyId) are documented in the schema. The description adds context by explaining that companyId overrides the STORNO_COMPANY_ID env var, which is a meaningful relationship detail beyond the schema. The date format guidance lives in the schema, so the description compensates adequately though not richly.

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 specifies a clear verb-resource combination ('Generate a sales analysis report') with an explicit date range scope and enumerates the returned content (KPI summary, monthly trends, invoices, top clients, products). This clearly distinguishes it from other reporting tools like reports_vat and generic list endpoints.

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 states it requires the X-Company header (companyId or env var), which is useful setup context. However, it gives no guidance on when to use this tool versus alternatives like reports_vat, invoices_list, or balance_list, and provides no exclusion criteria or prerequisite conditions.

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