Electronics Architect

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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description goes well beyond them: plain solve comparison is unmetered, adding monteCarlo triggers two metered runs against the account quota, Free accounts are refused with PLAN_REQUIRED, and the same seed makes movement attributable to the change. That is exactly the operational context an agent needs and cannot get 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?

It is front-loaded and dense — action first, then a return-value inventory, then the usage directive and plan gate. Almost every clause earns its place, but the content is crammed into one long run-on paragraph with no separation between parameters, returns and usage, which hurts 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?

There is no output schema, so the description carries the full burden of describing returns, and it does so item by item (changes, delta shape { a, b, delta }, stages, nodes, warnings.resolved/introduced, optional yield). Combined with the plan and metering disclosures, 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 already 100%, so the baseline is 3. The description still adds real meaning: the two sides may be mixed freely across design document, { designId } and { templateId }, and the monteCarlo seed carries the attribution semantics and default trial count. It slightly exceeds the schema, though most field-level documentation lives in the schema.

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

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

The description states a specific verb (compare) and resource (two designs) and immediately scopes it to 'what changed between them, and what the change did'. It also enumerates the exact outputs (changes, delta, stages, nodes, warnings), which distinguishes it from solve_design and run_monte_carlo_job 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 an explicit directive with an alternative: 'USE THIS after every edit instead of reading two full solve results side by side; it is the cheap way to see whether a part swap helped.' It also flags the metering distinction (plain solve unmetered, monteCarlo metered) and the Pro/Team requirement. It stops short of naming sibling tools or stating when-not to use it, so it lands just under the top tier.

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=false, idempotent=false, destructive=false, openWorld=false, so the mutation profile is known. The description adds substantive context beyond them: the schema v1 validation requirement, the returned design id and editorUrl, and a hard quota (Free accounts save 3 designs total, 1 sheet each, deletions do not restore a save) — a rate/quota disclosure that belongs in prose. It does not explain what happens on validation failure or name collisions, leaving some behavioral gaps for a create 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?

Five short sentences, front-loaded with the action and the payoff (editorUrl) before the quota caveat. Nothing is redundant with the title, and the quota sentence, though the densest, carries information an agent cannot get 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?

There is no output schema, so the description correctly discloses return values (design id plus editorUrl and its meaning, flagged as created by this key). For a nested-object create with hard account limits and no output schema, the description covers validation, return shape, downstream handoff, and quota — 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 coverage is 100%, so both parameters are already documented in the input schema and the baseline is 3. The description only adds the constraint that "design" must validate against schema v1, which largely restates the schema's own "(schema v1)" note and gives no added detail about the nested document structure or the name field.

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 ("Save a design to the cloud") and states the purpose from the human's side ("so a person can open it in the editor"). It also implicitly separates itself from update_design (new design) and explicitly from open_in_editor and create_share_link, so an agent can distinguish it among 20 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?

Gives an explicit workflow: "This is how agent work reaches a human: create it, then hand back editorUrl ... or create_share_link for someone without an account." It names the alternative tool and the condition that selects it (recipient has no account), which is exactly the when-to-use vs. alternative guidance needed.

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=false, idempotentHint=true, destructiveHint=false), but the description adds real context beyond them: the link is public, recipients need no account, and calling again mutates the existing link in place rather than minting a second one. It does not mention rate limits, revocation, or what happens to previously distributed URLs when permissions change.

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, zero filler, and the core purpose is front-loaded before the routing rule. Every clause carries information the agent needs to pick and place the call 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 single-purpose public-link mutation with no output schema, the description covers purpose, routing, and update-in-place behavior adequately. The remaining gap is parameter-level guidance (permission and expiry choices) that the caller must infer from the schema 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 only 67% (designId has no schema description) and the description mentions no parameters at all — not the view/edit/clone permission levels, not the expiration window. With coverage below the 80% baseline, the description was expected to compensate for the required-parameter gap and 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?

