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

Annotations already cover the safety profile (read-only, idempotent, closed-world), and the description adds substantial context beyond them: grouping rules, component_notes behavior, the pattern of error responses listing candidate prefixes and all-DNS prefixes. One flaw: it says to "pass include_dns=true to list them," while the schema declares include_dns defaults to true, leaving the actual default behavior ambiguous.

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?

Dense but front-loaded: the matching rule comes first, then grouping, then edge-case/error behavior. A couple of clauses restate the same idea ("every field a group reports is true of every part in it"), so it is slightly longer than strictly needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry return-shape burden, and it does explain grouping and the note-bearing empty result. The remaining gap is the include_dns default discrepancy, which could lead an agent to expect an empty list where DNS parts are actually returned.

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 four parameters (baseline 3). The description still adds real semantic value for `type`: whole-word and case-insensitive matching, and that partial prefixes return nothing rather than a superset.

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 ("List components") plus the scoping dimension (component type/refdes prefix in a design). The whole-word, case-insensitive prefix rule effectively separates it from the search_components_by_* siblings, which do fuzzy/partial matching.

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 operative guidance: request the full prefix, and if an expected part is missing, look under its own prefix. It also explains the include_dns conditional. It stops short of naming sibling tools (e.g. search_components_by_refdes) as alternatives for partial matches, so it earns a 4 rather than 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 establish a safe read-only, idempotent, closed-world profile, and the description goes well beyond them: blank/omitted path falls back to the server working directory (with `root` naming what was actually searched), misspelled arguments are refused by name, and truncation by max_results is surfaced in `notes`. It also discloses the per-format read strategy (Cadence queries the .DSN; KiCad reads a committed .net, else schematics directly with no KiCad install, with kicad-cli as last resort) and that unreadable designs return `error` plus `unsupported: true`.

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 correctly: the returned path and the filesystem-search alternative come first, then path fallback, then the format-specific caveats. It is dense but a few sentences drift toward downstream query behavior (Cadence CIS stuffing, KiCad fallback chain) that is closer to the query tools' concern than to listing, costing some tightness.

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, but the description still names the fields an agent will encounter: `root`, `notes`, `design_variants`, `error`, and `unsupported`. With 0 required params, 100% schema coverage, and four documented annotations, nothing an agent needs in order to call this correctly or interpret the result 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 still adds real meaning for two of the four parameters: `path` being optional and what blank means, and `max_results` truncation being reported in `notes` rather than silently dropping results. `pattern` and `max_depth` are only covered by the schema, so it stops short of a 5.

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 ('List the design projects in a directory') and enumerates exactly which file types count as a design (.DSN, .PrjPcb, .kicad_pro, .netlist.json), so an agent knows what will be returned. It also names the sibling relationship explicitly: the produced path is 'what every other tool takes', which separates it from the query siblings like list_nets or query_component.

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

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

Explicit routing guidance: 'use this tool instead of searching the filesystem' gives a concrete when-to-use and a when-not-to-use in one clause. It adds exclusions for the unsupported case ('every query on it returns that error, so do not query it') and states that a design with variants requires design_variant on every subsequent query, which pre-empts a common mis-call.

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 read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds two genuinely useful behavioral traits beyond that: alphabetical sort order and the possibility of a large result set. It stops short of noting the design_variant requirement, but that lives 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?

Three short sentences, front-loaded with what the tool does, then the volume caveat, then the routing hint. No filler; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read tool with full annotation and schema coverage, the description covers what is returned (net names, sorted) and how big it may be. No output schema exists, but the returned shape is still adequately conveyed; only the variant-selection prerequisite is missing from prose.

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

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

Schema coverage is 100%, and the schema's design_variant description is unusually thorough (including the <Default> alias), so the schema carries the burden. The description adds no parameter-level meaning beyond what is already documented — baseline 3.

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 (list all net names in a design), plus output ordering, and explicitly distinguishes itself from the sibling search_nets. An agent can pick between list_nets and search_nets 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?

Names the alternative (search_nets) and the condition that selects it ('for targeted queries'), with the implication that this tool is for full enumeration. The volume warning ('result can be large') reinforces when not to reach for it.

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 (which already declare readOnly, idempotent, non-destructive), the description discloses concrete return shape, the two pin representation forms, the special 'NC' sentinel that is a marker rather than a queryable net, case-insensitive lookup semantics, and that errors carry guidance and suggestions. That is exactly the context 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 progressively finer detail that each serves a purpose: the pin representation rules and NC sentinel are essential with no output schema, and the fallback guidance closes the loop. Dense but no filler sentences; a small readability cost from packing multiple rules into one run of prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must describe return values and it does so thoroughly, including the ambiguous pin-value cases an agent would otherwise mis-handle. Combined with the sibling fallback and error behavior, nothing needed to call and interpret this tool 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 all three parameters including design_variant's variant-vs-default rule are already documented. The description nonetheless adds semantics the schema lacks: refdes lookup is case-insensitive. That is real added meaning, though it covers only one of the three 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 ('Get full component details including all pin connections') and immediately scopes the content returned: MPN, description, value, pin-to-net mappings. It also names the sibling search_components_by_refdes for the not-found case, so the agent can distinguish lookup-by-known-refdes from search-by-unknown-refdes.

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 clearly implied (you already have a refdes and want full detail) and the failure path is explicitly routed: 'If the refdes is not found, search_components_by_refdes finds it.' It stops short of explicitly contrasting with list_components or search_components_by_description for the discovery case, so the when-not guidance is partial rather than complete.

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

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

