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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, aligning with the description's '(leitura)'. The description adds valuable behavioral context beyond annotations by explaining pagination, filtering, nesting, and bulk execution. It does not repeat safety claims but clarifies operational semantics, which is sufficient given the annotations' coverage.

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 front-loaded with the primary purpose and resource list, followed by usage patterns. It is a single paragraph but logically organized (domain, then usage, then resources, then bulk note). Every section serves a purpose, and the length is justified by the tool's complexity (9 parameters, multiple resources).

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 no output schema and no parameter descriptions, this description provides substantial guidance: it covers listing vs. single record, pagination, filtering, nesting, and bulk operations. It does not clarify return field details or error handling, and misses the 'account' parameter, but given the domain-specific resource names, the data shape is largely inferable. Overall, it is complete enough for an agent to use effectively.

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?

With 0% schema description coverage, the description compensates for most parameters: resource, id, parent_id, offset, limit, query, and bulk ids/parent_ids. It explains pagination and filter format (JSON) but omits the 'account' parameter entirely, and does not specify which resources are nested or the exact structure of the query. This leaves a minor gap but is largely effective.

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 it is for reading maintenance/fleet data from Bsoft TMS, explicitly marked as '(leitura)' to separate it from the write sibling tools. It enumerates the specific resources available (abastecimentos, pneus, equipamentos, etc.), making the purpose unambiguous and distinct from other Bsoft read tools.

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?

Provides explicit usage instructions: how to retrieve a single record with `resource` + optional `id`, how to list with pagination via offset/limit, and how to filter with `query` JSON. It also explains nested resources require `parent_id` and mentions bulk support with `ids`/`parent_ids`. These guidelines are concrete and actionable for selecting and invoking the tool.

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