States a specific verb and resource ('Create (or update) the public link for a cloud design') and anchors it to a known artifact ('the same link the editor's Share dialog makes'). It explicitly distinguishes itself from the sibling open_in_editor, so an agent can route 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 an explicit when-to-use condition ('for a person who does NOT own the design or sit on its team') and names the alternative for the opposite case ('for the owner, editorUrl / open_in_editor is the link'). It also discloses the one-link-per-design constraint, removing ambiguity about whether repeated calls create duplicates.

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/non-destructive, and the description adds material context beyond them: the plan-gating behavior and exact error code (PLAN_REQUIRED), that the document is returned inline rather than as a link, and the universal `attribution` block present in every export including the trailing CSV line.

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 and then dense with genuinely load-bearing detail; nearly every clause carries information an agent needs (export payloads, attribution, PDF exclusion, plan gate). It is a single heavy paragraph, so mild restructuring would help readability, but there is little 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?

With no output schema, the description carries the return-value burden and does so thoroughly — contents of each export, the attribution block, and the inline (not link) delivery model. Combined with the plan and sibling-routing notes, 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 coverage is only 33%, so the description has to compensate, and it does for `type` by describing the payload of each of the five enum values. `corner` is only gestured at ('the solved result at one corner') and the nom/min/max/worst values are left to the schema, and `designId` is undocumented, so it falls just short of full compensation.

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 ('Export a cloud design') and then enumerates exactly what each export type yields, so an agent can distinguish bom_json from design_json from solve_json at a glance. It also explicitly separates itself from siblings open_in_editor (PDFs) and run_derating (derating checks as data).

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: which type to pick, that PDF exports are not available here and the agent should hand the user an open_in_editor URL instead, that derating checks live in run_derating, and that a Pro/Team plan is required (Free refused with PLAN_REQUIRED). This is when-to-use, when-not and alternatives 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?

Annotations already cover read-only/idempotent safety, yet the description adds substantial behavioral depth beyond them: quota exhaustion semantics, the pack_offer top-up flow, that a key cannot purchase the top-up, that solving is unmetered on Pro/Team, and that Free accounts cannot buy packs. This is exactly the context an agent needs to reason about cost and authorization.

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 opening line is front-loaded with the two core facts (identity and remaining quota). The body is dense but nearly every clause addresses a distinct decision (pre-run check, failure mode, plan metering, Free constraints), so little is filler, though the paragraph is long for a no-arg 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?

With no output schema, the description carries the burden of explaining return values and does so field-by-field (label, scopes, tier, used/limit/reset, pack, remaining) while also covering plan-dependent behavior. An agent can act correctly without any further documentation.

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?

Zero parameters, so the baseline of 4 applies; there is no parameter syntax or format the description needs to compensate for. Nothing is missing on this dimension.

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 ('who this server is acting as, and what is left this month') and enumerates precisely what is returned: API key label and scopes, account tier, per-feature used/limit/reset date, pack, and remaining. No sibling tool touches account or quota state, so it is trivially distinguishable.

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 the trigger condition: 'Check this before a run that will use several AI calls or Monte Carlo runs, so you can tell the user up front.' It also names the failure path (QUOTA_EXHAUSTED with pack_offer) that this tool lets the agent preempt, and clarifies Free vs Pro/Team metering differences.

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 read-only/idempotent/non-destructive, so the description is free to add the parts that matter: the `properties` block is copy-ready for a node of that `type`, `provenance` is per supplied key, and `filledFromDefaults` lists keys the library did NOT supply (registry defaults, not datasheet figures). That trust caveat is exactly the kind of behavioral context 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?

Front-loaded with the purpose, and nearly every clause earns its place (the filledFromDefaults warning, the miss semantics, the schema-confirmation step). It is, however, a single dense em-dash-heavy block that could be broken up 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?

With no output schema, the description carries the full burden of describing the return shape — `properties`, `provenance`, `filledFromDefaults`, and the descriptive keys — and it does so fully, including how to use the returned `properties`. Nothing an agent needs to call or interpret 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema strings: `mpn` is an exact lookup, `type` is a filter whose result comes back as a `types` list. This clarifies how each parameter affects the response rather than merely restating the schema descriptions.

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

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

States a specific verb+resource ('Retrieve parametric simulation models from the Electronics Architect curated part library') and immediately bounds it against what it is not ('NOT pricing or stock'). An agent can distinguish it from siblings like get_design_schema (which it explicitly defers to) and from any pricing/stock tool 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 explicit routing: filter by `type` or look up an exact `mpn`, confirm the `type` with get_design_schema first, and tells the agent what a miss means ('enter the datasheet values by hand', not 'the part does not exist'). It also names the when-not case (pricing, stock, distributor search unavailable here).

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 one behavioral detail beyond that — the response includes a revision count — but says nothing about invalid-id handling or auth. Adequate but modest given the low annotation-driven bar.

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, with the core operation front-loaded and the id-sourcing tip second. 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 one-parameter read tool with complete annotations and no output schema, the description covers purpose, argument sourcing, and one return detail. Only a fuller statement of the return shape or error behavior is missing, which is minor here.

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 0% for the single required parameter, so the description must compensate. 'By id' plus the pointer to list_designs as the id source gives real semantics for designId, though it adds no format details.

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

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

States a specific verb (Read), resource (cloud design), and scope (one, by id), and even previews the return content (revision count). It explicitly contrasts with list_designs, letting an agent tell singular fetch from bulk listing 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 operative context: 'Use list_designs to find ids,' which tells the agent how to obtain the required argument. It stops short of stating when-not to use this tool (e.g., versus get_design_schema or open_in_editor), so it is strong but not exhaustive.

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), and the description adds genuinely valuable context the annotations cannot: SI base units with no prefix, JSON numbers never strings, and that unknown property keys are rejected rather than ignored.

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 purpose in one clause, then splits the two call modes and the critical formatting constraint. Dense 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 no output schema, the description still tells the agent what both call modes return and the units/typing rules that govern a hand-written design. Nothing essential 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 100% and the single `type` param is already documented in the schema, but the description goes beyond it by stating what a typed call returns (key, unit, default, allowed range, meaning) and what omitting it 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+resource: it reads the design schema and defines what a valid Electronics Architect design document looks like. This is clearly distinguishable from siblings like get_design, validate_design or get_component_model.

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 conditional usage — no arguments for the units policy/shape/type list, a `type` for that type's full property set — plus a strong directive to always read it before writing a design by hand. It does not name sibling alternatives, 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?

