Read a PcbLib

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

Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), the description reveals important behavioral details: fidelity carriers guarantee byte-identical rewrites when passed back, empty lists and optional fields are omitted rather than null, and the output shape matches get_component, export_library, and write_pcblib. These details are not present in the annotations and meaningfully set expectations for how the tool behaves.

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 dense but well-organized, covering purpose, output format, fidelity carriers, empty-field handling, and pagination advice in a logical sequence. Each sentence contributes specific value, and there is no redundant phrasing. The length is justified given the complexity of the output and the need to convey byte-identical rewrite guarantees and JSON shape consistency.

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?

With no output schema provided, the description compensates by detailing the footprint JSON shape, fidelity carriers, omission of empty values, and pagination. It explicitly references the shared JSON shape with get_component, export_library, and write_pcblib, which anchors the expected structure. This gives an agent sufficient information to understand what the tool returns and how to handle the data, making the description contextually complete.

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?

All five parameters are described in the schema with 100% coverage, including default values for limit, offset, and compact. The description reinforces the semantics of component_name and pagination ('For large libraries, use component_name to fetch specific footprints, or use limit/offset for pagination'). It also adds context that the output shape is consistent with other tools, which indirectly clarifies parameter expectations. No parameter is left ambiguous.

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 the tool reads an Altium .PcbLib file and returns its contents, including footprints with primitives. It is specific about the resource (PcbLib), action (read), and output (structured footprint data). It also distinguishes itself from write_pcblib by mentioning that passing fidelity carriers back enables byte-identical rewrites, clarifying its read-only role.

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 explicit guidance on when to use this tool, such as paginating large libraries with limit/offset or fetching a specific footprint by component_name. It also instructs on fidelity carriers ('pass them back unchanged to write_pcblib or update_component') and when to omit them ('when authoring from scratch'), which directly informs usage in different workflows. This guidance is actionable and goes beyond simple verb definition.

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