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

Annotations only flag destructiveHint/openWorldHint/idempotentHint; the description goes far beyond, disclosing that other Claude Code sessions lose their connection, in-flight calls fail, the extension WebSocket drops with reconnect timing (typically <1s, capped 15s), the proxy reconnects transparently, and the call returns before the new daemon is necessarily up.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the action, then usage rules, then a bulleted side-effects block, then the return contract. Every sentence carries decision-relevant information; nothing is padding despite the 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?

For a destructive, cross-session-affecting operation with no output schema, the description supplies the missing return contract ({ ok, pidWas, message }, ~100ms flush window) and full blast-radius disclosure. An agent has everything needed to decide and invoke 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?

There is one optional 'reason' parameter and schema description coverage is 100%, so the schema already documents it fully; the description adds no syntax or format detail for it. Baseline 3 applies when the schema does the heavy lifting.

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?

Opens with a specific verb and resource: 'Restart the EasyEDA bridge daemon.' This is unmistakably distinct from every sibling (all pcb_/sch_/lib_/document_ operations), so an agent can identify it 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?

States the precise trigger ('only after the bridge-daemon code itself has changed... new code loaded without manually killing the process') and an explicit exclusion ('DO NOT use this just because the EasyEDA browser extension was reloaded'), explaining why the extension reconnects on its own.

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/idempotentHint, so safety is covered. The description adds a non-obvious side effect (schematic sources are run through the schema validator and unknown tags logged to a file) and clarifies the response is unchanged. Some surrounding text (backups, validate flags) belongs to sibling upload tools rather than this one.

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?

Core purpose is front-loaded and the response format follows immediately. The FAST-BATCH block is useful but lengthy and partly concerns other tools, making the description denser than strictly needed for a read-only getter.

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 tool with full schema coverage and no output schema, the description supplies the return format and the validator side effect, which is sufficient. The additional upload/backup detail is more relevant to siblings and slightly inflates the entry.

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 both parameters (document UUID, instance_id) are fully documented in the schema. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline 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?

States a specific verb (get) and resource (raw source of the currently active document), and specifies the exact return format (string in EasyEDA's internal newline-delimited JSON arrays). It is immediately distinguishable from write siblings like document_set_source.

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 routes the agent: switch with editor_open_document first, write back with document_set_source, use document_validate for a structured report, and use the export/edit/re-upload workflow for bulk changes instead of many small MCP calls. Alternatives and conditions are all named.

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?

Goes well past the destructiveHint=true annotation by disclosing that a backup is taken automatically after validation passes, that it is committed to a local git-tracked repo, that backup.sha references the pre-edit state, and that validation only runs for schematic documents (documentType=1) while other types skip with a status. These are non-obvious, high-value behavioral facts for a destructive 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?

Front-loads the core action and the destructive warning, and the workflow paragraph is genuinely useful. It is somewhat long and repeats the git-backup/backup-SHA point twice, which costs a little efficiency without adding 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?

There is no output schema, yet the description covers the return contract (backup.sha), the validation outcome, the mutation risk, and the recommended workflow, plus how to obtain document UUIDs via list_instances/editor_get_open_tabs. Nothing needed to invoke it correctly 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 the baseline is 3; the description adds value by explaining that validate runs the Zod schema on new source and clarifying the schematic-only scope of validation. It largely restates the enum semantics already in the schema, so it does not go far beyond, but the validation-scope clarification is genuine added meaning.

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 ('Load document source from a local file and push it into the currently active document') and even names the internal call it makes (setDocumentSource). It distinguishes itself from project_import_file (project scope) and document_set_source (in-memory source) by tying the operation to a disk file and the active document.

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 prescribes when to use this over alternatives: the FAST-BATCH WORKFLOW paragraph says to export/edit/re-upload instead of issuing many small per-primitive MCP calls, names the sibling pairs (document_save_to_file/project_export_file, project_import_file), and points to document_validate for standalone validation. When-to-use, when-not, and alternatives are all present.

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 only give a coarse safety profile (readOnlyHint=false, destructiveHint=false), and the description adds substantial behavior the agent could not otherwise know: schematic sources are run through the schema validator in warn mode, the response carries a validation report, unknown tags are logged to ~/.easyeda-schema-discovery.jsonl, and mismatches are framed as missing schema coverage rather than bad data. That is real disclosure beyond the structured fields.

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?

Well front-loaded with the core action first, then format, then workflow guidance. It is on the long side and a notable portion (backup SHAs, validate modes, Zod validation) describes the upload path rather than this save tool, which blurs focus, but most of the text is decision-relevant.

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 tool with no output schema, the description does explain what comes back (the document source plus a validation report for schematics). It is nearly complete for invocation; the only gap is that details about upload-side backups and validate modes belong to sibling tools and slightly dilute what is needed specifically to call this one.

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, document and instance_id are already documented in the schema, which sets the baseline at 3. The description clarifies what the file at filePath will contain (EasyEDA internal newline-delimited JSON, or ZIP for .epro), but adds nothing about the document UUID or instance_id parameters themselves.

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 first sentence states a specific verb and resource: save the source code of the active document to a local file, plus the exact serialization format (newline-delimited JSON arrays). It also explicitly positions itself against document_load_from_file as the reverse operation, so an agent can distinguish it from siblings without opening any 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 FAST-BATCH WORKFLOW paragraph gives an explicit when-to-use rule: for many changes, export/edit/re-upload beats many small per-primitive MCP calls, and it names the alternative tools (document_save_to_file/project_export_file vs document_load_from_file/project_import_file). It also states default behavior for the related upload path (validate='strict') and points to document_validate for standalone checks.

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?

Goes well beyond the destructiveHint=true annotation: it discloses that a git-backed backup is taken automatically before replacement, that the returned backup.sha references the pre-edit state, that validation only runs for schematic documents (documentType=1), and that the call throws when validation aborts or backup fails. These are exactly the failure modes and side effects an agent needs for a destructive write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and return shape, then layered with warning and workflow guidance. It is somewhat dense and the backup guarantee is stated twice, but every sentence carries operational weight, so the redundancy is minor.

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?

Even without an output schema, the description specifies the success return shape ({ success, backup: { sha, path }, validation }) and the error conditions, plus validation scoping per document type. For a destructive 4-param tool, nothing essential to correct invocation 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 the baseline is 3, but the description adds value: it explains the validate modes and their strictness semantics, the auto-switch behavior of the document UUID, and the on-disk format ('newline-delimited JSON arrays; .epro files are ZIP archives') that governs the source string. That format context is not in the schema and meaningfully informs the source parameter.

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 the source code of the currently active document') and immediately disambiguates against document_get_source by noting the same format is returned there. The agent can distinguish this as the write counterpart to the get/load/validate siblings without opening a 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?

Explicitly states the correct workflow ('Always get the current source first, modify it, then set it back') and names concrete alternatives for the batch case (document_save_to_file / project_export_file, then document_load_from_file / project_import_file), including the condition (making many changes at once). This is unambiguous when-to-use and when-to-use-something-else 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 the safety profile (readOnly, idempotent, non-destructive, not openWorld), but the description adds substantial context beyond them: which doc types validate, that other types return a 'skipped' report with a reason, a filesystem side effect (unknown tags appended to a discovery log with EDA_DISCOVERY_LOG override), and the distinction between known-invalid samples vs unknown tags. This is exactly the behavioral detail annotations cannot 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?

Front-loaded with the core purpose, then scoped behavior, then return shape — a logical ordering. It is somewhat dense (three short paragraphs), but each block carries real information (supported types, logging side effect, report structure) rather than 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?

With no output schema present, the description carries the full burden and does so: it spells out the returned JSON report shape (docType, lineCount, knownCount, unknownTagCount, invalidCount, samples), validation coverage, and the logging side effect. An agent has everything needed to call and interpret it.

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 of 3 applies. The description restates the filePath-vs-default-document behavior, but this is already documented in the schema, so it adds little meaning beyond what the structured fields provide.

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 verb+resource: 'Validate a document's source against the Zod-backed EasyEDA schema.' It further scopes the tool by naming exactly which document types are validated (Schematic/PCB) and that others are skipped. It never explicitly name-checks a sibling for contrast, but the validation function is unambiguous against the get/set/save/load siblings.

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 gives useful operational guidance — 'Runs on the currently active document by default, or on a local file if filePath is provided' — which tells the agent how to invoke it. However, it offers no when-to-use/when-not guidance relative to sibling tools (e.g., document_get_source) and no prerequisites, leaving the choice of this tool over alternatives 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context by disclosing that returned content is document-type dependent (parent schematic info for schematic pages, associated board info for PCBs), which is exactly the kind of value annotations cannot provide.

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 sentences, zero waste, front-loaded with the core action followed by the type-conditional return detail. Nothing is redundant or padded.

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?

No output schema exists, so the description carries some of the return-value burden, and it does describe the type-conditional structure of the response. A getter with full annotation coverage and a fully documented single parameter is largely complete, though it could say a bit more about the shape of 'detailed info'.

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?

With only one parameter and 100% schema description coverage, the schema fully documents instance_id including the 8-char hex format and the list_instances reference. The description adds nothing about it, so the baseline 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?

States a specific verb (Get) and resource (currently focused document) with a clear scope qualifier. It is distinguishable from siblings like editor_get_open_tabs and editor_open_document by the 'currently focused' qualifier, though it does not name those alternatives explicitly.

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 is implied by 'currently focused document' but there is no explicit when-to-use guidance, no mention of when to prefer this over editor_get_open_tabs or document_get_source, and no stated prerequisites. The agent can infer intent but must guess at alternatives.

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 establish readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new context by disclosing what comes back (all open tabs, active tab marker, split-screen structure), which matters because there is no output schema. It could still mention ordering or multiplicity limitations.

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 short sentences, no filler, and the primary result (open tabs) is front-loaded ahead of the secondary result (split screen structure). 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?

For a simple read-only query tool with complete annotations and a well-documented parameter, the description covers everything needed to invoke it: what it returns and how the active tab is identified. Only richer return detail (ordering, per-tab fields) would add value.

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 single instance_id parameter is fully documented in the schema, including the multi-instance and auto-selection behavior. The description adds nothing about the parameter, so the baseline 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 ('Get all currently open tabs in the editor') and adds scope detail ('active tab marked', 'split screen structure'). It is clearly distinguishable from editor_get_current_document by implication (all tabs vs. one), but it never names or contrasts a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use, when-not-to-use, or alternative is stated. Usage is only implied: an agent can infer this is how you discover which tab is active versus calling editor_get_current_document. That is implied guidance, not stated 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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is clear without the text. The description adds genuine value by disclosing the supported UUID categories, but says nothing about what happens to currently open documents, whether unsaved work is at risk, or behavior when the UUID is invalid. A 3 is appropriate with annotations carrying the safety 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?

Two tight sentences, zero filler, and the core action is front-loaded before the scope qualification. Nothing needs trimming.

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 navigation tool with no output schema and annotations covering idempotence and safety, the description is nearly complete but silent on failure modes (unknown UUID, wrong document type for the current editor mode) and on side effects to existing open tabs. Adequate, with clear but minor gaps.

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 both parameters (instance_id auto-selection rules, documentUuid) are already fully documented in the schema. The description only contributes the set of document types a UUID may refer to, which is a modest addition over the schema's generic 'UUID of the document to open'. Baseline 3 applies when the schema does the heavy lifting.

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 concrete verb (open/navigate) and resource (document) and enumerates the accepted UUID domains: schematic page, PCB, and panel. That level of specificity lets an agent distinguish it from editor_get_current_document and editor_get_open_tabs, though it never explicitly names an alternative it must not be confused with (e.g. pcb_navigate_to).

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 is implied rather than stated: the agent can infer it should call this to bring a document into the editor, and the UUID-type sentence hints at valid inputs. There is no explicit when-to-use vs when-not-to-use guidance and no mention of the sibling navigation tools (pcb_navigate_to, pcb_navigate_to_region) that overlap in intent.

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 (readOnly=false, destructive=false, idempotent=false), it discloses the return value (the new device UUID) and honestly flags that whether the symbol/footprint are deep-copied or cross-library references is unverified - a meaningful behavioral caveat since it affects whether editing the copy touches the source. It still omits error/authorization behavior and collision handling (which lives only in the schema).

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 sentences, front-loaded with the action and the return value, and no filler. The second sentence is a hedge but it carries real behavioral information rather than padding.

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 no output schema, the description supplies the one return value an agent needs (new device UUID) and covers the annotation profile. Missing only failure/permission context, which is a minor gap given the rich 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 description coverage is 100%, so all five parameters (including the conditional instance_id and the collision-failing newDeviceName) are already documented in the schema. The description adds no format, default, or constraint information beyond that 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?

States a specific verb and resource (copy a library device) plus the scope (from one library to another), so an agent knows exactly what operation is performed. It does not explicitly contrast itself with the nearest sibling lib_symbol_copy, but the device-vs-symbol resource distinction makes the target unambiguous.

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 never says when to use this tool versus alternatives such as lib_symbol_copy, nor does it state prerequisites (e.g., both libraries must exist, instance selection when multiple instances are connected). Usage is only inferable from the name and schema.

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?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false) by disclosing that the operation is irreversible, that no undo and no backup snapshot exist because library assets are not documents, and that the return value is a boolean success flag.

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?