Adds a lot beyond the readOnly/idempotent annotations: each call advances the job 3-5 s of trials, progress only happens while polling, polling consumes no quota, jobs expire 24 h after finishing or last progressing, and a job belonging to another key returns NOT_FOUND. That last point and the quota-free guarantee are precisely the operational facts an agent cannot infer 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 the polling loop, then the terminal-state rule, then lifecycle caveats. Dense and information-rich, though the em-dash parentheticals make it read as one crowded paragraph rather than clearly separated concerns.

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 return burden and does it: it names the `job` fields (status, trials.done/total, progress), the `next` field's meaning and its 'how many calls left' estimate, and the `result` shape on completion. Nothing needed for correct polling or interpreting the response 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% and the single param is already documented with its `job_` + 20-char format, so baseline is 3. The description still adds provenance the schema lacks — that the id must come from run_monte_carlo_job — which is the one semantic detail that prevents a caller from passing an arbitrary id.

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

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

Opens with a specific verb+resource ('Poll a Monte Carlo job') and immediately ties the input to its producer ('by the `jobId` run_monte_carlo_job returned'), which cleanly separates it from the sibling run_monte_carlo_job (starts a job) and simulate_monte_carlo (returns the digest synchronously). An agent can identify the tool 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 loop contract: keep calling until status is done/failed/cancelled, do not sleep between calls unless `job.sliceInProgress` is true, and cancel via REST DELETE instead. It also names the alternative path for getting the same digest (simulate_monte_carlo), so the when/when-not decision is fully covered.

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 and closed-world, so the safety profile is covered. The description adds real value beyond them: every template is schema-valid and solves as-is, and the returned JSON is identical to the resource payload. It does not, however, discuss size or pagination, which is minor for a single-record read.

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, but the dated parenthetical about the 2026-09-11 acceptance run is anecdotal filler, and the port-convention example list is long. A reader has to wade through several clauses to reach the 'copy, edit, validate' 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?