Even with readOnly/idempotent annotations already covering safety, the description adds substantial behavioral context: traversal through series passives, stopping at power/ground nets by name or pin count, handling of non-standard rails like VDIO_LMS, skip_types effects, ground-net rejection, whitespace/31-character name matching, notes, and component_notes. This is exactly the kind of execution behavior an agent needs beyond the annotations.

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

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

The description is front-loaded with the core purpose and then packs in relevant edge cases. It is dense and longer than typical, but nearly every sentence provides operational value for a complex trace tool; minor structural improvement could come from separating traversal and naming rules, but it is not 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?

Although there is no output schema, the description names returned concepts such as circuit_hash, visited_nets, notes, and component_notes, and explains major error and edge-case behavior. For a complex 5-parameter trace tool with annotations covering safety, this is complete enough for an agent to 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains net_name matching fallback behavior and the effect of skip_types (e.g. ['C','L','R'] removes all three series passives). It does not explain include_dns or design_variant beyond the schema, but the added parameter context is substantial.

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 full XNET connectivity for a named net, tracing through series components to return the whole electrical node. It clearly distinguishes the result from a plain net query by explaining circuit_hash and the traversal scope, so an agent can identify this as the XNET-by-net tool rather than a generic net listing/search.

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 clear usage context: use it for full XNET connectivity, it rejects ground nets, and if the net is not found use search_nets. It does not explicitly compare against the sibling query_xnet_by_pin_name, but the 'by net name' scope and the search_nets fallback provide strong guidance for when to invoke it.

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, and the description adds substantial behavior beyond them: traversal rules (stops at power/ground by name pattern or >40 pins), what happens with rails named outside the pattern, NC handling for unconnected pins, and the ground-pin rejection error. This is exactly the kind of context 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?

Front-loaded with purpose and format, then behavior. Dense but nearly every clause carries information; the parenthetical rail-name list and trailing notes are slightly crowded but not 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?

With no output schema, the description correctly explains return contents (whole electrical node, circuit_hash, visited_nets, component_notes, empty result for NC). Gaps remain around include_dns and design_variant behavior, which an agent must infer from schema text alone.

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 goes further by explaining skip_types semantics with a concrete example (skip_types=['C','L','R'] leaves series passives out) and by describing pin_name's NC edge case. design_variant and include_dns are left entirely to the schema, keeping it from a 5.

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 with an explicit entry point: 'Get full XNET connectivity starting from a component pin, named REFDES.PIN'. The 'starting from a pin' framing implicitly distinguishes it from query_xnet_by_net_name, and the format example removes ambiguity about the input.

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?

Clear context for use: starting from a pin rather than a net, with skip_types for excluding series passives and a note that ground-connected pins are rejected. It does not explicitly name query_xnet_by_net_name or search_nets as alternatives, so routing 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?

Goes well beyond the readOnly/idempotent annotations: full output never truncated, findings grouped by severity then rule id, keys are `REFDES.PIN` arrays, `checked` versus `skipped` semantics, and an explicit non-coverage caveat that unconnected pins without a no-connect symbol are not checked. That limitation is exactly the kind of trait an agent cannot infer from 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?

Front-loaded with purpose and output shape before the rule catalog, and every rule entry carries its severity and meaning rather than being a bare id list. The rule enumeration is long and dense, but each item is load-bearing; it stops just short of maximal tightness.

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, and the description compensates fully by describing the returned `errors`/`warnings` grouping, the endpoint keying, and the `checked`/`skipped` fields. For a read-only single-design check with 5 params, nothing needed to call or interpret 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 coverage is 100%, so the baseline is 3; the description earns extra by explaining that rule ids drive `include_rules`/`exclude_rules` and that a bad id hard-errors, plus that `include_dns` controls whether DNS parts are counted. It adds nothing for `design_variant`, which is left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run electrical rule checks (ERC) on a design's netlist') plus the shape of what comes back. It is unmistakably different from every sibling, which are all list/search/query tools; this is the only validation tool in the set.

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 concrete operating guidance: use `include_rules`/`exclude_rules` to scope, `include_dns` to count Do-Not-Stuff parts, and an unknown rule id errors rather than silently checking nothing. It does not state when to prefer this over inspecting nets via list_nets/search_nets, so it stops short of full when-not/alternative coverage.

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 read-only/idempotent safety profile, and the description adds real behavioral context beyond them: a data-availability caveat, an explicit error condition ('rejects patterns that match all items'), and the domain quirk that `component_notes` names parts lacking an MPN. It stops short of describing the result shape, 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?

