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

Annotations already say destructiveHint=true, but the description adds meaningful details about the actual mutations (changetrack width, move layers, set parameters) and how to avoid them (dry_run). This extends beyond the bare annotation and helps the agent naturally understand the file modification behavior.

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, clearly front-loaded with the main purpose, followed by operation-to-file-type mapping and a dry_run tip. No fluff. Slightly below the ideal 5 because of the long list of operation examples embedded in a single sentence, but still compact.

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 is adequate for parameter coverage and the destructive nature is inferrable, but it does not discuss what the operation returns (e.g., a summary or count of changes) and does not state prerequisites for PcbLib vs SchLib files beyond specifying which operations apply. For a destructive update tool this leaves some possible gaps for an agent.

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?

The schema already describes all parameters with 100% description coverage, so the description adds little new parameter-specific information beyond some examples (e.g., layer names). That matches the baseline of 3 for already-complete schema coverage.

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 states a specific intent ('Perform one batch operation across all components in an Altium library file') and enumerates the three distinct operations per file type. It clearly differentiates this from sibling tools like update_component and bulk_rename because it is explicitly batch-oriented.

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?

It provides clear context: batch operations across all components, with examples and a concrete dry_run usage to preview changes. It does not explicitly list exclusions or name alternative tools for single-component updates, so it stops slightly short of full when/when-not guidance.

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

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

The annotations already communicate that this is destructive (destructiveHint=true), so the description does not need to restate that. It adds some context about regex/capture groups but does not detail side effects, safety preview via dry_run, or what happens to the file.

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 a single focused sentence with one illustrative example. It is front-loaded with the core action and avoids redundant restatement of the title or annotations.

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?

Given full parameter coverage and a destructiveHint annotation, the essential calling context is present. It could mention the optional dry_run affordance or return behavior, but the schema already covers dry_run and no output schema is provided.

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 parameters are already described in the input schema, so the description has less burden here. It reinforces the regex replacement syntax with a concrete example but does not add semantic meaning beyond the schema.

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 uses a specific verb ('Rename') and resource ('multiple components in a library') with a clear mechanism ('regex pattern matching'). The capture-group example distinguishes it from single-component rename operations and communicates a distinct scope.

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?

It clearly frames the tool for bulk/pattern-based renaming and shows an example transformation, which implies when it applies. It does not explicitly name alternatives such as rename_component or state when not to use it, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only'. It adds valuable behavioral context: identity (GUIDs, unique ids) is never a difference, geometry compares within tolerance, unmatched items are reported per side, and include_geometry=false changes the comparison to counts/properties only. It also discloses the return summary fields (identical, difference_count, differences, per-kind count summaries).

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: it front-loads the core comparison scope, then details geometry behavior, then gives usage routing. It is longer than the minimum but every sentence adds information; the only minor inefficiency is the long enumeration of primitive kinds, which could be summarized, but it is valuable for an agent.

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 read-only comparison tool with no output schema, the description covers the input constraints, the comparison semantics, the effect of the optional flag, and the return summary fields. It does not describe the exact structure of the differences output, but it names the key fields and the per-kind summaries, which is sufficient for an agent to invoke it correctly.

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 six parameters. The description adds context for tolerance (mm, default 0.001) and include_geometry behavior, but does not add meaning beyond what the schema provides for filepath_a, filepath_b, component_a, and component_b. Baseline 3 is appropriate.

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 states a specific verb ('Compare'), a clear resource ('two named components'), and enumerates exactly what is compared (description, parameters, per-primitive-kind details). It also distinguishes itself from siblings by naming diff_libraries and get_component as alternatives, so an agent can select it correctly.

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?

Explicitly says when to use this tool: after diff_libraries to drill into a specific pair, and when to use get_component instead for a single component's full data. It also states the type-matching constraint (.PcbLib with .PcbLib, .SchLib with .SchLib), which is essential for correct invocation.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds that it 'checks existence' but provides no additional behavioral details beyond what the annotations convey. It does not contradict the annotations, so this is not a red flag, but the description itself contributes little extra transparency.

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, using only two sentences to convey the purpose and a usage suggestion. It wastes no words and is well-structured, with the core function stated first and the usage context second.

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?

Given the rich set of sibling tools, the description effectively differentiates this tool as a lightweight existence check. However, it does not mention what the tool returns (e.g., a list of existing vs. missing components or a simple boolean), which could be relevant for an agent deciding whether to call this tool. It also omits potential error conditions like invalid file paths, but these are not critical for correct invocation.

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?

Both parameters (filepath and component_names) have clear descriptions that explain their purpose and format. The schema coverage is 100%, and the descriptions are sufficient for an agent to understand what values to provide. No additional parameter-level details are missing.

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's function: checking if one or more components exist in an Altium library. It uses specific language ('Check if', 'exists') and identifies the resource type (Altium library), which distinguishes it from sibling tools like list_components or get_component that have different purposes.

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 explicitly suggests using this tool to validate component names before operations like rename, copy, or delete, providing clear guidance on when to use it. It does not, however, mention alternatives or specify when not to use it, which would make the guidance more complete.

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

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

Annotations already indicate destructiveHint=true, and the description adds useful behavioral detail about creating a new component with fresh GUIDs. It does not mention what happens if the target name already exists, but the annotation covers the destructive nature.

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 compact and direct, using three sentences with no redundant or filler content. It efficiently conveys the action, the result, and the primary use case.

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?

