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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's main behavioral add is that it is for reading ('leitura') and explains pagination via offset/limit and query filters, plus bulk support with ids and parent_ids. This adds context on how pagination works and that bulk operations are supported, which is beyond the annotations. It does not describe return format or edge cases (e.g., errors, rate limits), but given strong annotations, this is adequate but not exceptional.

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 concise and front-loaded with the primary purpose, then a how-to sentence, then a list of resources, and a final bulk note. The structure is logical, and every sentence adds value—except perhaps the bulk support sentence could be more explicit about how to use it, but it is still informative. It is not verbose, and the resource list is useful. Slightly under-detailed on bulk mechanics, but overall efficient.

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 9 parameters, no output schema, and modest annotations, the description covers the main usage patterns (single get, list with pagination, nested resources, bulk) but misses the 'account' parameter entirely, which is a significant context signal given that it's a common parameter in this API family (bsoft_list_accounts suggests account contexts). It also doesn't explain the 'query' format beyond saying it's JSON, which could be ambiguous. Given the tool's moderate complexity, completeness is acceptable but not thorough.

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 role of resource, id (optional), query (JSON filters), offset/limit (pagination), parent_id (nested resources), and bulk ids/parent_ids. However, it does not explain the 'account' parameter, which is new and not self-explanatory. The description adds meaning for most parameters but leaves 'account' undefined. Given 9 parameters and 0% coverage, the description partially compensates but with a notable gap.

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 begins with 'Pessoas no Bsoft TMS (leitura)' and explicitly states the read-only nature, listing the types of registers (physical and legal persons) and the resource paths. It clearly distinguishes from write siblings by the '(leitura)' suffix and the readOnlyHint annotation, and it enumerates all supported resources, making it distinct from other bsoft_* 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?

The description provides clear usage instructions: pass resource with optional id to get a single record, or without id to list with pagination and filters using query JSON. It mentions nested resources require parent_id. However, it does not explicitly say when not to use this tool (e.g., for writes) or contrast with sibling tools, though the read-only context is implicit. The sibling list shows separate write tools, and the readOnlyHint annotation makes exclusion clear.

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