Four tight sentences, front-loaded with the action and its scope, then the destructive consequences, then the mitigation. Every sentence earns its place with no 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 destructive, no-output-schema tool, the definition supplies everything an agent needs: irreversibility, absence of backups, the scope boundary versus symbol/footprint, and the return type. Nothing material 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?

All three parameters are already documented at 100% schema coverage, and the description adds no syntax, format, or edge-case meaning for deviceUuid/libraryUuid/instance_id. Baseline 3 applies when the schema carries the full parameter burden.

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 ('Delete a library device') and immediately scopes it by clarifying it does NOT delete the referenced symbol/footprint, which distinguishes it from lib_symbol_delete and lib_device_modify without opening any 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?

Gives a concrete precondition — record the device with lib_get_device first if a restore may be needed — and the symbol/footprint note implicitly routes the agent to the sibling delete for those asset types. It stops short of an explicit when-to-use vs. alternatives comparison, so not 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 already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds genuinely useful behavioral context beyond that: partial-update semantics and the null-clears-a-field convention. It stops short of permission requirements or failure behavior, but with annotations carrying the safety profile this is a meaningful gain.

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 short sentences, front-loaded with the highest-value info (what can be changed), then patch semantics, then association details. Slight redundancy between 're-bind its symbol/footprint' and the later association sentence, but no 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 complex tool with nested objects and no output schema, the description covers the essential calling semantics: partial updates, null clearing, and association swapping. It omits any statement of return value (acceptable with no output schema) and defers instance selection to the schema, but nothing critical for correct invocation 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 high (86%), so the baseline is 3, but the description adds real meaning: it clarifies that nullable optional fields are cleared by passing null, and it explains the purpose of the nested association object (swap symbol/footprint UUIDs), which the schema only labels tersely. That goes beyond what the schema conveys.

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 (modify) and resource (library device), then enumerates the mutable facets: symbol/footprint re-binding, name, classification, description, and properties. This distinguishes it clearly from its siblings lib_device_delete, lib_device_copy, and lib_get_device.

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 gives solid patch-semantics guidance ('Pass only the fields you want to change', 'Pass null to clear an optional field'), which tells the agent how to invoke it. However, it never states when to prefer this over alternatives like lib_device_copy or lib_device_delete, so usage is only implied.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value by disclosing the scope of the result (metadata only, not source) and where the source actually lives, which is a behavioral boundary not encoded in annotations or schema.

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 sentences, zero filler: the first states purpose and return payload, the second routes to the correct tool for source retrieval. Front-loaded and tightly scoped.

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?

No output schema exists, and the description compensates by enumerating the returned metadata fields (uuid, library, name, classification, description). Combined with the annotations covering the safety profile and full schema coverage, nothing an agent needs to call this correctly 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 description coverage is 100%, so all three parameters (including instance_id and libraryUuid defaults) are documented in the schema. The description only restates 'by UUID' and does not add format or resolution semantics beyond that, so the baseline 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?