Given the absence of an output schema, the description adequately explains the operation's result and purpose. It covers the core behavior, and the dry_run parameter semantics are already described in the schema.

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 coverage is 100%, with all five parameters described clearly. The description itself adds no additional parameter-level detail, so the baseline score of 3 is appropriate given the complete schema.

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 copies/duplicates a component within an Altium library file, using specific verbs and a clear resource. It distinguishes the operation from cross-library copies and renames by emphasizing 'within an Altium library file' and fresh GUIDs.

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 mentions the tool is useful for creating variants, providing some usage context. It does not explicitly distinguish when to use this tool over the similar copy_component_cross_library or rename_component, though the 'within an Altium library file' phrasing gives an implicit boundary.

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

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

The annotations already mark destructiveHint=true, but the description adds valuable behavioral details: embedded 3D models are copied along, external STEP references are dropped unless preserve_external_paths is true, and it explains why (path may not resolve). This goes beyond the annotations without contradicting them.

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 moderately long but well-organized: purpose, constraints, behavioral details, and use case are each addressed. No redundant fluff, and the key distinctions are front-loaded.

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?

Given the tool has 7 parameters and no output schema, the description provides enough context to understand the tool's scope, constraints, and side effects. It does not cover error scenarios or edge cases, but that is not necessarily required for successful invocation.

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 coverage is 100%, so all parameters already have descriptions. The description repeats some of this (e.g., external path removal) but does not add substantial new meaning beyond what the schema provides, hence a baseline score of 3 is appropriate.

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?

Clearly states the action (copy a component) and the resource (from one Altium library to another). It also distinguishes from the sibling tool copy_component by specifying cross-library vs. within-library duplication, and mentions the use case of consolidating libraries or sharing projects.

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?

Explicitly names the alternative tool (copy_component) for duplicating within a library, and provides constraints (same type, different files). It also gives context on when to use this tool, making the selection among siblings unambiguous.

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

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

Beyond the destructiveHint annotation, the description explicitly states the delete action, explains the dry_run behavior to avoid actual modification, and details the return statuses ('deleted', 'not_found', 'error'), providing full transparency.

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, using two sentences to cover the core action and the dry_run/return behavior. It is well-structured and free of redundant information.

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 is complete for a deletion tool: it specifies input parameters, the preview option, and the output statuses. Even without an output schema, the return behavior is clearly described, and the destructive nature is highlighted.

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 coverage is 100% with clear parameter descriptions, and the description adds extra semantic value by explaining the dry_run behavior and the return status per component, which goes beyond the schema fields.

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 action ('Delete one or more components') and the target resource ('Altium library file'), with specific file types. It distinguishes this from other component operations like update or rename by the verb 'delete'.

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 implies usage when deletion is needed and mentions dry_run for previewing, but it does not explicitly compare against sibling tools like 'update_component' or 'copy_component' to clarify when deletion is the appropriate operation.

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

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

Annotations already declare the operation read-only and non-destructive. The description adds useful non-obvious context by specifying the output categories (added, removed, modified) and the file-type restriction, which helps the agent predict the tool's behavior.

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?

Two tight sentences: purpose first, then output detail and constraint. Every sentence adds information without redundancy 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?

For a simple read-only comparison with two well-documented parameters, the description covers the core invocation requirements and output categories. It does not detail the exact diff report format or what counts as 'modified', but no output schema exists and the core behavior is clear.

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 already documents filepath_a as base/old and filepath_b as new/changed, and the description adds the cross-parameter constraint that both files must share the same extension type. This is meaningful semantic value beyond the schema.

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 the action (compare), the exact resource (two Altium library files), and the high-level result (report added/removed/modified components). The 'library files' phrasing distinguishes it from the sibling compare_components, which targets individual components.

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?

Provides a clear prerequisite: both inputs must be the same type (.PcbLib or .SchLib). It does not explicitly say when to prefer this over sibling tools like compare_components, so it stops short of full alternative guidance.

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

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

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds meaningful behavioral context: nothing is written to disk, output is returned as text, JSON includes embedded 3D models as base64 STEP data keyed by model GUID, and CSV is a summary table. This gives the agent a clear model of side effects and output behavior far beyond the annotation flags.

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 long but information-dense, and the key behavior ('nothing is written to disk') is front-loaded. The JSON/CSV breakdown and usage guidance are essential given the tool has no output schema and serves two distinct formats. It could be slightly better structured into shorter sentences, but every clause earns its place.

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, the description must explain what the tool returns, and it does so thoroughly: JSON component shape, embedded 3D model handling, CSV column layout, and appropriate use cases. The three parameters are all covered by the schema, and the behavioral and usage context provided is sufficient for an agent to call this tool correctly without further inference.

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 baseline is 3, but the description adds value by elaborating what each format produces: JSON carries full component data in a shape compatible with read/write tools, while CSV provides a summary with specific columns. This deepens the meaning of the 'format' parameter beyond the schema's brief 'full data' vs 'summary table' phrasing.

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 opens with a specific action and resource: 'Export a .PcbLib or .SchLib as text in the response'. It clearly distinguishes the tool from read_pcblib/read_schlib by noting this is a full export rather than paginated inspection, and it also contrasts the JSON and CSV output roles. The purpose is unmistakable and well differentiated from the sibling 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?

Usage guidance is explicit: use JSON for version-control, backup, or moving a library; use CSV for inventory; use read_pcblib/read_schlib instead for paginated component inspection; and use list_components for a quick overview. The description names concrete alternatives and the conditions that select each one, leaving no ambiguity about when to invoke this tool.

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

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

With readOnlyHint and destructiveHint annotations already present, the description adds useful behavioral context: models are stored compressed and are extracted to standalone files. It discloses the side effect of writing .step files and lists mode behaviors without contradicting the 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?

