read_block_attributes

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that the description discloses the returned attribute structure (TAG → value), wildcard matching behavior, and the pagination default — genuine context, though nothing about auth or result size limits.

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?

Front-loads the one-line purpose, then layers QUANDO USAR, parameter notes, and a concrete example. Every block earns its place and the example is compact; the formatting is slightly list-like but readable and non-redundant.

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?

Output schema exists, so return-value mechanics need not be restated, and annotations cover the safety profile. Given 0% schema description coverage on 4 optional params, the description supplies the missing parameter semantics, usage triggers, and an example — nothing an agent needs to call this correctly is absent.

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 carries the full burden, and it largely does: wildcards for block_name and layer, empty block_name = all blocks, and limit/offset pagination with 0 = server default. A worked example further anchors usage; only the offset semantics could be spelled out more precisely.

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?

States a specific verb and resource ('Lê referências de bloco') and enumerates what is returned (handle, posição, camada, dicionário TAG → valor). An agent can distinguish this from sibling mutators like update_block_attributes, though it never explicitly names a sibling reader such as dxf_read_attributes.

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 'QUANDO USAR' block gives concrete triggers: reading the drawing's support table, checking TAGs, or reading before updating values. No explicit when-not or named alternative, but the 'before updating' cue implicitly routes to update_block_attributes.

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