No output schema exists, so the description correctly takes on the burden of describing the return ('a complete design document — the same JSON the resource serves'), including its validity and solvability. It is complete enough to call correctly, with only minor gaps around payload size.

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 single parameter is already documented in the schema as 'A template id from list_templates.' The prose adds no format, syntax, or resolution details 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?

States a specific verb (Read) and resource (one shipped template) and immediately scopes it as a complete design document equivalent to the ea://templates/{id} resource. This clearly distinguishes it from list_templates (enumeration) and get_design (user designs).

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 gives the condition that selects this tool over the alternative resource ('for clients that do not expose resources'), and routes the follow-up workflow: 'Copy it, edit it, then validate_design.' The templateId schema entry also points to list_templates as the discovery step.

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 and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: results are scoped by key type (personal key = account designs, team key = team designs). It stops short of describing return format, ordering, or pagination behavior.

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

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

Two tightly written sentences, front-loaded with the operation and immediately followed by the scoping rule. The editor-location analogy earns its place by grounding the result set for the agent, and there is 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 zero-parameter, read-only list tool with no output schema, the description covers the essential ambiguity: what set of designs comes back and why the key type matters. Only minor gaps remain (ordering, pagination, what a personal-vs-team mismatch looks like), which are low-stakes here.

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. There is no parameter syntax or filtering to document, and the description adds no misleading parameter claims, so nothing further is needed on this dimension.

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

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

The description opens with a specific verb+resource ("List the cloud designs") and adds a scope qualifier ("this key can see"), which is more than a name restatement. It is distinguishable from a single-fetch tool like get_design, though it never explicitly names list_templates as the contrasting sibling.

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 scope explanation (personal vs team key determines what returns), so an agent can infer when this is the right call. However, there is no explicit when-to-use framing, no exclusions, and no routing to siblings such as get_design for a single design or list_templates for templates.

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 and closed-world, so safety is covered. The description adds genuine value beyond that by disclosing the return payload (id, sheet names, component census by node type, canvas notes), which matters because 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?

Front-loaded with the purpose, then return contents, then routing. Three sentences is slightly long for a list tool, but every sentence carries information (payload shape, alternatives, usage trigger) 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, the description compensates by enumerating the returned fields, and it names the follow-on tools and resource URI. Nothing an agent needs to select or invoke this zero-arg 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?

Zero parameters, so the baseline is 4; there is no parameter syntax to explain. The description correctly notes that an id produced here can be passed to solve_design or get_template, which is the only useful cross-tool data-flow hint.

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?

Specific verb (List) plus resource (shipped power-tree design templates) with scope clarified against siblings: it lists templates, whereas get_template reads a full design and list_designs covers user designs. An agent can distinguish it from the rest of the sibling set immediately.

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: start here when the user describes a design that likely already exists, then use get_template or the ea://templates/{id} resource to read one, or pass an id to solve_design. Names concrete alternatives and the conditions that select them.

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, non-open-world), so the bar is lower. The description adds genuine behavior beyond them: the sign-in flow for unauthenticated viewers, the banner naming the key that made or last changed the design with one-click revert to the previous state, and that zero arguments yields a blank editor.

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 purpose and return value, then layers routing and fallback behavior. It runs long, and the banner/key-revert detail is slightly tangential, but nearly every sentence carries actionable routing or behavioral 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, and the description fully describes what is returned (a URL), the variants (design-specific vs. blank editor), and the auth implications. 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, but the description adds real meaning: designId scopes the URL to the owning account or team and makes it load that specific design, while its absence returns a blank editor. That is more than the schema's bare 'A cloud design id from create_design or list_designs.'

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 ('Return the URL that puts a design in front of a person on the canvas') and explicitly distinguishes itself from create_share_link, the closest sibling. An agent can identify the tool's role 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 explicit when-to-use ('belongs at the end of every workflow: an agent produces, a human reviews and approves') and when-not-to-use ('For someone WITHOUT an account ... use create_share_link instead'). It also warns that create_design and update_design already return the same link, so the agent knows when this tool is redundant.

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=false and destructiveHint=false but say nothing about cost, review mechanics, or output structure. The description fills that gap with high-value behavior: metered quota consumption, worst-case input derivation, the `rejectedSuggestions`/`ratingCheck` filtering behavior, and the specific limitation that solve results are only checked at one operating point. This is exactly the kind of detail 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?