The description is three concise sentences with no wasted words. It front-loads the primary purpose, adds a relevant storage detail, and summarizes modes, making it easy to scan.

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 schema covers all parameters thoroughly, including the important inline base64 behavior for omitted output_path, and annotations cover the safety profile. The description provides a clear high-level overview of purpose and modes, so the agent has enough context to invoke the tool correctly.

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 fully documents all seven parameters with rich details, including mode-dependent output_path semantics. The tool description itself mostly restates the mode enum, adding little semantic value beyond the schema.

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 states a specific verb ('extract'), resource ('embedded STEP 3D models from an Altium .PcbLib file'), and output format ('.step files'), making the tool's function unambiguous. It also distinguishes from sibling tools like extract_style by naming the exact content type (STEP 3D models).

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 explains the supported modes and the default, which provides some within-tool usage guidance. However, it does not explicitly state when to use this tool versus related siblings (e.g., read_pcblib, extract_style) or include exclusions, so usage context is more implied than explicit.

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

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

The description goes well beyond the readOnlyHint annotation by disclosing what the tool actually reports: track/arc widths, pad shapes, text heights, layer usage, pin lengths, and stroke/fill/text colours. It also clarifies edge semantics such as 'a via counts as Multi-Layer,' which gives the agent useful behavioral expectations beyond the structured 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?

The description is appropriately sized and front-loaded with the core purpose. Each sentence earns its place: the first states the action, the second details the type-specific output, and the third gives the intended use. There is no filler or redundancy.

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 simple one-parameter, read-only tool with no output schema, the description is complete. It explains what the output will contain for both supported library types, states the use case, and the annotations cover the non-destructive safety profile. Nothing essential is missing for an agent to call it correctly.

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?

The input schema already fully documents the single parameter (`filepath`), so the baseline is 3. The description adds indirect meaning by tying the filepath to either .PcbLib or .SchLib behavior, but it does not materially expand on the parameter itself beyond what the schema states.

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 states a specific verb-resource pair: 'Extract style information from an existing Altium library file.' It then enumerates exactly what style information is extracted for PcbLib and SchLib files, which distinguishes it from the more generic read_pcblib/read_schlib siblings and makes the tool's purpose unmistakable.

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 gives a clear use context: 'Use this to learn from existing libraries and create consistent new components.' It does not explicitly name alternatives or state when not to use the tool, but the purpose and intended workflow are clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral detail: it returns complete component data, works for both footprint and symbol libraries, and avoids full-library filtering. This goes beyond the structured hints without contradicting them.

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 with no filler. The core purpose is front-loaded, the return behavior is stated, and the file-type support is included efficiently. Every sentence contributes useful information.

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 simple 2-parameter read-only tool, the description is sufficiently complete: it defines the target, the input context, and the output scope. The lack of an output schema is partially mitigated by saying it returns 'full component data', though exact return structure and error behavior are not detailed.

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 filepath and component_name are already well documented in the schema. The description does not add much parameter-specific meaning beyond what the schema provides, but it reinforces the exact-name expectation and the supported library file types.

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 uses a specific verb ('Get') and resource ('single component by name'), clearly distinguishing this from broader library-reading tools. It also states what is returned ('full component data') and the supported file types, so an agent knows exactly what the tool does.

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 conveys a clear usage context: retrieve one known component by name without reading and filtering the entire library. It does not explicitly name sibling alternatives like list_components or read_pcblib/read_schlib, but the 'without needing to read and filter the entire library' phrasing effectively signals when this tool is preferable.

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

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.

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description adds extra behavioral context: backup files are timestamped, .bak files, and are automatically created before write operations. This gives the agent a clearer understanding of what these backup files represent, going beyond the structured 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?

The description is concise: two sentences with no redundant information. The primary purpose is in the first sentence, and the second sentence adds relevant detail about timestamps and automatic creation. Every word earns its place.

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 simple read-only tool with one fully documented parameter and safety annotations, the description is largely complete. It explains what the tool returns ('timestamped .bak files') and their origin. It does not specify the exact return format, but this is a minor gap given the simplicity and the absence of an output schema.

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?

The input schema already fully describes the only parameter, filepath, with type and a clear description ('Path to the library file (.PcbLib or .SchLib)'). The description does not add additional parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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 a specific verb ('List'), a resource ('available backup files for an Altium library'), and the file type (.bak). It differentiates from siblings like restore_backup by focusing on listing rather than restoring, so an agent can understand the tool's role at a glance.

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 implies the tool is for inspecting backups, and mentions they are automatically created before write operations, but it does not explicitly say when to use this tool versus alternatives like restore_backup or write operations. Context is understandable but no direct when-to-use or when-not-to-use guidance is given.

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

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. The description adds value beyond annotations by explaining pagination behavior with limit/offset and the default state (returning just names unless include_metadata is true). This is useful behavioral context without contradicting the 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?

The description is two concise sentences with no fluff. The core purpose is front-loaded, followed by pagination behavior and the optional metadata flag. Every sentence earns its place, making it easy to scan.

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 read-only listing tool with no output schema, the description is sufficiently complete: it names the resource, the supported file types, the pagination mechanism, and distinguishes the two return modes (names vs. metadata). It doesn't specify the exact response format, but that is acceptable given the schema-defined parameters and the read-only context.

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% for all four parameters, so the baseline is 3. The description adds semantic context: it connects limit/offset to pagination for large libraries and gives concrete examples of metadata (part_count, pin_count) that include_metadata yields. This extra meaning justifies a 4.

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 states the specific verb 'List', the resource ('component/footprint names in an Altium library file'), and the scope ('(.PcbLib or .SchLib)'). This clearly distinguishes it from siblings like get_component or search_components, which target individual or filtered components rather than a full listing.

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 gives context on when to use pagination ('for large libraries') and when to enable include_metadata, but it does not explicitly contrast this tool with alternatives like search_components or get_component. The usage guidance is implied rather than explicit, so an agent may need to inspect siblings to determine the right choice.

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

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

