list_blocks

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

The description discloses a notable behavioral trait: enabling count_inserts triggers a full modelspace scan, which is a performance cost. However, since there are no annotations, the description carries the full burden of conveying safety and side effects; it does not explicitly state that the operation is read-only or non-destructive. It omits other behavioral details such as whether results are sorted or whether hidden/anonymous blocks are excluded by default.

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 two sentences long, front-loaded with the core purpose, and adds a relevant performance caveat. Every word earns its place; there is no redundant phrasing or filler.

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?

Although an output schema exists (so return values are covered), the description lacks important context: it does not mention prerequisites (e.g., an active drawing), how filtering works, or what 'anonymous' blocks are. The tool has 4 parameters with 0% schema descriptions, and only one is addressed. Overall, the description is too sparse for a tool that lists block definitions with multiple filtering options.

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 only explains count_inserts (the full-sweep cost and its purpose), while limit, filter, and include_anonymous are left completely undocumented. The mention of XREF and path hints at filter usage but is not tied explicitly to any parameter. This is insufficient for 4 parameters with no schema descriptions.

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 names the resource (block definitions) and specifies what is reported (XREF status, path, optional insertion counts). Although the verb 'list' is not explicitly repeated, the context makes clear this is a listing operation. It partially differentiates from siblings like inspect_block and list_source_blocks by focusing on definition-level metadata, but it does not explicitly compare with those alternatives.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The performance warning about count_inserts ('cuesta un barrido completo del modelspace') implies that this option should be used sparingly, but there is no mention of when to prefer list_blocks over sibling tools like inspect_block or list_source_blocks. The guidance is limited to one parameter's cost, not the tool's overall usage context.

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