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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: pagination via offset/limit, JSON filters in query, the requirement of parent_id for nested resources, and bulk support using ids/parent_ids. It stops short of describing output format or error semantics, but for a read tool this is adequate.

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: a concise overview sentence, practical usage instructions, and a resource enumeration. The resource list is somewhat redundant with the schema enum, but the overall length is justified by the large number of supported resources and the need to convey the read-only nature. No filler or fluff.

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 tool with 23 resources, 9 parameters, no output schema, and no per-resource details, the description covers the essential operational model: listing vs single fetch, pagination, filtering, nested parent requirements, and bulk execution. It does not explain each resource's meaning or return shape, but the resource names are largely self-explanatory and annotations cover safety. This is reasonably complete for a read-only data access 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 0%, so the description must compensate. It explains the core parameters (resource, id, offset/limit, query, parent_id, ids, parent_ids) and the single-vs-list behavior. However, the 'account' parameter is not mentioned at all, and 'query' is only lightly described as 'filters in JSON' without syntax details. The resource list duplicates the schema enum, adding little semantic value.

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 this is the financial read module of Bsoft TMS ('Financeiro no Bsoft TMS (leitura)') and enumerates the covered domains (títulos a pagar/receber, pagamentos, contas, contratos, etc.). It also differentiates from the write siblings by explicitly labeling itself as read-only.

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 explains when to use the tool (for reading financial records) and provides the core pattern: pass resource plus optional id for a single record, or no id to list. It implicitly distinguishes from the write variants via '(leitura)', though it does not explicitly name alternatives like 'use bsoft_financeiro_write_* for mutations'.

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