The description substantially expands on the annotations. It discloses mutation and destructive behavior in concrete terms: add/remove change the library, every change creates a timestamped .bak, and only the five newest backups are kept. It also explains edge-case behavior such as case-insensitive name matching, refusal of duplicate/missing links, and the fact that the .PcbLib itself is never modified.

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 a single dense paragraph with every sentence earning its place. It front-loads the core operation, then covers validation rules, backup behavior, the library_path nuance, and sibling routing in a natural order. No filler or repetition.

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 mutating tool with 6 parameters, no output schema, and a destructive annotation, the description covers everything needed to call it correctly: operations, required/optional parameters, failure modes, side effects, backup behavior, and alternatives. An agent has enough context to select and invoke this tool safely without additional investigation.

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 coverage is 100%, so the schema already documents every parameter. The description still adds meaningful semantics beyond the schema: add refuses already-linked names, remove refuses unlinked names, matching is case-insensitive, and library_path is tied to writing ModelDatafile0 and Altium resolution. This goes beyond a baseline 3, though the schema remains the primary source for basic parameter definitions.

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 opens with a specific verb and resource: 'Manage the footprint links (PCB models) of one symbol in a .SchLib' and immediately enumerates the supported operations (list, add, remove). It also distinguishes itself from related tools by naming manage_schlib_parameters, get_component/read_schlib, and update_component, so an agent can tell exactly what this tool does and does not do.

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?

Usage guidance is explicit: it states when to pass library_path versus omit it, and it names concrete alternatives for related tasks ('Use manage_schlib_parameters for parameters such as Value', 'get_component or read_schlib to see the links together with the rest of the symbol', 'update_component to rewrite a symbol wholesale'). This leaves little to inference.

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

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

Annotations already mark this as destructive, but the description goes well beyond them: it discloses automatic timestamped .bak backups keeping the five newest, states that set refuses missing names and add refuses existing ones, and explains the reply carries the stored parameter and that list returns all parameters with a count. 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?

The description is long but every clause carries information: operation set, case-insensitivity, duplicate rules, backup behavior, output shape, and sibling routing. The core purpose is front-loaded, and the alternative-tool guidance is compactly placed at the end.

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 multi-operation tool with 11 parameters and no output schema, the description is unusually complete: it explains response contents, list return shape, backup side effects, parameter matching rules, and when each sibling should be used instead. An agent has nearly everything needed to invoke it correctly.

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 coverage is 100%, so the baseline is 3. The description adds meaningful operational semantics beyond the schema: case-insensitive name matching, set-vs-add refusal behavior based on existing parameters, and which operations each parameter class applies to. It does not deeply enrich every individual field, but the schema already covers those details.

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 opens with a specific verb+resource: 'Manage the parameters of one symbol in a .SchLib' and enumerates the exact operations (list, get, set, add, delete). It also distinguishes itself from siblings by naming get_component, read_schlib, update_component, and manage_schlib_footprints as 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?

The description explicitly routes the agent to sibling tools and explains why: use get_component/read_schlib to see parameters with pins/graphics, update_component to rewrite a whole symbol, and manage_schlib_footprints for footprint models rather than parameters. It also clarifies when to use set vs add based on whether the parameter already exists.

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

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

Even though annotations already flag destructiveness, the description goes well beyond them, detailing model deduplication, handling of missing 3D models, warning reporting, and preservation of external STEP references. It also instructs using dry_run for a non-destructive preview, which is valuable behavioral guidance an agent could not derive from structured data.

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 compact and front-loaded with the core purpose, then moves into constraints and edge-case behavior. Each sentence earns its place; only the model-deduplication parenthetical adds some density without harming readability.

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 destructive merge tool with no output schema, the description covers the essential constraints, behavior, and preview path. It could explicitly mention what the result/return value looks like beyond 'reported in warnings, but given the strong schema and annotations, this is a minor gap.

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 coverage is 100%, so the baseline is 3, and the description adds useful meaning on top: source libraries must all be the same type, and dry_run previews the merge without modifying files. It does not add much about on_duplicate, but the schema already documents that parameter's meaning and defaults, so the description's contribution is sufficient.

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 starts with a specific verb and resource—'Merge multiple Altium libraries into a single library'—and clearly distinguishes this operation from sibling read, write, and copy tools. It also names the key constraint that all sources must be the same library type, which helps an agent pick it over alternatives like copy_component_cross_library.

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 gives concrete usage context: all sources must be same type, and dry_run=true is recommended for preview. It does not explicitly contrast this tool with siblings or state when not to use it, but the task is well contextualized by the 'merge multiple libraries into one' framing.

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

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

Annotations already set readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: fidelity fields that must be passed unchanged for byte-identical rewrites, omission of empty lists/optional fields, compact-mode behavior for Simple stack_mode pads, and paging response metadata (total_count, returned_count, offset, has_more). These disclosures go well beyond the annotations and accurately predict output semantics.

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 front-loaded with the core purpose and then logically flows through usage, alternatives, data shape, fidelity rules, omission semantics, compact flag, paging, and component_name. Every sentence contributes unique functional information; there is no filler or redundancy. Its length is justified by the tool's complexity and absence of an output schema.

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?

Despite no output schema, the description covers the return format (structured JSON, units, included primitives), fidelity requirements, empty-value handling, compact-mode output, pagination metadata, and the effect of component_name. It also points to the shared JSON shape with get_component/export_library/write_pcblib, giving the agent enough context to correctly invoke and interpret results.

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?

