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

The description adds behavioral context beyond the annotations: it states that 'Report generation is a read-like operation (aggregates existing data — no state mutation)', which aligns with the readOnlyHint and idempotentHint annotations. It also discloses output behavior: 'Large reports come back as a downloadable file (open sections with arquivo_ler), not inline.' This is valuable additional information that the annotations do not provide.

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 structured with bullet points and a clear action list. Each sentence provides distinct information: report selection, date constraints, file output behavior, and read-only reassurance. It is slightly longer than necessary because it includes 'list' details despite the tool being flattened to 'generate', but the content is not wasteful.

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?

Given no output schema, the description covers the essential operational aspects: how to choose the report, date limits, file download behavior, and the safe/read-only nature. It falls short on the 'account' parameter and does not describe potential error cases or the exact format of the returned data, but for a generate action it is fairly complete and actionable.

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 has 0% description coverage, so the description must compensate. It explains 'report' (the Arquivo field from list) and DATA_INICIO/DATA_FIM (optional, passed together, DD/MM/YYYY, under 6 months). However, the 'account' parameter is not mentioned at all, leaving a gap. Also, the description says 'Requires report' while the schema lists no required fields, creating a minor inconsistency. Overall, it partially compensates but misses one parameter.

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 primary purpose: 'generate a report' in Feegow, with the specific action 'generate' highlighted via '[Flattened action: generate]'. It also explains how to identify the report using the 'Arquivo' field, which distinguishes this from the sibling feegow_report_list. However, the opening phrase 'List and generate system reports' is slightly ambiguous because the tool is specifically for generation, lowering the score.

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 gives concrete usage guidance: 'Requires report (the Arquivo field from list)' explicitly tells the agent to first list reports to get the necessary identifier. It also states a critical constraint: 'DATA_INICIO/DATA_FIM ... passed together; the interval must be UNDER 6 months.' It does not explicitly mention using feegow_report_list as an alternative for listing, but the referral to 'from list' implies that. This is clear context, though not a full when/when-not comparison.

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