Front-loaded with the core action ('Ask Electronics Architect's own reviewer...'), then progressively details output, cost, and worst-case mechanics. Dense but nearly every sentence earns its place; the worst-case paragraph runs slightly long but each clause adds behavioral information unavailable 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 complex, metered, open-world-ish analysis tool with no output schema, the description covers purpose, cost, input semantics, internal review mechanics, output structure (both the narrative and the rejectedSuggestions list), and the key edge case (solve-result limitation). An agent has everything it needs to call it correctly and interpret the result.

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 both params are described inline, so the schema already carries param syntax. The description adds semantic context for `design` (a design document preferred over a solve result, and the consequences of each), but provides no further detail on `ambientTemperature` beyond what the schema states. 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 ('AI design review of a design or solve result') and enumerates exactly what it returns: plain-English interpretation of numbers followed by concrete improvements with designators and estimated gains. It distinguishes itself from siblings like solve_design and validate_design by framing the output as advisory suggestions rather than a solve or a pass/fail check.

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?

Clearly states what to pass ('the design document: the reviewer solves it itself') and notes the solve-result alternative and its limitation, along with the cost ('one call on the account's monthly AI quota'). It lacks explicit when-not-to-use guidance or direct naming of the alternative siblings (e.g., run_derating, validate_design) for narrower needs.

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/non-destructive profile, and the description adds substantial context beyond that: server-side execution, Pro/Team unmetered versus Free-plan solve accounting with meta.solvesRemaining, the 1-sheet limit, which elements are not graded (sources, loads, BMS), UNSTATED handling for 0/blank ratings, GREEN/ORANGE/RED thresholds, and Motor/Inverter check 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?

Purpose is front-loaded and almost every sentence carries real information, but the passage is a ~350-word wall of text and the plan metering is literally stated twice ('Unmetered on Pro and Team; on the Free plan...'). Trimming the duplication and tightening the edge-case list would improve it.

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?

Comprehensive for a tool with no output schema: it describes each returned element (stress checks, limit, stressPct, status, basis, worst status, mitigation, summary, thresholds), plus the convergence caveat, ungraded element types, and metering behavior. Nothing material an agent needs 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 description coverage is 100%, so all five parameters are already documented. The description only marginally extends this, adding that the standard choice is 'the engineer's call' and reiterating the design/templateId/designId alternatives; it adds no syntax or format 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 specific verb and resource ('Grade every rated part of a design against a derating standard'), names the two supported standards with per-family factors, and is clearly distinguishable from siblings like solve_design, validate_design and review_design. An agent can tell what this returns 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 the precondition ('after one nominal solve') and the input alternatives (design document, templateId, or designId), and instructs to check solve.converged before reading the report. It never explicitly contrasts itself with sibling tools such as validate_design or review_design, so the routing guidance is implied rather than spelled out.

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=false and idempotentHint=false, and the description adds substantial behavioral context beyond them: metered quota charged once at creation, two-active-jobs cap with TOO_MANY_JOBS refusal, 24 h result retention, Pro/Team plan requirement with PLAN_REQUIRED, clamping via meta.clamped/clampedBy, and the fact that the job only advances while polled. This is unusually rich disclosure for a mutation 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?

It is long, but the complexity is real and the key facts (job semantics, alternatives, polling, limits) are front-loaded. A few clauses re-explain what the schema already says, keeping it just short of fully economical.

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: the digest shape (summary, counts, seed, nodeStats, never per-trial arrays), job.status 'done', the next.jobId/next.estimatedPollsRemaining continuation, and meta.clamped semantics. An agent has everything needed to invoke and drive the job 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 design/designId/templateId/options and their sub-fields, and the description largely repeats that ('Give a design document, a templateId or a saved design's designId, plus options'). Baseline 3 is appropriate; the description 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?

States a specific verb and resource ('Start a Monte Carlo tolerance analysis as a JOB') and immediately scopes it to runs too long for one call. It explicitly names simulate_monte_carlo as the same-engine sibling and distinguishes the job variant from it, so an agent can tell the two apart 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 an explicit decision threshold: use simulate_monte_carlo when nodes × trials is under ~50,000 (one call), use this above that or whenever simulate_monte_carlo timed out. The polling model and the fallback path for continuation are spelled out, 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 beyond the annotations: discloses quota metering ('counts against the account's monthly Monte Carlo quota'), refusal semantics for unrecognized node types, seed replay guarantees, the nearest-rank percentile method, and how failedTrials are excluded from statistics. It also explains why the default result is a digest rather than the per-trial array (3.5 MB for a 1000-trial run), which is exactly the kind of non-obvious behavior an agent cannot 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 purpose before diving into result semantics, and every sentence is substantive rather than filler. It is dense and runs long, but the density is earned by otherwise-undocumented behaviors like the digest default and quota cost.

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

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

With no output schema, the description correctly carries the full return-value burden, enumerating `seed`, `failedTrials`, `unconvergedTrials`, `summary`, and `nodeStats` in detail. The main gap is that it does not explain how this synchronous, metered run relates to `run_monte_carlo_job`, nor does it mention expected runtime for large trial counts.

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 carries the per-parameter burden (baseline 3). The description adds real meaning on top: byte-identical replay tied to `seed`, the reason to keep `options.trials` at 50 or fewer with `includeTrials`, and the keyed format of the per-trial `inputs` map.

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?

Strong specific verb+resource: 'Run a multi-trial Monte Carlo tolerance analysis entirely server-side,' with concrete detail on what is randomized and what is reported. However it never distinguishes itself from the sibling `run_monte_carlo_job`, which an agent could easily confuse with this synchronous metered tool.

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 guidance for `includeTrials: true` ('only when you need the per-trial inputs for sensitivity analysis') and for the default digest path, plus routes quota checks to `get_account_usage`. It states no explicit exclusion against the async sibling `run_monte_carlo_job`, which is the one routing decision an agent most needs.

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 far beyond the annotations: billing model (unmetered on Pro/Team, 10/month on Free, meta.solvesRemaining), server-side execution, that sweep counts as one solve, output size (55–70 KB for 34 nodes), and the caveat to read each sheet's `converged` rather than infer success from missing errors. That convergence warning in particular is behavioral knowledge an agent could not get from anywhere else.

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, but the single dense paragraph runs ~350 words and buries operational guidance. The SMPS efficiency/effVin/efficiencyCurve passage is long and only relevant to one component type, and the compact recommendation plus its size rationale are effectively stated twice.

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 full burden and does so: it documents the warning object shape (`code`/`level`/`label`/`message`/`remedy`), `summary.warningGroups`, per-sheet `converged`, `points[]` for sweeps, and how efficiency is reported. An agent can interpret the result without further documentation.

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 meaning the schema does not: compact drops the `efficiencyCurve` (not stated in the schema), and it explains why compact is preferred (full result echoes properties and repeats warnings). The designId/templateId/design alternatives are restated from the schema, which limits the score.

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 precise verb+resource and enumerates exactly what comes back (node voltages, currents, dissipation, junction temperatures, rating checks, warnings). It is clearly a simulation/solve tool, but it never explicitly contrasts itself with the close siblings validate_design, review_design or run_derating, 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?

Strong conditional guidance: pass sweep:true for a battery/supply range rather than guessing charge levels, PREFER compact:true for size reasons, and supply design / templateId / designId as alternatives. It lacks any explicit 'do not use this when…' or sibling routing (e.g. vs validate_design), which keeps it below 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 annotations: it discloses that the call is metered against a monthly synthesis quota, that it consumes a scarcer quota than AI calls, that it fails with PLAN_REQUIRED on Free accounts, and that generated designs can carry wrong part parameters. Annotations only give the generic non-read-only, non-idempotent profile; the description supplies the operational consequences.

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 example are front-loaded, and each subsequent sentence adds distinct operational information (quota, validation chain, plan gate) rather than restating the first. It is dense but no sentence is filler; the only mild cost is that quota, validation, and plan rules are packed into one block.

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 one-parameter generation tool with no output schema, the description covers the essentials: what it returns at a high level ('already solved'), what it costs, who can call it, and what must be done with the result before trusting it. It could say slightly more about the shape of the returned design, but the validation chain largely compensates.

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 single 'prompt' parameter is fully described in the schema, so the baseline is 3. The description adds value by giving a concrete example brief and emphasizing what must be included (input voltage, every rail with its current, binding constraints), which helps the agent compose a usable prompt rather than a vague one.

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 ('Generate a complete power tree from a plain-English brief') and concretizes it with a realistic brief example, including that the result is returned 'already solved'. It also names the siblings it relates to (get_account_usage, solve_design, validate_design), so an agent can place it in the workflow without ambiguity.

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 usage conditions: check get_account_usage first because the synthesis quota is smaller than the AI quota, and always follow with solve_design and validate_design before presenting results. It also states the plan prerequisite. What it lacks is routing guidance against the sibling generation tool create_design, which an agent might otherwise confuse with this one.

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 destructive=true and idempotent=true, and the description adds substantial context beyond them: prior state is preserved in revision history, attributed to this API key's label, and is rollback-able. It also explains the non-obvious return of editorUrl and what handing it back does, which is genuine behavioral disclosure.

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 core action and its full-replacement constraint. The third sentence is dense and slightly run-on, but every clause carries information an agent needs about the return 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?

Complete for a destructive mutation with no output schema: it covers the write semantics, the audit/rollback behavior, the message requirement, and the one returned field (editorUrl). 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 75%, and the description adds real meaning for `design` (must be the complete document) and `message` (persisted into revision history so the label explains the change). It adds little for `name` and `designId`, but the message semantics are non-obvious and well covered.

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 (Replace) and resource (cloud design) with the key scope constraint that the whole document is sent. An agent can immediately distinguish it from create_design (new object) and get_design (read) 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 strong in-tool usage rules ('send the whole document — there is no partial update', include a message), which is actionable context. However, it offers no guidance on when to choose this over siblings like create_design or review_design, leaving alternative selection 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, non-destructive and closed-world behavior, so the safety profile is covered. The description adds useful context beyond annotations: it is cheap, checks without solving, and returns every problem at once with a JSON path for each. It does not fully describe success output format, but the error behavior is clearly 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?

Three sentences, front-loaded with the core action, then scope, then the workflow trigger. Every sentence earns its place 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?

For a simple read-only validation tool with one well-documented parameter and annotations covering the safety profile, the description covers what is checked, when to call it, what it returns on failure, and how it relates to solve_design. 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 description coverage is 100% and there is only one parameter, whose schema description already says it is the design document to check. The tool description does not add syntax or format details beyond the schema, so the baseline 3 for high schema coverage 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: check a design against schema v1. It explicitly distinguishes itself from solve_design by saying 'WITHOUT solving it' and describes the exact validation scope (property keys, types, units, structure). An agent can tell this apart from review_design and solve_design 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 guidance: 'Run this after writing or editing a design and before solve_design.' It also explains why: a design that fails here is refused by the solver, and these messages are more specific. No alternative routing is left ambiguous.

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