Even with 100% schema description coverage, the description adds real meaning: 'compact (default true) omits a pad's per-layer size and shape arrays when its stack_mode is Simple', 'component_name fetches one footprint and turns paging off', and 'page with limit and offset: the result reports total_count...' These clarify how each parameter affects behavior, not just its type.

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 opens with a precise action and resource: 'Read an Altium .PcbLib file' and specifies the returned content (every footprint with description, height, primitives) and units. It also names sibling tools and their distinct use cases, allowing an agent to immediately differentiate read_pcblib from get_component, search_components, and list_components.

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 explicitly says when to use this tool ('study a library's footprint style or to fetch data for a read-modify-write') and provides clear alternatives: 'For one footprint whose name you know, get_component is cheaper; to find footprints by name pattern across libraries, search_components; for names alone, list_components.' This exceeds the minimum by giving both context and exclusion conditions.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description reveals important behavior: coordinate units (10 units = 1 grid square), fidelity-carrier fields that must be passed back unchanged for byte-identical rewrites, omission semantics for empty fields, and paging behavior with total_count/has_more. There is no contradiction with the 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?

The description is long but every sentence carries new operational information: usage intent, coordinate units, sibling alternatives, fidelity requirements, empty-field conventions, and paging details. It is front-loaded with the read purpose and scoping, with no filler or repetition of the schema.

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, the description compensates well by specifying the returned content (primitives, parameters, footprint links), the JSON shape shared with other tools, omission conventions, and paging result fields. An agent has enough context to call read_schlib correctly and interpret its results.

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?

The schema already covers all four parameters at 100%, so the baseline is 3. The description adds meaningful semantics by explaining that component_name fetches one symbol and disables paging, that limit/offset are for paging large libraries, and that a missing component_name errors out with the available symbol names. This clearly exceeds the schema-only 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 description names a specific verb ('Read') and resource ('Altium .SchLib file') and enumerates exactly what is returned: symbols with primitives, parameters, and footprint links as structured JSON. This clearly differentiates it from the PcbLib-oriented read_pcblib and related symbol tools like get_component.

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 explicitly states when to use this tool ('study a library's symbol style' or 'fetch data for a read-modify-write') and names concrete alternatives: get_component for a known symbol, search_components for name-pattern lookup, and list_components for names only. This gives an agent clear selection criteria.

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

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

Below the destructiveHint=true and readOnlyHint=false annotations, the description adds meaningful context: the operation is atomic, and it preserves all primitives and properties while changing only the name. This goes beyond the flat 'destructive' annotation and reassures the agent about scope of mutation.

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?

Two front-loaded sentences earn their place: the first states the action and scope; the second adds atomicity/preservation guarantees and a usage comparison. Nothing is repetitive or extraneous.

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 mutation tool with destructiveHint=true and no output schema, the definition covers the core call semantics: what changes, what is preserved, and the safer dry-run validate path exists in the schema. A minor gap is not disclosing failure cases (e.g., old_name not found or new_name colliding), but these are not required for correct invocation.

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% — the input schema fully documents filepath, old_name, new_name, and dry_run. The description introduces no additional parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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 states a specific verb ('Rename'), a specific resource ('a component within an Altium library file'), and the file scope (.PcbLib/.SchLib implied). It also differentiates itself from the copy+delete workflow, making it distinguishable from the 30+ sibling tools 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?

The description explicitly says 'More efficient than copy + delete for simple renames,' which routes the agent away from a close sibling workflow toward this tool. However, it does not address adjacent alternatives like bulk_rename or update_component, so the guidance is clear but not a complete when-to-use/when-not-to-use map.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read behavior is covered. The description adds meaningful behavioral context: it lists exactly which primitives are visualized, notes the per-kind count and legend, and clarifies that this is ASCII preview output rather than a graphical render. It doesn't mention potential performance limits with very large footprints, but the added detail is solid.

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?

One well-structured sentence that front-loads the main purpose, enumerates the covered primitives with parentheses, and ends with a crisp scope qualifier. No filler or repetition of schema details.

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 read-only preview tool, the description covers the scope, output shape, and primitives well. The lack of an output schema means an agent won't know the exact character output structure, but the per-kind count and legend are described, which is reasonable. The main missing piece is guidance on error scenarios (e.g., non-existent component or file), but this is not critical for a lightweight preview tool.

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 coverage is 100%, so all five parameters are already documented precisely, including defaults and units. The description adds value by explaining the overall rendering scope (which primitives appear and that there are markers/legend/counts), complementing the schema without duplicating it. This is above the baseline 3 because the description helps an agent understand what the output will include, which informs how to tune scale and max dimensions.

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 states a specific verb (render), resource (footprint from a PcbLib file), and format (ASCII art visualisation). It enumerates the primitives covered and explicitly distinguishes itself from a full rendering ('A quick preview, not a rendering'), which helps differentiate it from sibling tools like render_symbol.

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's closing note ('A quick preview, not a rendering') implies when it should be used, and the sibling list makes render_symbol the clear alternative. However, it doesn't explicitly say 'use render_symbol for symbol previews' or state when a full rendering would be needed, so some guidance is left to inference.

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

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

Annotations already mark the tool as read-only and non-destructive, but the description adds substantial behavioral detail: every record kind gets its own marker, followed by a per-kind count line and legend; coordinates are schematic units (10 units = 1 grid); output is limited to max_width x max_height characters. This fully paints the execution behavior and output format beyond what annotations convey.

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 a single dense paragraph but is well-organized: purpose, output format, parameter semantics, units, then routing to alternatives. Every sentence carries needed information, though the structure could be slightly broken up for easier scanning. No wasted words.

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 read-only preview tool with a full schema, the description covers the output structure, parameter effects, coordinate system, output size limits, and alternatives. There is no output schema, but the description explicitly describes what the ASCII-art output contains (markers, count line, legend), so an agent knows what to expect. Nothing essential is missing.

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 coverage is 100%, so each parameter's basic meaning is documented. The description adds extra nuance by explaining scale in 'characters per 10 schematic units', clarifying part_id's default and the all-parts behavior of 0, and stating the coordinate-unit convention. This goes beyond the schema descriptions while remaining consistent with them.

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 opens with a specific verb and resource: 'Render an ASCII-art preview of one symbol in a .SchLib.' It immediately clarifies the tool's scope (one symbol), its purpose (quick visual check), and its non-archival nature (not a drawing to keep), which distinguishes it from other library tools without needing to see sibling names.

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?

Provides explicit routing: use get_component or read_schlib for exact coordinates/properties, and render_footprint for a .PcbLib footprint. This tells an agent exactly when to choose this tool over alternatives and when to defer to others, leaving no ambiguity about its niche.

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

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

With destructiveHint=true already signaling mutation, the description adds meaningful behavioral detail: components not in the provided list are appended at the end in their original relative order. This is useful beyond the annotations and helps the agent predict the exact outcome.

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 core action and target file types. Every sentence adds necessary information, and the key behavior about unspecified components is stated clearly without redundancy.

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 two-parameter mutation tool with no output schema, the description covers the main inputs and the important edge-case behavior. It does not specify return values or error handling, but those are not essential given the straightforward scope.

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 coverage is 100%, so the baseline is 3. The description adds meaning to component_order by clarifying the ordering behavior and the fallback rule for omitted components, which is not in the schema.

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 states a specific verb ('Reorder'), a clear resource ('components in an Altium library file'), and the file types (.PcbLib or .SchLib). It clearly differentiates this tool from siblings like list_components, read_pcblib, and write_pcblib.

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 implies when to use the tool by scoping it to reordering components in Altium library files, but it does not explicitly state when to prefer this over alternatives or mention any constraints or prerequisites. Usage context is present only by implication.

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

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

The description discloses the destructive nature by stating it removes data, and mentions the refusal of SchLib files, which are behaviors beyond the annotations that already mark it destructive. It does not detail all side effects (e.g., whether changes are saved automatically), but the annotation covers the core destructiveness.

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, using two sentences with a clear enumerated list of the two repair operations. It avoids unnecessary detail and is well-structured for quick comprehension.

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?

It provides sufficient context about the problem it solves (missing STEP references) and the trigger condition (validate_library reports both conditions), along with the scope restriction. While it does not mention the effect of dry_run (covered by the parameter description), the overall context is adequate for an agent to decide to invoke the tool.

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?

The schema provides full descriptions for both parameters (filepath and dry_run). The tool description adds context about the file type (PcbLib only) but does not significantly enhance the semantic understanding of the parameters beyond what the schema already provides.

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 repairs PcbLib files by removing orphaned 3D-model data, enumerating two specific types (embedded models not referenced and body references to non-existent models). It distinguishes this tool from other library operations by focusing on the repair action.

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?

It implies usage after validate_library reports the orphaned data conditions, and it explicitly states the scope (PcbLib only, SchLib refused), which helps an agent decide when to use this tool. However, it does not name alternative tools for comparison.

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

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

The annotations already mark this as destructive, but the description adds meaningful behavior beyond that: the current file is snapshotted first, the operation is reversible, and the restore is atomic. This is exactly the kind of safety-relevant context an agent needs and could not get from the annotations alone.

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, each earning its place: the core operation, the default behavior, and the crucial safety semantics. The main action is front-loaded and there is no filler or redundant restating 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?

For a destructive tool with no output schema, the description covers the required input, optional input behavior, reversibility, and atomic write semantics. It mentions pre_restore_backup as reported output but does not fully describe the response shape. This is a minor gap and does not undermine successful invocation.

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%, and both parameters are already well documented: filepath is required, backup_path is optional and defaults to the most recent backup. The description repeats the default behavior but does not add new parameter-level semantics beyond what the schema provides, so the baseline of 3 applies.

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 states a specific verb and resource: restore an Altium library file from a backup. It also clarifies the default behavior of using the most recent backup when none is specified. Among the sibling tools, this is clearly the restore operation and is not easily confused with read/write or component-level 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 gives useful operational guidance about the optional backup_path and the default fallback to the most recent backup. However, it does not explicitly say when to use restore over other tools or point to list_backups as the companion tool for selecting a backup. The usage context is implied rather than stated.

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

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

Annotations already carry the safety profile (readOnlyHint=true, destructiveHint=false), so the description only needs to add behavioral context beyond that. It discloses what is returned ('matching component names with their source library paths'), which is useful, but it does not describe edge behaviors like empty-match results, case sensitivity, invalid-pattern handling, or search scope 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?

Three sentences with zero waste: the first states the action and method, the second states the return value, the third states supported file types. The core purpose is front-loaded, and every sentence earns its place.

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 read-only search tool with 3 params (2 required, 1 enum) and annotations covering the safety profile, the description is nearly complete. It even compensates for the missing output schema by stating the return content ('matching component names with their source library paths'). Minor gaps remain only around empty-result behavior and match semantics, which are low-stakes for a non-destructive search.

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 pattern, filepaths, and pattern_type. The description adds marginal reinforcement by tying 'regex or glob patterns' to the pattern_type enum and file extensions to the filepaths parameter, but it does not add new semantic detail beyond what the schema already provides.

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 states a specific verb and resource: 'Search for components across multiple Altium libraries using regex or glob patterns,' which clearly distinguishes this from siblings like list_components (enumerate all), get_component (fetch one known component), and read_pcblib/read_schlib (read whole files). It also clarifies scope by naming both supported file types, '.PcbLib' and '.SchLib,' so an agent knows exactly what this tool covers.

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 implies when to use the tool: when you need to find components by pattern across multiple libraries rather than reading a whole library or fetching a known component. It names the search methods ('regex or glob patterns') and the return value, giving clear context, but it does not explicitly name alternatives or state when-not-to-use conditions relative to siblings like list_components or component_exists.

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

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

Annotations carry only readOnlyHint=false and destructiveHint=true, so the description must carry the behavioral burden — and it does, substantially. It discloses that replacement is wholesale ('a primitive left out is removed'), rename side-effects and refusal rules, case-insensitive name matching, error behavior listing available names, dry_run reporting (would_rename, changes list), and real-run behavior (backup, save, returns renamed/old_description/component_count plus post-write validation). This is far beyond the annotation baseline and confirms rather than contradicts the destructiveHint.

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?

A single dense paragraph with no wasted sentences — purpose, naming constraint, shape rule, replacement semantics, rename behavior, dry_run, real-run returns, and alternatives all earn their place. It front-loads the core purpose before the details. Slightly held back from a 5 because the long unbroken block of text could be more scannable with paragraph or bullet separation for an agent, but the content density is justified by the tool's complexity.

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, the description correctly carries the return-value burden, naming both dry_run and real-run results (would_rename/changes list vs. renamed/old_description/component_count/validation). It covers error behavior, backup, rename edge cases, and points the user to get_component's output as the editing starting point. The only minor gap is that it doesn't detail what the post-write validation checks, but for a complex mutation tool with rich 100%-coverage schema this is nearly 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?

Schema coverage is 100%, so the schema documents each field individually — baseline 3. The description adds cross-field meaning the schema cannot: the conditional rule 'Provide footprint for a .PcbLib or symbol for a .SchLib, in the shape write_pcblib or write_schlib takes', how the object's name interacts with component_name (rename vs. keep), and the case-insensitive matching of component_name. This goes beyond individual field 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?

States a specific verb and resource: 'Replace one existing component of an Altium library (.PcbLib or .SchLib) with the object given, keeping its position in the library.' This is a precise, single-target operation and is clearly differentiated from siblings — the Alternatives list names write_pcblib/write_schlib, batch_update, update_pad/update_primitive and rename_component as distinct scopes. An agent can tell exactly what this tool is for versus its near-neighbors.

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?

Ends with an explicit Alternatives clause: 'write_pcblib or write_schlib to rewrite a whole library, batch_update for one change across every component..., update_pad or update_primitive to change one primitive in place, rename_component for a rename alone.' This gives explicit when-not and alternative routing, and the body clarifies when to reach for this tool (replace one component wholesale while keeping its position).

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false; the description complements them by disclosing the conditional cascade to per-layer tables on stacked pads and the response count behavior. It does not discuss overwrite/reversibility, but the destructive annotation lowers that burden.

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 purposeful sentences: core purpose, operational lookup, and the one non-obvious side effect. No filler or repetition of schema boilerplate; the nuance is placed after the primary use case.

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, the description supplies some return information ('response reports how many followed') and the schema covers all parameters. It could still say what a normal success response looks like, but for a moderate-complexity mutation this is a minor gap.

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 coverage is 100% and each parameter has a good description, so the baseline is 3. The description adds real value for width/height/shape by explaining exactly how updates propagate on stacked pads ('layers that shared the old primary value follow it...'), going beyond the schema.

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: 'Update specific properties of a pad in a PcbLib footprint'. It also clarifies scope with 'without replacing the entire component' and 'Find pad by designator', distinguishing it from whole-component rewrite tools like write_pcblib or update_component.

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 communicates clear intended usage: targeted partial pad changes via designator, not whole-component replacement. It does not explicitly name alternative tools or state when-not-to-use conditions, so it misses the full 5, but the context is clear enough for routing.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses important side effects: moving a layer drops its associated carriers, and changing a stacked via diameter propagates to per-layer diameters and reports the count. This provides transparency beyond the basic hints.

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 yet packed with essential behavior details, structured logically: first the core action, then layer-carrier consequence, then via diameter nuance. No redundant sentences.

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?

Given the complexity (six primitive types with differing properties, dry_run option, layer carrier implications), the description covers all necessary context for correct invocation. It even hints at output behavior for via diameter updates, and the absence of an output schema is not a gap.

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?

Although the schema already provides per-property descriptions, the description adds crucial context by listing which properties are valid for each primitive_type and stating that any other key is refused. This significantly enhances semantic clarity and reduces misuse.

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 updates specific properties of a primitive in a PcbLib footprint, identifying the resource and action. It distinguishes itself from update_pad by explicitly stating pads are not handled here and should use update_pad.

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 explains how to locate a primitive via read_pcblib's index and explicitly directs pad updates to update_pad. It also details conditional behaviors (layer move dropping carriers, via diameter propagation) which guide usage.

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

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

The annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral detail by listing the categories of issues detected and stating that the tool 'returns a list of warnings and errors,' which clarifies it is purely diagnostic and non-mutating.

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 compact yet highly informative. It front-loads the main purpose, then uses a scannable list of concrete checks, and finishes with the return behavior. No unnecessary filler or repetition is present.

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 single-parameter, read-only validation tool, the description covers what it does, what it checks, and what it returns. It does not specify the exact structure of warnings and errors, but it provides enough for an agent to select and invoke the tool correctly. The absence of an output schema makes a slightly richer description of return format desirable, but not essential.

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 coverage is 100%, with the only parameter 'filepath' already described as 'Path to the .PcbLib or .SchLib file.' The description does not add anything beyond that, so the baseline of 3 applies: the schema does the work and the description does not need to compensate.

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 states a specific verb ('Validate'), a clear resource ('Altium library file'), and enumerates the exact checks performed. This distinguishes it from read/write/repair siblings even without naming them, because the focus on integrity checking is explicit and concrete.

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 context for using the tool is implied: use it when you need to check a library for common integrity issues. However, the description does not explicitly say when not to use it, mention alternatives like repair_library or read_pcblib, or clarify that it is a diagnostic rather than a corrective tool.

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

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

Annotations already flag this as destructive (destructiveHint: true), so the description does not need to restate that. It adds useful context by clarifying that only the project source is generated and that compiling to a binary .IntLib is deferred to Altium Designer. However, it does not disclose whether an existing file at the target filepath would be overwritten or what side effects may occur, leaving a minor transparency gap.

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 three sentences with no filler. The first sentence states the core action and resource, the second explains path semantics, and the third clarifies the boundary of the operation with the user's next step. It is front-loaded and every sentence earns its place.

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 two-parameter tool with no output schema, the description sufficiently covers the object being written, how document paths are interpreted, and the fact that compilation is not part of this operation. The main omissions are explicit overwrite behavior and direct routing to sibling tools, but annotations and the overall description keep this mostly 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?

The input schema already fully describes both parameters, so the baseline is met. The description adds meaningful value by explaining that member documents are referenced relative to the .LibPkg location and that same-folder files become bare names, which helps the agent construct correct document paths.

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 opens with a specific verb and resource: 'Write an Altium Library Package (.LibPkg) project file that groups source library documents.' It clearly distinguishes this container-level tool from sibling tools like write_schlib and write_pcblib by targeting the project file rather than individual library documents.

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 clearly states the context: this tool groups .SchLib/.PcbLib documents so they can be compiled into an .IntLib, and it explicitly notes that only project source is generated while compilation is a separate Altium Designer action. It does not explicitly name sibling alternatives or give a 'when not to use' exclusion, so it stops short of a 5.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, which the description's file-modifying behavior confirms with no contradiction. Beyond the annotations it discloses numerous subtle behaviors an agent must know: auto-insertion of a '.Designator' text, the auto_3d_body placeholder flagged 'assumed_height', the silk-on-pad warnings array, the read-echo immunity, and the hard '|' separator restriction. This is exactly the kind of behavioral disclosure that prevents silent surprises.

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?

Every sentence earns its place — there is no fluff — but the description is a single dense wall of text with no paragraph breaks or bullet structure. Critical constraints are spread unevenly: the mm-units requirement and the '|' restriction (arguably the two most likely to cause a failed write) sit at opposite ends, with the important '|' rule buried in the final clause. Scannability suffers for a description of this length.

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?

Given the tool's very high complexity and the absence of an output schema, the description compensates well by explaining the response ('bodies' array with height/source and 'none' source, 'warnings' array), the read-modify-write contract, and the auto-generation behaviors. It is nearly complete; the only shortfall is structural, not informational.

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 coverage is 100% and the schema documents each parameter exhaustively, so the baseline is 3. The description still adds genuinely useful aggregate context: the mandatory millimetre unit convention, the IPC-7351B responsibility placed on the AI, and the '|' constraint that no text field may contain. These go beyond the per-field schema text and materially affect correct invocation.

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 opens with a specific verb+resource: 'Write footprints to an Altium .PcbLib file'. It immediately establishes what is produced (a footprint library) and enumerates the primitive types involved (pads, tracks, vias, fills, arcs, regions, text, component_bodies), clearly distinguishing this footprint-focused writer from siblings like write_schlib (symbols) and write_libpkg (projects).

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 gives strong usage context: the append flag for add-vs-replace, the auto_designator/auto_3d_body toggles, and the read-modify-write pairing with read_pcblib (echoed footprints carrying primitive_order are never touched). It does not, however, explicitly name siblings to avoid (e.g. write_schlib for symbols), leaving that differentiation implicit in the subject matter rather than stated.

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

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

Annotations already declare destructiveHint=true, openWorldHint=false, and readOnlyHint=false. The description adds valuable specifics: the '|' character restriction in text fields, coordinate units (10 units = 1 grid square), pin body_end/tip echo behavior, and the distinction between append and replace. It does not explicitly warn about overwriting existing content when append=false, but the append note conveys the replace semantics.

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 a dense paragraph of about 200 words. It front-loads the core purpose and append semantics, but the second half packs several distinct concepts (units, pin geometry, separator restriction) into one long sentence, which reduces readability and may bury the most critical operational constraints.

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?

Given a 3-parameter tool with 100% schema coverage and no output schema, the description covers the essential operational context: file format, append behavior, coordinate system, pin orientation, multi-part handling, and a key text constraint ('|'). It omits explicit mention of what happens to an existing file when append=false (though implied) and does not list all supported primitive types in the schema scope, but the schema enumerates them.

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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining coordinate systems ('a pin's (x, y) is its body-attach end and orientation is the direction it points outward — the response echoes each pin's computed body_end and tip'), the '|' separator constraint not in the schema, and the multi-part design pattern (part_count + owner_part_id).

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: 'Write schematic symbols to an Altium .SchLib file.' It immediately clarifies the file format and the append-vs-replace semantics, distinguishing it from read_schlib (read) and write_pcblib (PCB footprints).

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 explains the append flag's effect, which implicitly signals when to use the tool versus alternatives, but it does not explicitly state when to choose this over write_libpkg or import_library, nor does it warn about the destructiveHint=true behavior (overwrite) beyond the append note.

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