Four short sentences, purpose first, then caveats and alternatives — nothing is padding. The `component_notes` clause is a little cryptic out of context (it reads like a field name with no explanation of where it appears), costing a bit of clarity.

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 four-parameter, two-required search with no output schema, the description covers the fallback path, the failure mode, and one domain nuance, which is close to sufficient. The main remaining gap is that return contents are only obliquely referenced via `component_notes` and otherwise undocumented.

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

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

Schema coverage is 100%, so all four parameters are already documented in structured fields, making 3 the baseline. The description goes slightly beyond by warning that overly broad `pattern` values are rejected, which tells the agent how to shape that argument rather than just its type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Search for components by description pattern') and immediately differentiates itself from the refdes/mpn siblings by naming them as fallbacks. An agent can tell which of the three component-search tools applies 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 an explicit precondition (not all netlists carry description data) plus named alternatives for that case (search_components_by_refdes, search_components_by_mpn, asking the user for a BOM), and routes full-result needs to list_components. Both when-to-use and when-not-to-use are 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description adds genuinely new behavior: MPN data may be absent, `component_notes` enumerates parts lacking an MPN, and broad match-all patterns are rejected. It stops short of describing result ordering or how many matches are typical, so not 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?

Four short sentences, each carrying distinct load: purpose, data-availability caveat plus fallbacks, a diagnostic field, and a failure-mode guard. Purpose and fallback path are front-loaded with 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?

Covers the failure modes that matter most for this tool (missing MPN data, over-broad pattern rejection) and the escape hatch, which is sufficient given 100% schema coverage and a simple read-only shape. Return shape is unspecified but no output schema exists, so a small gap remains.

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 `pattern`, `design`, `include_dns`, and `design_variant` are already documented. The description restates that `pattern` targets MPN but adds no syntax, anchoring, or matching-semantics detail beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search for components by MPN pattern') and immediately names the distinguishing axis versus siblings search_components_by_refdes and search_components_by_description. An agent can route correctly 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?

Explicit when-to-use ('by MPN pattern'), when-not (netlists without MPN data), concrete alternatives (refdes, description search, ask user for a BOM), and a full-listing alternative (list_components). This is the strongest form of routing guidance.

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

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

Beyond the readOnly/idempotent annotations, it discloses that identical components are grouped on MPN, description, comment and value together with the invariant that every reported field is true of every part. It also explains component_notes for MPN-less parts and a notes field on zero matches – substantive behavior an agent could not infer.

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?

Five short sentences, front-loaded with purpose and the key grouping behavior, then edge cases. No filler; each sentence adds a distinct fact.

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 explains the grouped return shape, the component_notes field, and the zero-match notes field, so an agent knows what comes back. Complete for a read-only search 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, and the description adds matching semantics ('case-insensitive') that inform how the pattern parameter behaves. The design/design_variant/include_dns parameters get their meaning from the schema alone, so no full compensation is needed.

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 ('Search for components by refdes pattern') and differentiates from siblings search_components_by_mpn and search_components_by_description via the refdes key. An agent can select 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?

Explicitly redirects to list_components for full results and states that match-all patterns are rejected, giving a clear when-not condition. It does not explicitly contrast with the mpn/description search siblings, though their names largely carry that, keeping this just 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?

Goes well beyond the readOnly/idempotent annotations: discloses case-insensitivity, result ordering and keying, the notes field on zero matches, whitespace-trimmed matching, and that match-all patterns are rejected. These are exactly the behaviors an agent needs to predict outcomes.

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 purpose, then progressively deeper caveats. Slightly long, but every sentence (prefixing, trimming, match-all rejection) conveys a distinct behavior rather than restating the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by describing the return shape (sorted, keyed by design name, notes on empty). Combined with full schema coverage on the three parameters, an agent has what it needs 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics for the pattern parameter: case-insensitivity, trim behavior, and the hierarchical sheet-path prefixing that changes how patterns must be written. The design and design_variant parameters are left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search for nets matching a regex pattern') and immediately establishes the matching model. It is clearly distinguishable from list_nets, which is named as the unfiltered 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?

Explicitly routes the agent: use list_nets for full results when a pattern would match everything, prefer unanchored patterns over anchored ones for hierarchical nets. It gives both the when and the when-not with concrete examples.

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