MagicON RF Design Engines

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it reports every unsupported figure and every claim the results contradict, returns them in `findings` with a `why` reason, and offers four remediation patterns. It stops short of describing ordering, counts, or empty-result behavior.

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

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

Front-loads the core action and return shape, then the usage trigger, then the remediation guidance. Every sentence carries content, though the closing enumeration of fix strategies is slightly long relative to the rest.

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 carries the burden of explaining returns and does so: it names the `findings` collection and its `why` field and characterizes what lands there. For a single-parameter, read-only check, nothing 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 coverage is 100% for the single `text` parameter and the schema already says to pass verbatim prose including tables and captions. The description reinforces 'verbatim' but adds no format or syntax 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?

States a precise verb+resource: check a draft passage against engine results from THIS session. The scope qualifier ('THIS session') and the negative framing ('computes nothing, adds no evidence') clearly separate it from the compute siblings like run_link_budget and run_thermal_analysis.

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 trigger ('Run it before publishing or handing over a report, fabrication sheet, BOM summary or any other figure-bearing deliverable built from these tools') and implicitly rules out using it as a compute tool by stating it computes nothing. An agent knows exactly when to reach for this versus a solver.

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

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

With readOnlyHint=true already covering safety, the description adds real behavioral context: it discloses the multi-step pipeline, the cost/size/performance scoring axes, the Pareto-frontier return, and the backing engine/endpoint. It does not explain the apparent tension between readOnly and 'designs/generates' operations, but the annotation's safety signal is not contradicted.

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

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

A single dense sentence, but it is front-loaded with the core purpose and every clause (pipeline stages, scoring axes, return shape, engine reference, invocation hint) earns its place. Slightly long but not 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, and the description compensates by describing the return (ranked list with a Pareto frontier). For a 6-param all-optional tool it is nearly complete, missing only a note on what happens without a prior design.

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 six parameters are already documented, including their defaults and reuse semantics. The description adds only the no-argument invocation hint, so the 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+resource ('Multi-objective RF chain comparison') and enumerates the full behavior chain: designs the primary chain, generates alternatives, scores on cost/size/performance, returns a ranked Pareto list. This clearly distinguishes it from sibling design_rf_chain, which designs a single chain.

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 trigger ('Call with no arguments after a chain design to compare that design') and a prerequisite (a prior chain design). It does not name a sibling alternative or state a when-not condition, so it stops short of the top band.

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 readOnlyHint=true, but the description says the designed gain is auto-applied to the chain's antennaGainDbi unless apply_gain=false — a state mutation. That directly contradicts the read-only annotation. The description is otherwise candid about side effects, but the conflict with the annotation triggers a 1 under the rubric.

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

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

A single dense paragraph that front-loads what is designed, then the model, then the default behaviors and return contents. Every clause carries information, though the substrate/gain sentences could be broken out for faster scanning.

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 14-parameter tool with no output schema, the description covers the substrate sourcing logic, the array conditional, the auto-apply side effect, and enumerates return contents (dimensions, resonance/bandwidth/gain, beamwidths, pattern cuts, grating-lobe check). Remaining parameter specifics are fully covered by 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 already 100%, so the baseline is 3, but the description adds real meaning: the substrate defaulting rule, the array-vs-single conditional on nx/ny, and the note that omitting user_request labels results 'caller-asserted'. The material-resolution guidance is also reinforced rather than merely restated.

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 (design a rectangular microstrip patch antenna / planar array), names the underlying model (Balanis cavity + array factor), and ties itself to a concrete endpoint and UI panel. An agent can distinguish it from design_rf_chain or run_stackup_solver 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?

Gives clear conditions: array mode triggers only when both nx and ny are supplied, and substrate values derive from the latest solved stackup unless dk/df/h_mm are given explicitly. It does not, however, name when to prefer a sibling tool (e.g. design_rf_chain vs this) or state 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 readOnlyHint and openWorldHint false, so the description carries the real burden and delivers: it discloses the extraction/insertion behavior (pre-driver or attenuator inserted to hit target power), the default source assumption, and a non-obvious reporting rule that when pricingCoverage is 'partial', total_usd is a subtotal of pricedLines and must not be called the total. That is substantive behavioral context 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?

