Import a library

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

Annotations already provide destructiveHint=true and readOnlyHint=false, and the description adds genuine behavioral detail beyond them: embedded_models are restored alongside footprints, bodies whose models are missing from the data are reported in warnings, and library type is auto-detected from the JSON. These are side-effect-relevant traits an agent cannot infer from the schema. No contradiction with annotations.

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?

Three sentences totaling roughly 70 words, with the core action front-loaded, round-trip semantics second, and auto-detection third. Every sentence carries information not present in the structured fields, and there is no filler or repetition of the title.

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?

The description covers the non-obvious aspects of importing: input format provenance, round-trip restoration of embedded_models, warning behavior, and type auto-detection. With no output schema, it omits what the tool returns on success, and overwrite-vs-append behavior lives only in the schema's append parameter rather than the description — both minor given destructiveHint is already annotated.

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 100%, so the schema already documents all three parameters and the baseline is 3. The description adds semantic depth for json_data beyond the schema's shape note: the data must be export_library-compatible, embedded_models are restored during import, and missing models trigger warnings. That elevates it above the baseline.

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 opening sentence names a specific verb and resource: 'Import components from JSON data into an Altium library file.' The auto-detection of PcbLib/SchLib and the reference to export_library's JSON format distinguish it from type-specific siblings like write_pcblib/write_schlib and from merge_libraries. An agent can tell exactly what this tool does without opening the schema.

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?

'Accepts JSON in the format produced by export_library, enabling round-trip workflows' gives a concrete condition for when to use this tool: immediately after an export_library call to restore a library. It stops short of a 5 because it never names alternatives or states when not to use it, but the round-trip framing provides clear context.

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