Electronics Architect

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

Annotations only cover safety/idempotency hints, but the description goes well beyond them: it discloses that solving both sides is unmetered, that monteCarlo is 'two metered Monte Carlo runs against the account's quota', and that a Pro/Team plan is required with a PLAN_REQUIRED refusal for Free accounts. These quota, cost and authorization facts are exactly the context annotations cannot convey.

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

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

Purpose is front-loaded in the first clause and followed by the return contract, which is necessary given there is no output schema. It is dense and long, but nearly every sentence carries either a return shape, a cost implication, or a plan requirement, so little is expendable.

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 documents the return surface (changes, delta, stages, nodes, warnings, optional yield). Combined with the plan requirement, metering notes and input flexibility, 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 100%, so the baseline is 3, but the description earns more by explaining that a/b can mix a document, designId and templateId freely, and that the monteCarlo seed makes movement attributable to the change. It still leaves corner and ambientTemperature semantics largely to the schema.

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

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

States a specific verb (compare two designs) and resource, then enumerates exactly what it produces: what changed and what the change did. It is clearly distinguishable from siblings like solve_design, get_design and review_design because it frames itself as a diff rather than a solve or a read.

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 THIS after every edit instead of reading two full solve results side by side' explicitly names the alternative it replaces and the moment to reach for it. It also scopes the optional path ('Pass monteCarlo to add yield'), so the agent knows when the expensive branch applies.

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

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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), the description discloses the validation precondition (schema v1), the quota consumption rule and its non-refundable nature ('A Free account saves 3 designs in total, the editor's saves included (deleting one does not give a save back)'), the ownership/attribution semantics ('flagged as created by this key'), and what is returned. This is materially more than the structured fields convey.

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

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

Purpose is front-loaded in the first clause, and the quota caveat is appended rather than buried. Four sentences are justified by the amount of distinct information (validation, return values, routing, limits), though the parenthetical about deleted saves is dense enough that it could be tightened.

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

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

There is no output schema, and the description compensates fully by naming the return payload (new design id and editorUrl) and explaining what that URL is. Combined with the validation precondition and quota limits, an agent has everything needed to call this correctly and act on 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% so the baseline is 3, but the description adds an actionable constraint the schema does not: the design body must validate against schema v1, which points the agent at get_design_schema before calling. The `name` parameter's human-recognition intent is left entirely to the schema.

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

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

The description states a specific verb and resource ('Save a design to the cloud') and immediately scopes it to the human-facing editor, which cleanly separates it from update_design (mutation of existing) and open_in_editor (opening, not creating). An agent can identify this as the creation entry point 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?

It gives clear routing guidance ('This is how agent work reaches a human: create it, then hand back editorUrl... or create_share_link for someone without an account') and names two relevant siblings with the condition that selects each. It never states the exclusion case, e.g. that an already-saved design should be modified with update_design rather than re-created, so the when-not half of the guidance is implicit.

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?

Annotations only declare readOnly/idempotent/no-destructive; the description adds non-obvious behavior beyond that, notably that each call itself runs more trials and the job only progresses while polled, that polling consumes no quota, the 24 h readability window, and NOT_FOUND for another key's job. It even discloses that cancellation is non-refundable, which no annotation covers.

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 polling loop, then edge cases, with no filler sentences. It is dense and parenthetical-heavy in places, but every clause carries operational information an agent needs.

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

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

Despite having no output schema, the description fully specifies the return shape (`job` with status/trials.done/trials.total/progress, `next`, and `result` as simulate_monte_carlo's digest) and the lifecycle, so nothing an agent needs to drive and terminate the poll loop 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 schema already documents the `job_` + 20-character format, so the baseline is 3. The description adds provenance meaning (where the id comes from) and ties it to the polling contract, a modest but real value-add.

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 ('Poll a Monte Carlo job') and anchors it to the `jobId` returned by run_monte_carlo_job, so the agent immediately knows this is the follow-up to a specific sibling. It is clearly distinguishable from simulate_monte_carlo, run_monte_carlo_job, and the other design tools.

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

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

Gives explicit when-to-call (after run_monte_carlo_job), the loop condition (keep calling until done/failed/cancelled), pacing rules (no wait between calls unless sliceInProgress, then ~5 s), and routes cancellation to a different interface entirely (DELETE /v1/jobs/{id} over REST). No alternative is left implicit.

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 safety (readOnly, idempotent, non-destructive), yet the description adds substantial context: metering/quota behavior, the exact status semantics (GREEN/ORANGE/RED bands), the UNSTATED handling for zero/blank ratings, what is deliberately not graded (sources, loads, BMS), Motor/Inverter edge cases, and the convergence precondition. This is far beyond what structured fields provide.

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

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

Front-loads the core action well, but it is dense and contains a verbatim redundancy: the Pro/Team unmetered and Free-plan solve-counting quota is stated once mid-description and again in the closing sentence. Trimming that duplicate iteration would materially tighten an otherwise information-rich passage.

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 explaining returns — per-component stress checks (parameter, actual, rated, limit, stressPct, status), worst status, mitigation text, `summary` counts, `thresholds`, and the `unrated` list. 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%, so the baseline is 3, but the description adds real meaning: `standard` is required and is 'the engineer's call', the design/templateId/designId triad are alternatives for supplying the design, and ambientTemperature feeds both the solve and the thermal stress figure. It doesn't restate every schema detail, which 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 — grade every rated part of a design against a named derating standard (NASA GSFC or IPC-9592) — and plainly distinguishes itself from siblings like solve_design, validate_design and review_design. An agent can identify the operation 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 clear context: run 'after one nominal solve', require a design/templateId/designId plus the standard, and warns to read `solve.converged` first. It stops short of explicitly naming alternatives (e.g. 'call solve_design before this') or stating when not to use it, so it lands at a strong 4 rather than a 5.

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

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

Annotations 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?

The description contradicts the idempotentHint=true annotation by stating 'Each run counts against the account's monthly Monte Carlo quota,' which is an additional side effect on repeated identical calls. Although the description otherwise discloses many behavioral traits (seed replay, clamping, failed/unconverged trials, percentile method, size defaults), this direct contradiction with the annotation forces a score of 1.

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

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

The description is front-loaded with the core action, then proceeds through result format, quota behavior, default digest versus raw trials, and parameter guidance. Despite its length, every sentence carries operational information relevant to calling 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 complex, nested-parameter simulation tool with no output schema, the description thoroughly explains the default digest result, the omitted per-trial array and its size rationale, quota consumption, and failure modes. An agent has enough context to call it correctly without needing return-value 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 description coverage is 100%, so the baseline is 3, but the description adds useful parameter implications: seed enables byte-identical replay, includeTrials should be used only for per-trial sensitivity analysis, and options.trials should be kept at 50 or fewer when includeTrials is true. It does not add format or constraint details beyond what the schema already documents, so it falls short of 5.

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

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

States a specific verb and resource: run a multi-trial Monte Carlo tolerance analysis server-side, including distributions, clamping, and what is simulated. It does not distinguish itself from the sibling run_monte_carlo_job, leaving potential ambiguity about which Monte Carlo entry point to choose.

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

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

Provides clear conditions for using includeTrials=true and points to get_account_usage for quota, plus guidance to keep trials small when requesting raw data. It does not compare against the sibling run_monte_carlo_job or explain when to prefer this tool over that alternative.

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 annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description earns credit by adding substantial behavioral context beyond safety: plan limits and solve counting, result size (55–70 KB vs compact), the converged boolean as the success signal, warning structure with stable codes and remedies, and the nuanced difference between node and stage efficiency.

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

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

The description is long but front-loads the core purpose and output list, then layers in billing, input options, warning semantics, efficiency nuances, and sweep guidance in a logical order. There is some repetition (e.g., 'counts as one solve' appears twice) and a few tangents, but nearly every sentence carries actionable information for a complex tool.

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

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

No output schema exists, so the description must carry the full burden of explaining return values—and it does: node voltages, currents, dissipation, junction temperatures, rating checks, warnings with codes/levels/labels/messages/remedies, summary.warningGroups, per-sheet converged booleans, dual efficiency figures, and efficiencyCurve details. Nothing an agent needs to interpret a solve 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 description coverage is 100%, so the schema already documents all eight parameters in detail. The description largely repeats the sweep and corner semantics already in the schema and adds only marginal parameter-level meaning (e.g., 'PREFER compact: true'), so it lands at the baseline for a fully documented 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 first sentence states a specific verb (solve) and resource (design) and enumerates the exact result fields (node voltages, currents, dissipation, junction temperatures, rating checks, warnings). This is far more specific than a tautology and lets an agent distinguish it from siblings like run_derating or simulate_monte_carlo 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?

The description gives clear context for when to use sweep (battery range, tolerance sweep), when to prefer compact (always, due to size), and how to supply a design (design, templateId, designId). It stops short of explicitly naming when NOT to use this tool versus alternatives like run_derating or review_design, so it misses 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?

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.