Front-loaded with the design action and its outputs before the caveat and the sibling routing. The first sentence is dense with stacked parentheticals, which slightly taxes readability, but every sentence carries non-redundant information.

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

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

With 19 parameters, no output schema, and a complex orchestration task, the description still tells the agent what comes back (BOM plus convergence summary including achieved vs target output) and how to interpret partial pricing. Nothing needed to call the tool correctly appears to be 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 schema already documents all 19 parameters in detail, including defaults and 'only when stated' constraints. The description adds an implicit default for the signal source but no parameter-level syntax or value guidance beyond what the schema provides, so the 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 ('Design a complete RF transmitter chain') and enumerates the concrete stages it resolves (driver, PA, filter, connector) plus what it returns (BOM and convergence summary). It also names the two sibling tools it is not (design_rf_receiver, design_tr_module), so an agent can disambiguate 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?

Explicitly routes to alternatives: 'For a receiver, use design_rf_receiver instead. For a module that shares one antenna between transmit and receive, use design_tr_module instead.' It also states an implicit default behavior (signal source is the user's input power; no VCO unless explicitly the generator), covering the when-to-use decision fully.

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 readOnlyHint and openWorldHint; the description adds far more — the full result surface (frequency plan with image/half-IF/LO leakage, cascaded NF, noise floor, MDS, sensitivity, SFDR, ADC interface), plus disclosure behavior when inputs are omitted ('reported as unavailable rather than assumed', 'labelled caller-asserted'). It also warns that a stage built from memory is discouraged and that an omitted nfSideband produces an ambiguity warning, which is genuine behavioral context beyond 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 purpose, then outputs, then parameter routing, then sibling routing — a logical progression with zero filler. Despite being several sentences, each one carries distinct information the agent needs to call the tool correctly.

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 13-parameter tool with nested stage objects and no output schema, the description compensates by describing the returned quantities in detail and by stating what is withheld when optional inputs are missing. It also flags the no-BOM limitation for main_board_input_voltage, covering the full decision surface.

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. The description adds routing semantics the schema cannot: which of rfFrequencyHz vs stages[] to use and under what user-story condition, plus the note that bandwidthHz gates noise floor/MDS/sensitivity. It stops short of explaining the remaining numeric conventions, which the schema already handles.

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 ('Design or analyse a superheterodyne RECEIVER') and immediately enumerates what it selects (limiter, LNA, image filter, mixer, LO, IF filter, IF amp, step attenuator) and what it returns. It explicitly distinguishes itself from design_rf_chain (transmitter) and design_tr_module (shared antenna), so an agent can route 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 decision rule for the two primary modes ('pass rfFrequencyHz to design one; pass stages[] only for a bench receiver the user described with their own numbers') and names two alternatives with the conditions that select them. No exclusions are 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 declare readOnlyHint=true and openWorldHint=false, consistent with a design/compute tool. Beyond that, the description discloses refusal behavior ('any other pairing is refused'), defaults-vs-withholding semantics ('the switching/blanking budget is absent, not assumed'), and scoring fallbacks, which are genuine behavioral facts the annotations cannot carry.

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 paragraph is dense but front-loaded: purpose and the two usage paths come first, safety budgets next, alternatives last. Every sentence earns its place, though the run-on enumeration of budgets and the very long single paragraph slightly reduce scannability.

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 26-parameter tool with no output schema and no formally required parameters, the description supplies what an agent needs: the two invocation modes, the design outcome (four safety budgets), what is withheld when inputs are omitted, and refusal conditions. 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 schema already documents each of the 26 parameters, making 3 the baseline. The description still adds cross-parameter routing logic the schema cannot express: which inputs select the design path vs. the explicit-inputs path, and that omitted inputs are withheld rather than defaulted. That is meaningful added meaning, though most per-parameter detail remains in the schema.

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

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

States a specific verb+resource ('Design a T/R (transmit/receive) module that shares ONE antenna'), names the shared-antenna front-end choices, and enumerates the four safety budgets returned. It explicitly contrasts itself with design_rf_chain (transmitter alone) and design_rf_receiver (receiver alone), so 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?

Gives explicit when-to-use routing: 'Pass frequencyGhz and targetOutputPowerDbm to design one; pass txPeakPowerDbm and isolationDb only to check a front end the user already described with their own numbers.' It also names the alternatives (design_rf_chain, design_rf_receiver) and their selection condition, leaving nothing 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?

Goes well past the readOnly/openWorld annotations: it discloses result ordering ('best first on the first limit'), how parts missing a limited figure are handled (named as not compared, never counted as matches), the refusal behavior for untraceable figures, and the 'caller-asserted' labelling that results receive when user_request is omitted. This is substantive behavioral context an agent cannot get from 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 purpose and criteria, then behavior, then the constraint on inputs — a sensible order. The single dense paragraph repeats the 'only stated figures' rule that the schema already carries per-parameter, which is mild redundancy rather than 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?

With no output schema, the description carries the return-value burden and does so: matching parts, best-first ordering, headline figures with datasheet pages, and the treatment of non-compared parts. Combined with full schema coverage and readOnly annotations, 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 coverage is 100%, so the schema already documents every parameter including the 'only a limit your user stated' phrasing. The description still adds meaning beyond it by enumerating the usable limits (noise figure, gain, P1dB, Psat, OIP3, insertion loss) and, crucially, by explaining that ranking is driven by the first limit supplied.

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 (find), resource (real parts in the validated catalog), and the exact selection criteria (part type, frequency, optional limits), so an agent knows this is spec-based search rather than MPN lookup. It explicitly contrasts with lookup_component_by_mpn by noting the results carry the same datasheet-page provenance that tool gives.

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 is given: use it when the user has stated a spec (type + frequency + limits), and the rule 'Pass only figures your user stated; an untraceable one is refused' tells the agent how to populate limits. However, it never states when to prefer this over sibling design tools (design_rf_chain, compare_rf_chains) or when lookup_component_by_mpn is the better 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 only cover readOnly/openWorld; the description adds real behavioral detail beyond them: which figures are returned with datasheet page references, that missing figures are labelled 'not in the record', that internal estimates are named but never numeric, and that the caller-asserted labelling depends on user_request. Exact-match matching behavior is also 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?

The purpose and return contents are front-loaded, and the exclusions follow logically. It is dense and slightly long for a two-parameter lookup, but nearly every clause carries distinct information (returned fields, degraded-data behavior, exclusions).

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 fully carries the return-value burden: it enumerates the returned fields, explains datasheet page references, and describes how incomplete records and estimates appear. Nothing needed to call 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 both parameters are already documented in the schema, including the exact-match caveat and the user_request verification purpose. The description adds no further syntax or format guidance for them, 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 ('look up') and resource (an RF component in the validated catalog by manufacturer part number) and immediately scopes it against the full datasheet. It is trivially distinguishable from the design_/run_ siblings, none of which retrieve catalog parts.

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 trigger ('Use this whenever the user names a specific part, so answers come from catalog data rather than recall') and explicit exclusions ('It does NOT hold derating, absolute-maximum ratings, bias, test conditions or footnotes: for those, read the datasheet link'). Both when-to-use and where-to-go-otherwise 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds real value beyond them: it discloses the underlying engine (POST /api/compliance/check), that layers are derived, that standards default, and that omitting user_request downgrades results to 'caller-asserted.' No rate limits or caching behavior mentioned.

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 dense sentences, front-loaded with the purpose and standards, followed by the invocation shortcut. No filler, though the standards enumeration is long and the default rule is repeated from the schema.

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

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

With no output schema, the description supplies the return shape ('per-rule pass/fail with severities and remediation'), the default standard set, the derivation of layers, and the user_request labeling consequence. An agent has 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?

Schema description coverage is 100%, so the schema already documents layers, standards, user_request, and stackup_config, including defaults and the caller-asserted labelling rule. The description largely restates the same default/derivation facts, adding little 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 ('Audit the solved stackup against PCB standards') and enumerates the standard families checked. It is clearly distinguishable from siblings like run_stackup_solver or run_pdn_analysis, which operate on different artifacts.

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

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

Explicitly says 'call with no arguments once a stackup exists,' which gives a clear precondition and default path. It does not name a competing sibling or state when NOT to run it, but the context is unambiguous.

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

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

With readOnlyHint=true already covering safety, the description still adds real behavioral context: defaults for tolerance/trace width, frequency derivation from the solved stackup, the differential-pair tolerance halving, and the caller-asserted vs verified labelling consequence of omitting user_request. The Phase-24/POST endpoint reference is implementation detail rather than agent-relevant behavior, keeping it out of the top score.

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 and ranking logic are front-loaded in the first sentence, and the calling guidance follows. The third sentence on the Phase-24 engine and internal POST route is low-value for an agent deciding whether to call, marginally diluting otherwise efficient 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?

No output schema exists, and the description compensates functionally by explaining that results are ranked styles with the cheapest qualifying one marked. Combined with full parameter coverage and read-only annotations, an agent has enough to invoke correctly; only the exact result shape remains unspecified.

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 five parameters and their defaults are already fully documented in the schema; the baseline is 3. The description largely restates those same defaults (tolerance 5%, trace width 0.1, derivation when omitted) without adding 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 names a specific verb ('Recommend') and resource ('PCB glass-weave (fiber-weave) styles') and states the scope precisely: ranks catalogued styles by impedance variation and cost for the design frequency, and marks the cheapest one meeting the tolerance. This is distinguishable from every sibling analysis tool at a glance.

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

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

It gives a concrete precondition and calling pattern -- 'call with no arguments once a design exists' -- plus which inputs are derived vs defaulted. It does not name a specific sibling or state exclusions (e.g. that a solved stackup must exist first), so it falls short of explicit alternative routing.

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

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

Annotations only establish readOnlyHint/openWorldHint; the description goes well beyond by disclosing that stages and input power are derived server-side for the no-arg case, that omitting user_request labels results 'caller-asserted', and that outputs include headroom warnings and an ambiguity warning for mixers. This is rich behavioral context an agent could not infer from 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?

Front-loaded with the core action and the no-arg rule, then progressively optional modes, then the sibling escape hatch. Dense and useful throughout, though the mid-sentence return-value list makes it a long single block rather than cleanly segmented.

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 correctly enumerates return figures (per-stage power, cascaded NF/OIP3, headroom warnings, noise floor/MDS/SFDR), covers the optional branches, and points to the sibling for the air-link case. 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 baseline is 3, but the description adds genuine meaning: the conditional pairing of bandwidthHz with requiredSnrDb, the semantics of the zero-argument mode, and the stages/inputPowerDbm coupling. It stops short of explaining every nested stage field, which the schema already handles well.

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 ('Compute a cascaded RF link budget') and immediately distinguishes itself from the sibling run_ota_link by scope (on-board chain vs over-the-air link). An agent can route between the two 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 branch conditions: call with NO arguments for a just-designed chain, pass stages + inputPowerDbm only for a bench/hypothetical chain, and use run_ota_link for air links. When-to-use, when-not-to-use, and the named alternative 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 declare readOnlyHint=true and openWorldHint=false, so the description must carry the rest — and it does: engine parity with POST /api/ota-link/compute, the free-space-only physics exclusions, that distance and misc loss are user assumptions disclosed on the result, and the caller-asserted labelling triggered by omitting user_request. These are non-obvious behavioral traits that materially affect interpretation of the output.

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 and outputs are front-loaded in the first sentence, and the sibling disambiguation is placed last where it belongs. It is a single dense block, and a few clauses (reuse rules, assumption disclosure) duplicate what the schema already states, so it is efficient but not waste-free.

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 13-parameter RF physics tool with no output schema, the description covers everything an agent needs: what is computed, what is excluded from the model, which inputs are reused or defaulted, and the shape of the returned figures. The absent output schema is compensated for by the explicit result enumeration.

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 13 parameters including the W-vs-dBm preference, defaults, and reuse rules. The description largely restates those (distance and misc loss as 'user assumptions', reuse of sensitivity/gain/frequency) rather than adding new parameter-level 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?

States a specific verb and resource ('Compute a one-way over-the-air link budget') and enumerates exactly what the result contains (EIRP, Friis FSPL, received power, link margin, closes/marginal/fails verdict, max range). It explicitly names the sibling it is not ('For the stage-by-stage cascade through one chain's parts ... use run_link_budget instead'), so an agent can route correctly 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 when to use this tool versus run_link_budget, names the scope boundary (FREE-SPACE ONLY, excluding rain/terrain/multipath/fading), and documents the fallback behavior when inputs are omitted (sensitivity reused from a prior link budget; tx gain and frequency from a prior antenna design). Nothing about selection 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value beyond that: it discloses the server-side derivation of inputs and that the engine is the Phase-25 implementation behind POST /api/pdn/analyze. It does not cover failure modes or runtime characteristics, but that is a minor gap given the annotation coverage.

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, front-loaded with the purpose and outputs before the derivation and no-arg usage note. The internal engine/endpoint reference is slightly implementation-flavored but short enough to earn 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 usefully enumerates what the analysis returns, and it explains that all four optional parameters are derived server-side. Combined with 100% schema coverage and read-only annotations, this is nearly complete, with only return format/pagination left unspecified.

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's schema already documents its 'derived when omitted' behavior, so the description largely repeats structured data. It reinforces the no-argument default but adds no syntax or format detail beyond the schema, making the baseline 3 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 (PDN impedance analysis) and enumerates the concrete outputs: interplanar capacitance, decoupling impedance vs. target, violations, and recommended caps. It is clearly distinguishable from sibling analysis tools like run_stackup_solver and run_thermal_analysis by domain and by the enumerated results.

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 ('call with no arguments once a design exists') and explains that all inputs are derived server-side, which tells the agent when the tool is applicable. It stops short of naming an alternative or stating when not to use it, so it is strong context rather than full routing guidance.

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

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

With readOnlyHint=true and openWorldHint=false already covering the safety profile, the description adds substantive context: the analytical-formula basis, that it reuses the SSOT engine behind POST /api/planar-filter/compute, and that it emits 'accuracy warnings'. It goes beyond annotations without contradicting them.

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

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

Purpose and supported topologies are front-loaded in the first sentence, followed by returns, usage, and exclusions. The long enumerated list of return artifacts is dense but every element is informative; there is little waste, though the returns clause could be tighter.

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 12-parameter tool with nested objects and no output schema, the description compensates well by spelling out what the call returns (impedances, width/spacing, footprint, response_curve and response_summary, accuracy warnings). Parameter-level detail is left to the fully-covered schema, so this is complete enough 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 description coverage is 100%, including enum constraints and nested substrate fields, so the schema does the heavy lifting (baseline 3). The description's mentions of Chebyshev/Butterworth and topology restrictions largely restate what the schema already documents, adding little parameter-level meaning beyond it.

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 ('Synthesize a passive planar copper-on-PCB filter from analytical formulas') and enumerates the supported topologies and responses. An agent can immediately tell this apart from all siblings (antenna, radar, link-budget, PDN tools), none of which synthesize filters.

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?

'Use it to replace a purchased SMT filter with board copper' gives a clear when-to-use context, and 'Interdigital/combline are not implemented' marks the capability boundary. It stops short of naming alternative tools or when NOT to use this one, so it is clear-context but not full when/when-not routing.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), yet the description adds real behavioral context: endpoint parity with POST /api/radar/performance, the fallback rule that MDS is inherited from a prior link budget, and the fact that RCS/target range/system loss are user assumptions disclosed on the result. It stops short of describing the return payload or numeric-edge behavior.

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

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

Front-loaded with the compute purpose, then two short sentences carrying the fallback and assumption-disclosure rules. Dense parenthetical enumerations but each clause maps to a real capability; no filler or repetition.

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

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

With 16 optional parameters, no output schema, and a complex physics domain, the description covers purpose, chaining, fallback inputs, and how results are labelled. It does not explain what happens when no parameters are supplied (all optional) or summarize the result shape, which is the remaining 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 parameter docs are already unusually rich (units, defaults, W-vs-dBm preference, assumption flags), so the baseline is 3. The description largely restates schema content (dBi gain entry, assumption disclosure) without adding syntax or precedence detail the schema lacks.

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 ('Compute') and resource ('radar performance') and then enumerates the exact outputs: monostatic range equation quantities (received power, SNR vs range, max detection range, integration gain) and pulsed-waveform relations (duty cycle, unambiguous range/velocity, range resolution, blind speeds). This is far more specific than siblings like run_link_budget or design_rf_chain, so an agent can route 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?

Usage is only implied: the note that the detection floor is 'reused from a prior link budget's MDS when not given' hints this tool chains downstream of run_link_budget, but it never states when to choose this tool over run_link_budget or run_compliance_analysis. No explicit when-not or exclusion criteria are 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 only declare readOnlyHint=true and openWorldHint=false, so the description carries real weight and delivers it: it warns that mask loss is NOT modeled and that a masked result says so in diagnostics, discloses the cost_priority default overrides, and explains the construction/hybrid search behavior. These are non-obvious behavioral traits an agent cannot derive from 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?

Front-loads purpose and usage in the first two sentences, then uses the remaining space for the one genuinely confusing output relationship (per-layer vs pressed total) that would otherwise cause downstream misreporting. No filler or restatement of the title.

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

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

With no output schema, the description must explain returns, and it covers the highest-risk return semantics (prepreg thickness, pressed total, diagnostics). For a 20-parameter solver it leaves most return fields (loss, heat_w, costPriority) to the schema, which is reasonable but not exhaustive.

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 and the schema already documents every one of the 20 parameters in detail. The description's numeric detail (prepreg_sheets x prepreg_sheet_thickness_mm, pressed thickness offset) describes returned fields rather than adding parameter syntax beyond the schema.

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

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

States a specific verb+resource ('Run the impedance-aware stackup constraint solver') plus the concrete output the agent gets ('ranked material/thickness/copper solutions'). This is clearly distinguishable from sibling analysis tools like run_thermal_analysis or run_pdn_analysis, which compute different quantities.

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 trigger: 'Use when the user wants ranked material/thickness/copper solutions for a given layer count and frequency.' That is clear context for invocation, but it names no exclusions and no alternative sibling (e.g. when to prefer run_glass_weave_analysis or a config update instead).

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 readOnlyHint/openWorldHint annotations: discloses that power_w is taken from the designed chain's dissipated power, ambient_c defaults to 25 C, the result carries `recommendations` to answer adjustment questions, a supplied heatsink REPLACES still-air convection and is echoed with source 'user_supplied' and a heat_path, and results are labelled caller-asserted if user_request is omitted.

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: purpose first, then invocation defaults, then heatsink handling. Some enumeration of models and overlap with schema text costs a little, but essentially every sentence 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 16-param, zero-required, no-output-schema tool, the description covers the critical behaviors (defaults, heatsink replacement semantics, recommendations output). It does not explain the shape of the returned result beyond `recommendations`/`heat_path`, but 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% (baseline 3), but the description adds real semantic value: heatsink θcs/θsa/mount must be 'all three as stated — never guessed', user_request should be the user's verbatim words to prove figures were stated not inferred, and analysis_input is optional once a design exists.

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 ('Run a full PCB thermal analysis') and enumerates the exact physics models computed (via array Rth, Kennedy spreading, Coffin-Manson, Timoshenko warpage, resin flow), which clearly separates it from siblings like run_pdn_analysis or run_stackup_solver.

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 invocation context: 'Call with no arguments once a design exists', explains server-side defaults, and tells the agent when to supply `heatsink` (only when the user states one). It lacks an explicit when-not/alternative routing against sibling analyses, but the operating conditions are well defined.

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