Starts with a specific verb+resource ('Get a library footprint's metadata') and enumerates the returned fields, which cleanly separates it from lib_symbol_get and from lib_footprint_open_in_editor. An agent can distinguish it from siblings without opening any 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?

Explicitly tells the agent that this tool does not return source, and prescribes the alternative workflow (lib_footprint_open_in_editor + document_get_source). It gives a clear when-to-use-this-vs-that condition, though it does not state exclusions for the sibling it is contrasted with.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower, yet the description still adds real behavior: opening creates a tab, the call returns a tabId, and system-library footprints are rejected. It does not say what happens if the same footprint is already open in a tab.

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, zero waste, and the core action is front-loaded ahead of the return-value and eligibility details. Every sentence carries distinct 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?

With no output schema, the description correctly explains the return value (tabId and how to use it) and states the eligibility restriction. The remaining gap is what state the editor/tab ends up in and whether repeated opens stack tabs.

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 four parameters and the baseline is 3. The description adds indirect meaning only (libraryUuid must point at a personal/team/project library, and the returned tabId is a document UUID); it says nothing about instance_id or splitScreenId.

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+resource ('Open a library footprint in the EasyEDA editor as a tab') and pins the scope with a hard constraint ('only footprints in a personal, team or project library'). The footprint/symbol distinction is unambiguous against lib_symbol_open_in_editor, which shares the same verb.

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?

Gives clear when-to-use context plus a chaining recipe: take the returned tabId and feed it to document_get_source / document_save_to_file as the document UUID. It also states a negative condition (system-library footprints are refused). It does not name an alternative tool for cases where the footprint should not be opened interactively.

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?

Goes well beyond the destructiveHint=true annotation: states it is IRREVERSIBLE, that no undo and no backup snapshot exist because library assets aren't documents, spells out the required library permission level, and declares the boolean return. This is exactly the extra context the annotation bar rewards.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the irreversible warning first, then workflow, then precondition, then return value - well ordered. It is somewhat dense with parentheticals, but every sentence carries load; no 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?

A destructive mutation with no output schema, yet the description covers safety, required permissions, a safe pre-step, and the return type. Nothing an agent needs to call it correctly 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 the baseline is 3. The description adds real meaning for libraryUuid (must be a library you can write to - personal/team/project) and ties documentSource to the format document_get_source returns, which is slightly beyond the schema text.

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?

Precise verb+resource: 'Replace a library footprint's entire source.' The 'entire source' scope and the 'footprint' (vs the symbol sibling lib_symbol_update_document_source, and vs document_set_source on the open document) let an agent distinguish it without opening a 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?

Gives a clear precondition workflow ('Read and save the current source first' via lib_footprint_open_in_editor + document_save_to_file) and a gating condition ('must live in a library you can write to'). It does not state explicit when-not-to-use or name the update-in-place sibling as an alternative, 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 already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered without the description. The description adds only the return shape (UUIDs and names), which is modestly useful since no output schema exists. No pagination, ordering, or size caveats are disclosed.

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, front-loaded sentence that names the resource and the returned fields with no filler. It is appropriately sized for a simple read tool, though there is no additional structure because there is nothing else to say.

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, zero-required-param list tool whose annotations cover safety, this is close to sufficient, and it even describes the return payload in the absence of an output schema. The gap is the absence of routing guidance among the several sibling library-UUID tools, which is the main thing an agent would need.

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 the single instance_id parameter is fully documented in the schema, including the auto-selection rule and the list_instances pointer. The description adds nothing beyond that, 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?

States a specific verb+resource: 'Get a list of all available component libraries with their UUIDs and names.' The word 'all' and 'list' distinguish it as a bulk enumeration rather than a single-record lookup. It does not, however, explicitly differentiate itself from sibling UUID getters like lib_get_personal_library_uuid or lib_get_system_library_uuid.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance is given. It never mentions the alternatives (lib_get_personal_library_uuid, lib_get_project_library_uuid, lib_get_system_library_uuid) that an agent must choose between to fetch library identifiers. The 'all' phrasing offers an implicit contrast but no directive.

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, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that the response includes symbol, footprint, and 'all properties', but says nothing about error behavior when the UUID is not found or cross-instance/library resolution 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?

A single, well-shaped sentence with the key lookup identifier front-loaded and the return contents trailing. No filler or redundancy, though the trailing clause is a light restatement of expected output rather than new guidance.

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-entity getter with full schema coverage and annotations carrying the safety profile, the description is largely sufficient. In the absence of an output schema it helpfully names the returned fields (symbol, footprint, properties), which covers most of what an agent needs before calling.

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?

With 100% schema description coverage, all three parameters (deviceUuid, instance_id, libraryUuid) are already documented in the schema, including multi-instance handling. The description only restates the UUID lookup and adds no format, scoping, or resolution meaning beyond it, 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?

States a specific verb (Get) and resource (device) with the lookup key (UUID) and the returned content (symbol, footprint, properties). It is clearly distinguishable from lib_search_device and lib_get_device_by_lcsc, though the description does not name those alternatives explicitly.

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 is implied rather than stated: 'by its UUID' signals you need a device UUID in hand. No explicit when-to-use, prerequisites, or routing to the sibling search/lookup tools is given, so the agent must infer this is the follow-up to a search.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds nothing behavioral beyond that — no note on multi-instance targeting behavior (the instance_id requirement) or what a multi-ID query returns. With annotations doing all the work, the description contributes almost no extra context.

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 compact sentences with the core operation front-loaded and a concrete example following immediately; 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 read-only lookup with full schema coverage and annotations covering the safety profile, the description is nearly complete. A brief mention that results span libraries unless libraryUuid is supplied would close the remaining gap, but nothing critical 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 description coverage is 100%, so all three parameters (lcscIds, instance_id, libraryUuid) are already documented in the schema, including the single-vs-array form and the multi-instance condition. The description's C-number example duplicates the schema's own example, adding no new syntax or format detail, so baseline 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 ('Get device(s)') and identifies the lookup key ('by LCSC C-number(s)'), which distinguishes it from siblings like lib_get_device and lib_search_device that presumably key off other fields. It does not explicitly name those siblings, so the differentiation is implicit rather than spelled out.

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 example ('finding specific components like "C17414" for a 2.2k resistor') illustrates a valid use case, giving implied guidance on when to reach for this tool. However, it never states when NOT to use it or points to lib_get_device / lib_search_device as the alternatives for non-LCSC lookups.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by disclosing that the call returns undefined on private deployments, an edge case not captured by annotations and useful given no output schema exists.

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 tight sentence with the core purpose front-loaded and the caveat parenthetically appended. No filler or redundancy to trim.

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 full annotation coverage, a fully documented parameter schema, and only one trivial argument, the description covers what an agent needs, including the private-deployment caveat. It could optionally note the UUID's format or relationship to the other library-UUID tools, but 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 description coverage is 100% for the single instance_id parameter, and the schema already explains the 8-char hex format and the omit-when-single-instance rule. The description adds nothing beyond that, so the baseline 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 names a specific verb (Get) and a precise resource (the user's personal library UUID), which is self-differentiating from the nearby lib_get_system_library_uuid and lib_get_project_library_uuid siblings by the 'personal' qualifier alone. An agent can tell exactly what it retrieves 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 resource name implies when to use it (when you need the personal library's identifier), but there is no explicit when-to-use/when-not guidance or reference to the system/project library UUID alternatives in the sibling set. Usage is inferable but not 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 this a safe, idempotent, closed-world read, so the bar is low. The description still adds real value by disclosing the edge-case return behavior (undefined when no project is open), which the annotations cannot express.

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 front-loaded sentence with a parenthetical for the edge case; every clause earns its place and nothing is padded.

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 parameterless getter with no output schema, the definition covers the one thing an agent needs beyond the schema: what comes back when there is no open project. Missing only an explicit pointer to the sibling UUID getters.

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 single instance_id parameter is fully documented in the schema (100% coverage), including the multi-instance rule and the list_instances pointer. The description adds nothing about the parameter, so the baseline 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?

States a specific verb (get) and resource (UUID of the current project's library), which is more precise than the sibling getters. It does not, however, explicitly distinguish itself from lib_get_personal_library_uuid or lib_get_system_library_uuid, leaving the agent to infer the difference from the 'project' qualifier alone.

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 is only implied: the tool is clearly the project-scoped variant, and the parenthetical hints at a precondition ('if no project is open'), but no alternatives are named and no explicit when-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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the resource scope ('system built-in') and does not disclose any further behavioral traits such as UUID stability or required auth; with annotations covering the basics, this is minimal but adequate.

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 sentence that is front-loaded with the verb and resource. Every word earns its place with zero 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 read-only getter with comprehensive annotations, full schema coverage, and no output schema, the description states the returned value (the UUID) and the resource scope. Nothing an agent needs in order to call it correctly 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 description coverage is 100% and the single optional instance_id parameter is fully documented in the schema, including when to omit it and a reference to list_instances. The description adds no meaning 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?

States a specific verb 'Get' and resource 'UUID of the system (built-in) component library'. The phrase 'system (built-in)' explicitly separates it from sibling tools lib_get_personal_library_uuid and lib_get_project_library_uuid, so an agent can select it without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use, prerequisites, or alternatives are stated. The description does not tell the agent when to choose this over lib_get_all_libraries or the personal/project UUID getters; usage must be inferred from the name alone.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds return-field context (UUIDs, names, descriptions, package info) but discloses nothing about pagination behavior, result caps, or rate/instance constraints beyond what the schema already says.

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 sentences, zero filler, with the action stated first and the return shape second. Nothing is redundant or padded.

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 usefully enumerates the returned fields, and the schema fully documents the five parameters. It is adequate for a read-only search tool; only pagination/default-result behavior is left unstated, which is a minor gap given the page/itemsOfPage params.

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 all five parameters including the 0-based page, instance_id, and libraryUuid are already documented in the schema. The description's 'by keyword' merely restates the key parameter, adding no format or syntax detail beyond the schema. Baseline 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?

Names a specific verb (Search) and resource (component library devices) plus the key mechanism (by keyword). It is distinguishable from lib_get_device and lib_get_device_by_lcsc by retrieval mode, though it never names those siblings explicitly, which keeps it just short of a 5.

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?

'by keyword' implies the intended use case (find devices when you don't already have an identifier), but the description states no when-to-use condition, no when-not-to-use, and no alternatives such as lib_get_device or lib_get_device_by_lcsc. Usage is inferred 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 non-readonly, non-destructive, non-idempotent. The description adds genuine value beyond them: it discloses the return value (the new symbol UUID) and a specific failure condition (name collision in the target library). It does not cover auth/permission requirements, but the failure-mode and return disclosure are useful additions.

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 short sentences with zero waste; the core action is front-loaded and the return value and failure condition follow logically. 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?

With no output schema, the description compensates by naming the return value (new symbol UUID) and the collision failure path. Combined with the fully-covered input schema, an agent has what it needs, though permission/prerequisite context is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters are already documented in the schema (including the instance_id conditional behavior and newSymbolName default). The description only echoes the collision semantics already stated in the newSymbolName schema description, adding no new parameter-level meaning.

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 (copy) and resource (library symbol) plus directionality (one library to another) with a concrete example (system → personal). This clearly distinguishes it from the sibling lib_device_copy, which operates on devices rather than symbols.

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 scenario (moving/copying a symbol between libraries, e.g. system → personal) but never states when to use this instead of alternatives such as lib_device_copy or lib_symbol_update_document_source. Usage is inferable but not 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds material context the annotations cannot: no undo, no backup snapshot is taken, and the reason (library assets are not documents). It also states the return shape (boolean success), which is useful given there is no output schema.

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?

Four tight sentences, front-loaded with the irreversible consequence and followed by the mitigating action and return type. No filler; every sentence changes agent behavior.

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, no-output-schema tool this is complete: it covers irreversibility, the absence of backups, the recovery workflow, and the boolean return value. Nothing an agent needs before calling it 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 description coverage is 100%, including the non-obvious instance_id auto-selection rule and the list_instances referral, so the schema carries parameter meaning. The description adds nothing parameter-specific, which is the correct baseline when the schema already does this work.

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 first sentence states a precise verb+resource ('Delete a library symbol') and the scope is unambiguous against siblings like lib_symbol_get and lib_device_delete. An agent can distinguish it immediately 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?

It names the safety pre-step and the alternative tool explicitly: 'Fetch and save the symbol source with lib_symbol_get first if you may need to restore it.' That routes the agent to the right sibling under a stated condition rather than leaving it 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context by scoping the return payload (metadata only, no .esym source) and routing the caller elsewhere. It stops short of describing errors or behavior when the UUID is not found, so a 4 rather than a 5.

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 sentences, zero waste, and the primary action is front-loaded ahead of the negative/alternative clause. Nothing here could be deleted without losing routing value.

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?

No output schema exists, and the description compensates by enumerating the returned fields (name, classification, description) and explicitly excluding the source body. Combined with the fully documented input schema and read-only annotations, an agent has everything needed to call this 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 all three parameters (including instance_id's multi-instance rule and libraryUuid's default) are already documented in the schema. The description only restates 'by UUID' and adds no format, default, or edge-case meaning beyond that. Baseline 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?

States a specific verb and resource ('Get a library symbol's metadata') plus the key ('by UUID'), and explicitly distinguishes itself from source retrieval by naming what it does NOT return. An agent can separate it from lib_symbol_open_in_editor and document_get_source without reading any 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 names the alternative path explicitly ('use lib_symbol_open_in_editor + document_get_source') for the case the agent actually wants source content, which is the most likely reason to call the wrong sibling. That is an explicit when-not plus named alternatives.

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 cover the safety profile (not read-only, not destructive, idempotent), and the description adds behavior beyond them: it creates an editor tab as a side effect, returns a tabId, discloses the failure mode for system-library symbols (error instead of a tabId), and links the return value to a downstream tool. 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?

Two sentences, zero filler, front-loaded with purpose and return value before the constraint and fallback. 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?

No output schema exists, so the description carries the return-value burden and does so (tabId and its use with document_get_source). Combined with the full schema coverage and annotation safety hints, an agent has everything needed to call this correctly or route to lib_symbol_copy when the call would fail.

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 all four parameters are documented in the schema (including instance_id selection and splitScreenId defaults), so the baseline of 3 applies. The description adds no parameter-level detail such as symbolUuid vs libraryUuid syntax or format 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?

States a specific verb and resource ('Open a library symbol in the EasyEDA editor as a tab') and immediately distinguishes the outcome (returns a new tabId). An agent can tell it apart from siblings like lib_symbol_copy and lib_footprint_open_in_editor without opening either 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?

Explicitly states the precondition that only personal, team, or project library symbols can be opened, that system-library symbols cause an error, and names the alternative (lib_symbol_copy into your own library first). This is exactly the when/when-not/alternative guidance the dimension asks for.

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?

Goes well beyond the annotations: it discloses irreversibility, that no undo exists, that no backup snapshot is taken (because library assets are not documents), the write-permission requirement, and the boolean return. This is exactly the destructive-operation context an agent needs before committing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action, then the irreversibility warning, then the prerequisite and return type. Four tight sentences with no filler; every clause carries actionable 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 destructive mutation with no output schema, the description covers the safety posture, the recovery path, the permission prerequisite, and the return value. There is nothing an agent needs to call this correctly that 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 description coverage is 100%, so all four parameters (symbolUuid, libraryUuid, documentSource, instance_id) are already documented in the schema. The description adds no format or syntax detail beyond it, so the baseline 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?

States a specific verb+resource: 'Replace a library symbol's entire .esym source.' The scope (entire source, symbol-level) is precise and distinguishes it from footprint/document variants and from lib_symbol_get, which it explicitly positions as the read counterpart.

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?

Gives clear operating context: it must target a writable library (personal/team/project), and it prescribes the recovery workflow ('Fetch and save the current source with lib_symbol_get first'). It stops short of naming when-to-use alternatives like document_set_source, so an explicit exclusion is missing.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds useful value by disclosing what the read returns (per-instance project, active document, open tabs), which matters since there is no output schema.

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 sentences, zero waste, with the purpose front-loaded and the routing rationale second. Nothing is repeated from the schema 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?

For a zero-parameter, read-only list tool with no output schema, the description covers what it does, when to call it, and the shape of the result. An agent has everything needed to select and 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies there is nothing to supply and focuses instead on what the call yields.

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 (List) and resource (connected EasyEDA Pro instances) and enumerates the state fields returned (project, active document, open tabs). No sibling tool lists instances, so the distinction is unambiguous from the name plus this scoping sentence.

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 states the use case: find the instance_id needed by other tools when multiple instances are connected. There are no competing alternatives to exclude, but the trigger condition is spelled out clearly rather than implied.

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 idempotentHint=true, destructiveHint=false, readOnlyHint=false, so the safety profile is known. The description adds useful context on coordinate units and frame, which is valuable. It doesn't state what happens to existing content when the origin is changed or whether the change persists to file, so it goes modestly beyond annotations without fully covering behavioral effects.

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?

Four sentences, front-loaded with the core purpose, followed by units/frame then alternative routing. No filler; each sentence carries meaning, though the explicit sentence recommending use of this tool to read/set the offset is somewhat redundant with the opening sentence.

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 get/set origin tool with no output schema, the description gives units, coordinate frame, and the alternative conversion tool – enough for an agent to call it correctly. It doesn't describe the return shape for the 'get' action or persistence semantics, which are minor given annotations and schema coverage.

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 all five parameters. The description adds a coordinate-frame contract (mil, +X rightward, +Y upward) that supplements the plain offsetX/offsetY parameter descriptions, but does not expand on 'action', 'document', or 'instance_id' beyond what the schema says. Baseline 3 is correct.

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+resource ('canvas origin offset relative to data origin') and distinguishes its get/set dual behavior. The units and coordinate frame (+X rightward, +Y upward, mil) make it unambiguous compared to siblings like pcb_convert_coordinates.

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 sibling pcb_convert_coordinates and the condition that selects it ('to convert between canvas and data coordinates'), giving clear alternative routing. It does not spell out when to prefer 'get' vs 'set', but the action enum in the schema covers that.

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 safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), which matches 'clear all selection' — clearing is a state change but non-destructive and idempotent. The description adds only the 'all' scope and no new behavioral context, so it neither contradicts nor enriches 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?

A single front-loaded sentence with no filler. It is appropriately terse for a simple state-clearing tool, though it forgoes the opportunity to add any routing or context.

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 low-complexity selection-clearing tool with no output schema and annotations covering the safety profile, plus 100% schema coverage, the description is sufficient to invoke it correctly. Only usage context 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%: both 'document' (UUID with auto-switch semantics) and 'instance_id' are fully documented in the schema. The description adds no parameter detail, so the baseline 3 applies since the schema already does the work.

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+resource+scope: 'clear' the 'selection' in the 'PCB editor'. An agent can immediately tell this apart from pcb_get_selected (read) and pcb_select_net (set). It does not name alternatives explicitly, but the action is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as pcb_get_selected or pcb_select_net. The single sentence only describes the action, leaving the agent to infer 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 declare this is a safe, idempotent, non-destructive read, so the safety profile is covered. The description adds genuinely useful non-obvious context: units are mil (1 mil = 0.001 inch), coordinates are relative to the canvas origin, and +X/+Y point right/up. It does not restate any annotation and does not contradict 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?

Front-loaded with the core purpose, followed by the unit/origin conventions an agent needs. The final clause ('Use ... pcb_convert_coordinates to convert between canvas and data coordinates') is mildly circular since it restates the first sentence, a small redundancy in an otherwise tight description.

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?

No output schema exists, but the description need not explain the return value for a symmetric conversion tool. It covers units, origin, and axis conventions well; the only untouched behaviors (document auto-switch, instance auto-selection) are already fully documented 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%, so the baseline is 3, but the description adds real meaning beyond the schema's bare 'X coordinate'/'Y coordinate': units in mil and the origin-relative axis convention that determines how the numeric inputs must be interpreted. The direction enum values are self-explanatory and need no further gloss.

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 — converting between canvas and data coordinates — and immediately pins down the unit system (mil, relative to canvas origin) and axis orientation. It also names the related sibling pcb_canvas_origin, so an agent can separate this tool from the origin-management tool without opening either 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?

Gives clear context for when this tool is relevant (any canvas/data coordinate translation) and points to pcb_canvas_origin for the complementary origin-offset task. It stops short of explicit when-not guidance or an explanation of when each direction value should be chosen, but the routing context is clear.

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 this is a non-read-only, non-idempotent, non-destructive write. The description adds the coordinate-space convention (canvas mils, +X right, +Y up), which is real value, but discloses nothing about failure modes, whether a save is required afterward, or how the new primitive is returned. Adds some context beyond annotations, not rich behavioral detail.

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, front-loaded with the action, followed by units and a pointer to helper tools. No filler, though the helper-tool sentence could be tightened. Appropriate length for a 10-parameter primitive-creation tool.

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 10 parameters, no output schema, and full schema coverage, the description covers the critical ambiguity (units and coordinate frame) that the schema omits. It does not address the optional lineWidth or multi-instance behavior, but the schema and sibling guidance largely cover those.

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, but the schema's own parameter descriptions are thin ('Start X coordinate', 'Track width') and omit units entirely. The description compensates by specifying that coordinates and lengths are in mil and defining the axis orientation, which the schema does not.

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: 'Create an arc track segment on the PCB.' An agent immediately knows this produces an arc primitive rather than a straight track. It does not explicitly distinguish itself from close siblings like pcb_create_track or pcb_create_polyline_track, but the arc/segment distinction is clear from the wording.

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 names two helper tools (pcb_canvas_origin, pcb_convert_coordinates) for coordinate handling, which is useful routing guidance. However, it never states when to choose this tool over the other track-creation siblings (pcb_create_track, pcb_create_polyline_track), so usage vs alternatives is only implied.

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 this is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds the coordinate frame and units, but says nothing about whether the fill can be undone, whether a net association is required, or what happens on overlap with existing copper.

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 purpose is front-loaded in the first clause, followed by coordinate semantics and cross-references. The sentence about lengths ('widths, diameters') is generic boilerplate that does not apply to a polygon fill, a small amount of wasted text.

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?

There is no output schema, so the description carries the burden of explaining results and side effects, which it does not. Coordinate semantics are well covered, but for a geometry-creating mutation it omits return value, undo/reversibility, and interaction with existing fills.

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 baseline is 3, but the description adds genuinely new meaning the schema lacks: coordinates are in mil (0.001 inch), relative to canvas origin, +X rightward and +Y upward. That unit/frame clarification is directly needed to supply a correct polygon.

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 ('Create a fill region on the PCB'), which is clear on its own. However, it never distinguishes the tool from close siblings like pcb_create_pour or pcb_create_region, so an agent must guess which of the three creation tools to pick.

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 routes the agent to pcb_canvas_origin and pcb_convert_coordinates for the coordinate system, which is useful operational guidance. It gives no when/when-not advice relative to pcb_create_pour or pcb_create_region, so selection between the geometry-creation siblings 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 declare this as a non-read-only, non-idempotent, non-destructive write. The description adds the coordinate origin and unit semantics, which go beyond the annotations, but it says nothing about atomicity, repeat-invocation behavior (relevant given idempotentHint=false), or failure modes.

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?

Four sentences, all front-loaded with the action first and coordinate semantics second; each sentence carries information the schema lacks. No wasted filler, though it is slightly longer than strictly necessary.

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 no output schema, the description covers the highest-risk ambiguity (units and coordinate reference frame) and routes to helper tools. It is close to complete, missing only a note on return/failure behavior, which is minor given the annotation coverage.

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, but the description meaningfully adds unit and axis semantics (mil units, +X rightward, +Y upward, relative to canvas origin) that the terse schema ('X coordinate') does not convey. That extra meaning pushes it above 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?

States a specific verb+resource ('Create a standalone pad on the PCB'), and the word 'standalone' usefully hints this is a free pad rather than one owned by a footprint. It does not explicitly differentiate itself from creation siblings like pcb_create_via or pcb_create_track, so it falls just short of a 5.

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 genuine usage context by pointing to pcb_canvas_origin and pcb_convert_coordinates for handling the coordinate system, which is the main source of error here. However it offers no explicit when-to-use vs when-not guidance or alternatives for the creation act itself, leaving that implied.

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 this is a non-destructive, non-idempotent write operation, so the safety profile is covered. The description adds coordinate-frame and unit context but says nothing about side effects, whether existing geometry is replaced, or how net/layer assignment behaves on execution.

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?

Purpose is front-loaded in the first sentence, followed by tightly scoped unit/coordinate clarification and two tool cross-references. Every sentence carries information; only the coordinate-system detail is slightly verbose but still 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 write tool with no output schema, the description supplies the unit convention, coordinate frame, and pointers to origin/conversion helpers that an agent needs to build correct point arrays. It omits the semantics of net/layer assignment, but the schema documents those adequately.

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%, setting a baseline of 3, but the description adds meaning the schema lacks: coordinates and widths are in mil (1 mil = 0.001 inch), relative to the canvas origin with +X rightward and +Y upward. This is genuinely additive for the polygon and lineWidth parameters.

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: 'Create a multi-segment polyline track defined by a series of points.' The 'multi-segment polyline' qualifier implicitly distinguishes it from the sibling pcb_create_track, but it does not name that alternative explicitly.

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 useful context (coordinate system, units) and cross-references pcb_canvas_origin and pcb_convert_coordinates for coordinate handling. However, it never states when to choose this over pcb_create_track or other creation tools, leaving the primary routing decision 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 declare it is a non-read-only, non-idempotent, non-destructive mutation, so the safety bar is partly covered. The description adds genuinely non-obvious behavior: pours reflow against a stale design-rule snapshot until the PCB is reopened (issue #34) and pour rebuilds miss anti-pads for post-plane vias (issue #32). It does not state whether repeated calls create duplicate pours, which matters given idempotentHint=false.

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?

Purpose is front-loaded in the first sentence, followed by actionable bug caveats and unit conventions. It is somewhat long and splits the unit convention across two sentences (coordinates, then lengths), but every sentence carries information an agent would otherwise have to discover the hard way.

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 10-parameter mutation tool with no output schema, the description covers units, coordinate frame, known upstream pitfalls, and the helper tools for origin/conversion. Remaining gaps (no return-value note, no idempotency note) are minor given the fully documented schema and existing annotations.

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 would be 3, but the description adds real semantic value beyond the schema: coordinates are canvas coordinates in mil relative to the canvas origin, +X rightward and +Y upward, and lengths are also in mil. It also points to pcb_convert_coordinates for canvas/data conversion, which the schema does not mention.

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?

"Create a copper pour region on the PCB" gives a specific verb and resource, so the agent knows precisely what operation is performed. However, it never distinguishes this from close siblings like pcb_create_region or pcb_create_fill, which an agent could easily confuse with a pour.

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?

There is no explicit when-to-use or when-not guidance, and the near-siblings (pcb_create_region, pcb_create_fill) are not named as alternatives. It does provide operational guidance (reopen the document before rebuilding pours after rule changes) and routes the agent to pcb_canvas_origin / pcb_convert_coordinates for coordinates, so usage is implied but not delimited.

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 this is a non-idempotent, non-destructive write in a closed world. The description adds useful behavioral context about the coordinate space (canvas coordinates, +X right/+Y up, mil units) and auto-closing of polygons, but does not describe side effects like document auto-switching or failure modes beyond what annotations cover.

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, front-loaded with the purpose, then coordinate semantics, then helper-tool routing. Every sentence earns its place; the only mild cost is that the coordinate detail could be trimmed for brevity.

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 7-parameter, 3-required write tool with 100% schema coverage and no output schema, the description covers the highest-risk ambiguity (coordinate system and units) and points to companion tools. It omits return behavior and error handling, but annotations carry the safety profile, making this largely 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 baseline is 3, but the description genuinely adds meaning the schema lacks: the coordinate units (mil) and the canvas coordinate orientation for polygon points, plus that lengths such as lineWidth are also in mil. The schema only types these as bare numbers, so this compensates for the ambiguity.

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 (Create) and resource (design rule region) with a clarifying parenthetical '(keepout/constraint area)' that distinguishes it from copper-area siblings like pcb_create_pour and pcb_create_fill. It does not explicitly name or route away from those siblings, but the resource is specific enough to be actionable.

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 real coordinate-handling guidance by naming pcb_canvas_origin and pcb_convert_coordinates for origin management and coordinate conversion. However, it offers no when-to-use vs when-not guidance relative to the other pcb_create_* tools, so usage is only implied.

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=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered by structured data. The description adds the coordinate model (canvas-relative mil, +Y upward), which is helpful, but it does not disclose what happens on failure, whether re-issuing creates duplicates, or the auto document-switch side effect beyond what the schema states.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action in the first clause, then layers on coordinate conventions and cross-references. Every sentence carries information, though the coordinate-system detail is slightly dense for a single sentence.

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?

Covers purpose, coordinate semantics, and where to look for related operations, which is sufficient for a create tool with no output schema. Gaps are minor: no statement of the success response or the interaction between net/layer values and validation.

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, but the description meaningfully enriches the parameters by defining the coordinate units (mil = 0.001 inch), the axis orientation (+X right, +Y up), and that widths/diameters share the same unit — none of which is stated in the schema where coordinates are only labelled 'Start X coordinate'.

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 — 'Create a single track segment (line) between two points' — on a given layer and net. The word 'single' implicitly differentiates it from the sibling pcb_create_polyline_track, but that sibling is never named, so the distinction relies on inference.

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 useful how-to context (read the origin offset with pcb_canvas_origin, convert coordinates with pcb_convert_coordinates), which is real usage guidance for the coordinate model. However, it never states when to use this versus pcb_create_polyline_track, and gives no preconditions or exclusions.

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 only declare the basic mutation profile (readOnly=false, destructive=false, non-idempotent). The description adds far more: a known upstream bug (pro-api-sdk #32) causing missing anti-pads on non-matching nets, an unfixable-by-rebuild failure mode, a named DRC symptom, and an explicit fabrication risk warning. This is exactly the kind of behavior structured fields cannot 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 core action is front-loaded, followed by the critical warning, then coordinate semantics. Every sentence carries information, though the bug-warning block is dense and could be trimmed slightly without losing meaning.

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 creation tool with full annotation coverage, 100% schema coverage, and no output schema, the description supplies everything an agent needs: units, coordinate system, cross-referenced helper tools, and a critical safety caveat. 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 the baseline is 3, but the description goes beyond the terse schema labels by defining units (mil, 1 mil = 0.001 inch), the coordinate frame (canvas coordinates relative to origin), axis orientation (+X right, +Y up), and that lengths share the same unit. It does not clarify viaType options or the net/instance relationship.

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+resource ("Create a via") that is unambiguously distinct from sibling creators like pcb_create_track, pcb_create_pad, and pcb_create_pour. It does not explicitly name or contrast a sibling, so it stops short of a 5.

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?

Gives strong workflow context: regenerate the internal plane after placing vias, and do not ship until the DRC error clears. It also routes the agent to pcb_canvas_origin and pcb_convert_coordinates for related tasks, though it never states when to prefer this tool over a general primitive creator.

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 destructiveHint=true, so the description goes further and adds genuinely new behavioral context: there is no undo path, the whole document is snapshotted to the local backup repo beforehand, and the response carries the backup SHA for recovery. That is exactly the recovery/risk information an agent needs before a destructive call.

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 tight sentences: the action first, then the irreversibility constraint, then the mitigation. No filler, and the most decision-relevant information (no undo, but a backup exists) is 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?

For a destructive tool with no output schema, the description covers the essential risk profile, the safety net, and what the response returns (backup SHA). It stops short of clarifying behavior on nonexistent IDs or multi-document/instance edge cases, but nothing critical for a correct invocation 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 description coverage is 100%, so all four parameters (ids, type, document, instance_id) are already documented, including the enum for type and the instance_id auto-selection rule. The description only restates 'by type and IDs' and adds no format or constraint detail beyond the schema, so the baseline 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 gives a specific verb (Delete), resource (PCB primitives), and scope (one or more, by type and IDs), which cleanly separates it from read/modify siblings like pcb_modify_primitive and pcb_get_primitives_by_id. An agent can identify the operation 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?

It discloses the key operating condition (irreversible, no undo) but never states when to reach for this tool versus alternatives such as pcb_modify_primitive or the sch_delete_* siblings, nor any preconditions beyond what the schema already carries. Usage is implied by the verb rather than explicitly framed.

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 cover the safety profile (readOnly/idempotent/non-destructive), but the description adds substantial behavior beyond them: the exact return shape, the Base64-in-reply caveat, the fact that omitted `layers` exports all enabled copper including inner layers (contrasting EasyEDA's raw default), and the CAUTION that options keys cannot override routing fields.

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?

Long, but front-loaded with purpose and return shape, then organized into clear labeled sections (formats, WARNING, per-format options, CAUTION). The per-format option reference is dense but justified because the schema cannot express it; slightly heavy, keeping it from a 5.

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?

No output schema exists, yet the description states the return shape ({ fileName, data, size }). For a 16-format export tool with a free-form options object, it covers defaults, sub-formats, the disk-write alternative, and the DRC prerequisite — everything needed 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 schema documents the top-level params but leaves `options` as an empty free-form object (additionalProperties only), so the description carries the burden of documenting per-format option shapes (gerber, odbplus, pick_and_place, 3d, bom, dxf), unit value literals, and fileType sub-format values. This is meaning well 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?

Opens with a specific verb+resource ("Export the PCB design") and immediately scopes the output formats. It also implicitly distinguishes itself from the sibling pcb_export_to_file by noting that this one returns Base64 in the reply while the sibling writes to disk.

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 states prerequisites before fabrication output (run pcb_run_drc and sch_run_drc, resolve all violations, include connectivity checks) and names the alternative (pcb_export_to_file) with the condition that selects it (large gerber/3d outputs). Format-by-format guidance is given inline, so the agent knows which value to pick for which goal.

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 only the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds substantial behavior beyond them: the Base64-avoidance rationale, the exact return shape {saved, size, originalName, format}, the non-obvious default that omitting `layers` exports all enabled inner copper unlike EasyEDA's raw default, and a caution that options keys cannot override routing fields. 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?

Front-loaded with the routing decision and the DRC prerequisite before the format detail, and the return shape is stated compactly. It is long and repeats the 'see pcb_export' pointer twice, but nearly every sentence carries distinct information, so the length is largely earned.

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 6-param export tool with no output schema and a free-form options bag, the description supplies everything needed: prerequisites, return shape, per-format option contracts, default-selection behavior, and a routing caution. Nothing material is missing 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 coverage is 100% for named params, but the most complex parameter (`options`) is an empty additionalProperties object in the schema, so the description is the sole source of its semantics. It documents per-format option shapes for gerber, odbplus, pick_and_place, 3d, bom, and dxf, specifies unit values as literal strings, and states default behavior — far beyond what the schema conveys.

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+resource+destination ('Export the PCB design ... directly to a local file path') and explicitly distinguishes itself from the sibling pcb_export by naming the condition that selects it (large outputs). An agent can route between the two tools without opening either 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?

Gives explicit when-to-use ('preferred over pcb_export when the output is large — gerber/odbplus zips, 3d STEP, pdf') and a hard precondition ('BEFORE generating any fabrication output: run pcb_run_drc (and sch_run_drc) and resolve all violations', plus 'Clearance DRC alone is not sufficient'). Alternatives and exclusions are both named.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond that — no mention of scope (all nets vs. filtered), return format, or pagination.

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 front-loaded sentence with no waste. It is arguably too terse rather than padded, so it earns credit for efficiency but not maximum marks.

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 list tool with an output schema absent, the definition is minimally adequate but silent on what the returned net-name list looks like (array of strings? objects?) and whether it is scoped to the target document. A sentence on scope would close the 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 description coverage is 100%, and the schema itself explains document UUID auto-switching and instance_id auto-selection in detail. The description contributes nothing about parameters, 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?

States a specific verb+resource: retrieving all net names from the PCB design. An agent can distinguish this from pcb_get_net_primitives, pcb_get_net_rules, and pcb_get_net_length, though the description never explicitly contrasts with those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as pcb_get_net_primitives or pcb_get_net_length. The agent must infer usage from the name alone.

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 cover readOnly, idempotent, non-destructive, and closed-world traits, so the safety profile is set. The description adds return-shape context absent any output schema by enumerating the fields returned for component, track, via, and pad primitives, which is genuine value. It stops short of covering polyline/arc/pour/fill/region fields and says nothing about ordering or result size.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose before expanding into the type/filter matrix and field lists. The dense field enumeration is justified by the absence of an output schema, though listing fields for only some primitive types leaves the block slightly lopsided rather than wasteful.

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 9-param query tool with no output schema but full annotation coverage, the description supplies the filter-by-type semantics and partial return-field detail an agent needs. Remaining gaps (fields for the non-enumerated primitive types, pagination/truncation behavior) are modest against what the schema and annotations already provide.

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% (baseline 3), but the description goes beyond the schema by mapping which filters are meaningful per primitive type (component→layer, track→net/layer, via→net, etc.), adding real selection guidance. The per-type field lists further clarify what 'fields' projection can target.

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 ('Get') and resource ('all primitives of a specific type on the PCB') with the scoping qualifier that it is type-driven with optional filters. This implicitly distinguishes it from point-based (pcb_get_primitive_at_point), region-based (pcb_get_primitives_in_region), id-based, and net-based siblings, but it never names an alternative to make the routing explicit.

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 is implied via the type/filter mapping (e.g., via filters by net, pad by layer/net), which helps the agent pick the right call. However, there is no explicit when-to-use/when-not guidance and no mention of the sibling query tools it competes with, so selection still requires 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond them by disclosing an upstream EDA bug (padNumber reads null for API-placed components until doc reopen), which materially affects how an agent interprets results.

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 front-loaded sentences with zero filler: purpose first, return shape second, caveat last. The caveat is longer but is the kind of detail that prevents a wrong conclusion, so it earns its space.

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 explicit field list is a valuable substitute for return-value documentation, and the SDK bug note covers a real edge case. Only the missing when-to-use/alternative guidance keeps it short of complete for a 6-parameter tool with nested objects.

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 document, instance_id, limit, filter and fields are fully documented in the schema. The description only restates the primitiveId input and then lists RETURN fields (primitiveId, padNumber, net, layer, x, y), which are not parameters, so it adds no parameter meaning beyond the schema 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?

States a specific verb and resource ('Get all pins/pads of a specific component') plus the identifying key ('by its primitive ID'), so an agent knows exactly what is returned. It never names a sibling (e.g. sch_get_component_pins for the schematic side, or pcb_get_primitives_by_id), leaving the PCB-vs-schematic routing to inference from the tool name.

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 is only implied: you call it when you have a component primitive ID and want its pads. There is no explicit when-to-use, no when-not-to-use, and no pointer to the schematic or generic-primitive alternatives that appear in the sibling list.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond that — nothing about scope, permissions, or return shape — so it neither strengthens nor contradicts the 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?

A single front-loaded sentence with the verb and resource first and a parenthetical example set that earns its place. No waste.

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 full schema coverage and no output schema, this is close to sufficient. The only mild gap is that "(clearance, width, etc.)" is vague about what the returned rule configuration actually contains, but no safety or routing information an agent needs 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 description coverage is 100%, so the document and instance_id parameters are already fully documented in the schema. The description adds no syntax, format, or selection meaning for either parameter, which is the expected baseline when the schema does the work.

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 clear verb+resource ("Get the current PCB design rule configuration") and illustrates the content with examples (clearance, width). It does not, however, differentiate itself from the nearby siblings pcb_get_net_rules or pcb_manage_rule_config, so an agent cannot tell which rules tool to reach for from the text alone.

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?

There is no when-to-use guidance, no exclusions, and no named alternative despite multiple overlapping siblings (pcb_get_net_rules for net-specific rules, pcb_manage_* for modification). The description offers implied usage only via its content examples.

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 full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the behavioral burden is light. The description contributes only the word 'routed,' which distinguishes from logical/manhattan length, but adds nothing about units, layer scope, or whether unrouted connections count.

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 front-loaded sentence with zero waste and no filler. It is appropriately sized for the operation, though it is terse enough that a small clarifying clause (e.g., units) could have been added without bloat.

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 tool with full schema coverage and annotations carrying the safety profile, only purpose needs stating, and it is stated. Remaining gaps are minor but real: no indication of units or whether the figure spans all copper layers versus a specific one.

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 each parameter (net, document, instance_id) is well documented in the schema itself, including how to obtain the document UUID and when instance_id is required. The description adds no parameter-level meaning, 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?

Names a specific verb (Get) and resource (total routed length of a net), which clearly distinguishes it from generic net readers like pcb_get_all_nets or pcb_get_net_primitives by indicating the returned metric. It does not, however, explicitly contrast itself with those siblings.

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 is implied: an agent can infer it should call this when a net's routed length is needed. There is no explicit when-to-use guidance, no exclusions, and no pointer to alternatives such as pcb_get_net_rules or pcb_get_net_primitives.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that (no note on result size, truncation via limit, or document auto-switching behavior, all of which live in the schema). Consistent with annotations but adds little.

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 well-formed sentence with the scope qualifier front-loaded. Nothing padded, nothing wasted.

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 7-parameter read tool with a nested filter object and no output schema, the description is minimally adequate. The rich schema and annotations cover the mechanical details, but the description could have warned about response size or pointed to sibling retrieval modes, which it does not.

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 every parameter is already documented, and the description's only contribution is the example list of primitive types (tracks, pads, vias), which loosely maps to the 'types' filter. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (Get) and resource (primitives) and scopes it to 'belonging to a specific net', which cleanly separates it from siblings like pcb_get_all_primitives, pcb_get_primitives_in_region, and pcb_get_primitives_by_id. It gives the reader enough to know what comes back, though it never names those alternatives explicitly.

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?

There is no when-to-use guidance, no prerequisites, and no mention of the sibling tools that retrieve primitives by other criteria. The agent must infer from the scope phrase alone that this is the net-scoped variant of the family.

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, idempotentHint and destructiveHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that: no scope of rules returned, no indication of whether rules come from the active document or the netlist, no relationship to the manage_* rule tools.

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 four-word sentence with no filler and the action front-loaded. It is efficient, though it borders on under-specification rather than optimal conciseness.

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 rules-retrieval tool surrounded by several near-identical rule siblings and with no output schema, the description does not say what the returned rules look like or how they relate to design rules versus net classes. The agent is left to guess at the tool's exact role.

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 document and instance_id parameters are fully documented in the schema, including UUID sourcing and multi-instance behavior. The description contributes no additional parameter meaning, so the baseline 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 ("Get net-specific design rules"), so an agent knows it retrieves per-net rule data. However, it does not distinguish itself from the close siblings pcb_get_design_rules and pcb_manage_net_rules, leaving ambiguity about which one to pick.

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?

There is no guidance on when to use this instead of pcb_get_design_rules (global rules) or pcb_manage_net_rules (rule mutation). The agent must infer the distinction from the name alone, with no stated prerequisites or exclusions.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context on the coordinate system and units, but says nothing about what happens when no primitive exists at the point, which primitive wins if several overlap, or what the call returns (no output schema).

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 tight sentences, purpose front-loaded, followed by the unit/orientation contract and then related-tool pointers. No filler, though the coordinate-convention block is somewhat dense relative to the core operation.

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 coordinate and unit semantics are fully covered, and the document/instance_id parameters are documented in the schema. What is missing is the return contract: with no output schema, the description should say what is returned (and what happens on a miss), which is the main remaining gap for a point-query 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 baseline is 3; the description goes beyond the schema's bare 'X coordinate'/'Y coordinate' by specifying units (mil, 1 mil = 0.001 inch) and axis orientation (+X rightward, +Y upward). This resolves a real ambiguity an agent would otherwise guess at.

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 (Get) and resource (primitive) with a precise spatial scope (at a specific point on the PCB), which inherently separates it from pcb_get_all_primitives, pcb_get_primitives_by_id, and pcb_get_primitives_in_region. It does not, however, explicitly name or contrast any sibling, so an agent must infer the boundary.

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 is implied by the coordinate explanation: you call this when you have a PCB canvas point. The only routing guidance given is for coordinate handling (pcb_canvas_origin, pcb_convert_coordinates), not for choosing this tool over the other primitive-retrieval siblings.

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 this as a read-only, idempotent, non-destructive operation. The description adds no behavioral context beyond the basic retrieval action and batch cardinality ('one or more'), and does not mention response size, filtering behavior, or document/instance targeting.

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 front-loaded sentence with no filler. It states the action, resource, and retrieval key directly.

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 is rich and fully described, and annotations cover the safety profile, so the terse description is largely sufficient for invoking the tool. It does not explain return shape, but the tool name and 'Get ... primitives' phrasing make the retrieval outcome reasonably clear, 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?

Schema description coverage is 100%, so the schema already documents all seven parameters, including type, primitiveIds, document, limit, fields, filter, and instance_id. The description only references type and primitive ID(s) at a high level and adds no syntax or format detail 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 ('Get') and resource ('PCB primitives') and narrows scope to retrieval by type and primitive ID(s). It is clear enough to distinguish from retrieval-by-region or retrieval-at-point siblings, though it does not explicitly name any alternative.

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 is implied by 'by their type and primitive ID(s)': the agent should use this when it already knows the primitive type and ID(s). However, there is no explicit when-to-use guidance, no exclusions, and no named alternatives such as pcb_get_all_primitives or pcb_get_primitives_in_region.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the coordinate frame (mil, relative to canvas origin, +X right / +Y up), but says nothing about what counts as a 'primitive' in the result, truncation behavior via limit, or response size, which are real behavioral concerns for this tool.

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 tight sentences: purpose first, then the coordinate semantics that most affect correct invocation, then the cross-references. No filler or restatement of the tool name.

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 10-parameter, no-output-schema tool, the description covers the coordinate model and related tools well, and the schema's fields/filter/limit descriptions carry the projection and truncation warnings. It stops short of defining the returned primitive set or the return shape, which the absent output schema leaves partially to 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 meaning the schema lacks: the unit (mil, 1 mil = 0.001 inch) and the coordinate frame/orientation for left/right/top/bottom, which the schema only labels as 'Left boundary X' etc. That materially reduces ambiguity about how to supply the boundary values.

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 (get) and resource (primitives) with an explicit scope qualifier ('within a rectangular region'), which is exactly what separates it from pcb_get_all_primitives and pcb_get_primitive_at_point. An agent can pick the right tool without opening a 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?

Usage is implied by the region scope, and it helpfully points to pcb_canvas_origin and pcb_convert_coordinates for coordinate handling. However, it never states when to prefer this over the sibling queries or any preconditions (e.g. requiring a document/instance context, or cost of wide regions).

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, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered and the bar is low. The description adds only the mild context that results are state-dependent (they track the live selection), and says nothing about empty-selection behavior or result size.

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 front-loaded sentence with no filler; the core noun phrase 'currently selected primitives' arrives immediately. Nothing in it is redundant for a tool of this shape.

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 five parameters, nested filter objects and no output schema, the definition leaves gaps: what counts as a 'primitive', what happens when nothing is selected, and how the returned array is shaped are all unstated. Annotations cover the safety side, but the retrieval contract is thin.

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% – document, instance_id, limit, fields and filter are all documented in the schema, including the strong warning to always supply 'fields'. The description contributes nothing beyond that, 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?

States a specific verb ('Get') and resource ('currently selected primitives in the PCB editor'), so the retrieval semantics are clear. It implicitly separates itself from pcb_get_all_primitives and pcb_get_primitives_in_region by the word 'selected', but it never names those siblings or makes the contrast explicit.

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 phrase 'currently selected' implies the prerequisite (something must be selected in the editor), but the description never states that, nor does it point to alternatives like pcb_clear_selection or the region/point-based getters. Usage is only weakly implied.

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 safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description only needs to add context. It adds nothing: there is no statement about whether the highlight replaces an existing one, whether it persists across operations, or how it relates to selection state. readOnlyHint=false is also left unexplained for an ostensibly visual operation.

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 front-loaded sentence with zero filler; the action and its scope arrive immediately. Nothing is wasted, though brevity here comes at the cost of the missing guidance noted elsewhere.

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 non-destructive PCB operation with a fully documented schema and clear annotations, the description is nearly sufficient. The gap is the unresolved overlap with pcb_select_net, which the agent must resolve to invoke the right tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.