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

The description says report generation is 'a read-like operation (aggregates existing data — no state mutation)', which aligns with and reinforces the readOnlyHint and idempotentHint annotations. It additionally discloses that large reports are not returned inline but as downloadable files opened via 'arquivo_ler', and that date intervals must be under 6 months. These are meaningful behavioral traits beyond the structured metadata.

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 well-structured with bullet points for each action, and the date and file-size caveats are valuable. The 'Flattened action: list' line is slightly cryptic but not redundant; overall no sentence is wasted.

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 the list action, return fields are specified. For generate, the required report parameter, date constraints, and large-report file handling are covered. Gaps remain: the account parameter is undocumented, the response format for non-large generated reports is unstated, and the reference to 'arquivo_ler' is not explained nor linked to an available sibling. Given no output schema, these omissions leave the tool incompletely described.

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 defines 'report' as the Arquivo field from list, and specifies that DATA_INICIO/DATA_FIM must be passed together in DD/MM/YYYY format with an interval under 6 months. However, the 'account' parameter is never mentioned or explained, leaving its purpose unclear. Since schema coverage is 0%, the description carries the full burden and misses one of four parameters.

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 opens with 'List and generate system reports in Feegow', a specific verb+resource combination. It enumerates two actions with clear outcomes (list returns id, Ct, Relatorio, Arquivo; generate produces a report). This distinguishes it within the sibling set by naming the exact resource and actions.

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 explains when to use generate (requires report from list, date interval under 6 months) and notes large reports are delivered as downloadable files. However, it does not explicitly differentiate this tool from the sibling feegow_report_generate, nor does it state when listing should be preferred over generating. The 'Flattened action: list' note hints at the primary use but is not elaborated.

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