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

No annotations are provided, so the description carries the full behavioral burden. It conveys the RFQ delivery mechanism (email and/or webhook) but omits everything else an agent needs for a mutation: permission/auth requirements, whether a duplicate id overwrites or errors, the significance of the id pattern, and what happens to unmentioned fields.

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

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

Two tight sentences, front-loaded with the core action. Every clause carries information and there is no filler. Slightly under-specified rather than wasteful.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description only addresses 2 of the parameters and provides no safety, idempotency, or auth context. An agent cannot reliably invoke it without guessing about the other six fields.

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 only 13% across 8 parameters, so the description must compensate. It mentions email and webhook (and implicitly the aikea.rfq/v1 schema), but leaves id, name, notes, region, services, and token_env completely unexplained, and never notes the required id/name pair or the id slug pattern.

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: 'Save a CNC shop for quotes.' This clearly distinguishes it from the sibling aikea_list_fabricators, which is a read tool. It's clear but doesn't explicitly name the sibling or the broader workflow placement.

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

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

The description implies this is a setup step before requesting quotes ('for quotes'), and says what to provide (email/webhook). However it gives no explicit when-to-use guidance, no prerequisites (e.g., must the shop be registered before aikea_request_quote), and no mention of alternatives like aikea_list_fabricators.

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 no annotations, the description carries the full burden; it does well on the output side by naming every artifact and stating that paths/URLs plus a layout image are returned. It is silent on the mutation profile: whether it writes to disk, overwrites prior builds, costs money, or requires a saved design.

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

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

One dense sentence front-loaded with the core action, followed by the artifact list. Every clause carries information; the enumeration of outputs is long but each item is useful for verifying success.

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

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

No output schema exists, and the description compensates by describing return values and download URLs in detail. Combined with near-complete parameter documentation, an agent has enough to call and interpret the tool, though overwrite/failure behavior is unaddressed.

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 three documented params already carry units, ranges and defaults (trim, spacing, tool_diameter). The description adds no semantic detail beyond the schema, and design_id remains undocumented in both places. 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 (nest, write) plus the resource (fabrication package) and enumerates the concrete artifacts produced, so the agent knows exactly what the tool yields. It does not, however, differentiate itself from the sibling aikea_preview, which likely renders a layout without emitting files.

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

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

No when-to-use guidance, no prerequisites (e.g. design must exist / be finalized), and no mention of aikea_preview as the lighter-weight alternative for just viewing a layout. The 'build' framing implies a terminal step but the agent is left to infer it.

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

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

With no annotations, the description carries the full behavioral burden; it usefully discloses the destructive overwrite semantics ('revise an existing design in place') and the returned artifacts. It omits other behavior an agent would want, such as whether generation is deterministic, persistence/ownership implications, permissions, or cost.

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

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

Three short sentences, each earning its place: purpose first, then return values, then the revision hint. No filler or restatement of the title.

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

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

There is no output schema, but the description compensates by naming the return payload (summary, validation issues, preview image), and all four parameters are documented in the schema. A mutation-capable tool with no annotations could say more about side effects, but the essentials are covered.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the mm units and the revision semantics of design_id. The description's restatement of the design_id behavior adds little beyond what the schema states, so the baseline of 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?

The description states a specific verb and resource ('Generate a parametric flat-pack design') and enumerates the concrete outputs it produces (panels, CNC machining, hardware, assembly steps), which clearly separates it from siblings like aikea_get_design or aikea_list_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?

It explicitly tells the agent that passing design_id switches the tool into revision-in-place mode, which is genuine usage guidance, and it points to aikea_list_options as the source of valid template keys. It does not, however, say when to prefer this over aikea_get_design for inspecting an existing design or what to do if the template is unknown.

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

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

Annotations only declare readOnlyHint=true; the description adds genuine behavioral content by describing the two response shapes and the contents of the full model ('every part with local-frame machining'). It omits error behavior (e.g. unknown design_id) and payload size/rate implications of full=true.

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

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

A single sentence that front-loads the default behavior (summary) and then qualifies the alternative. No wasted words and no redundancy with the schema.

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

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

With no output schema and minimal annotations, the description adequately explains the return shape and the switch that changes it. Given the low complexity (2 params, one required), only edge-case error handling 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 0%, so the description must carry parameter meaning. It does define what full=true actually returns, which the schema does not; design_id is self-evident by name. It compensates well for the coverage gap without fully documenting both parameters.

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

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

States a specific verb ('Return') and resource ('a saved design'), and clearly distinguishes the two output modes (summary vs full JSON model). It does not explicitly contrast itself with the similarly named sibling aikea_design or aikea_list_designs, so it falls short of a 5.

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

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

It gives one concrete condition for opting into the heavier mode ('when full=true'), which is implied usage guidance. However, it never says when to prefer this tool over aikea_design, aikea_list_designs, or aikea_preview, and offers no exclusions or prerequisites.

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?

readOnlyHint=true already establishes this is a safe read. The description adds one genuine behavioral fact beyond the annotations — results are ordered newest first — but says nothing about pagination, result limits, or what a saved design record contains.

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

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

A single sentence with no waste, front-loading the resource and appending the ordering constraint. Nothing could be removed without losing information.

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

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

For a zero-parameter list tool with no output schema, the description covers the essentials: what it returns and in what order. It is slightly thin on whether the list is unbounded or paginated, which is the one thing an agent might need before calling it.

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

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

The tool takes zero parameters, so there is no parameter semantics burden to carry; the baseline for a parameterless tool is 4. The description correctly does not invent argument documentation.

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

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

States a specific verb (list) and resource (saved designs), plus an ordering guarantee. It is clearly distinguishable from aikea_get_design (single fetch) and from aikea_list_options/list_fabricators by resource, though it never names a sibling explicitly.

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

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

Usage is implied by the verb: use this to enumerate saved designs before fetching one with aikea_get_design. There is no explicit when-to-use, when-not-to-use, or prerequisite guidance, and no mention of how this differs from aikea_design or aikea_build.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds where the list comes from ($AIKEA_HOME/fabricators.json or the AIKEA_FABRICATOR_WEBHOOK env var), which helps an agent reason about configuration state, but it says nothing about what happens when neither source exists (empty list vs error).

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

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

A single front-loaded sentence with the core action first and configuration sources relegated to a parenthetical. Nothing is wasted, though the file-path/env-var detail is closer to implementation trivia than selection-relevant information.

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

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

For a zero-parameter read-only list tool with readOnlyHint covering safety and no output schema required, the description covers the essential purpose and data source. The only gap is whether the result is an empty list or an error when no fabricators are configured.

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 and the schema is trivially complete, so the baseline of 4 applies. There are no parameter semantics for the description to clarify or omit.

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

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

The description names a specific verb ('List') and resource ('CNC shops configured for quotes'), which is clearer than the bare title 'List fabricators' and tells the agent this returns quote-capable shops rather than, say, designs or options. It does not explicitly differentiate itself from siblings like aikea_list_options or aikea_list_designs, but the resource is distinct enough to disambiguate.

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

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

There is no statement of when to call this versus alternatives, nor any prerequisite or ordering guidance (e.g., call before aikea_request_quote or aikea_add_fabricator). Usage is only implied by the verb 'List'.

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

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

readOnlyHint=true already establishes this is a safe read, so the bar is lower. The description adds workflow context (call first) but says nothing about return volume, pagination, or whether results are static/cached. Adequate but not rich.

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

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

Two short sentences, zero waste, with the resource and the ordering instruction front-loaded. 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?

With no input schema properties and no output schema, the description carries the burden of explaining what the agent gets back, and it does list the returned categories. It could mention scope or freshness, but it is sufficient for a simple discovery call.

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

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

The tool takes zero parameters, so the baseline is 4. The description enumerates what the (implicit) result set covers, which is the only semantic content available for a parameterless listing call.

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

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

States a specific verb (List) and resource (furniture templates) plus the categories of data returned (parameters, board materials, joinery methods, load presets). It is clear what the tool does, though it does not explicitly contrast itself with sibling list tools like aikea_list_designs or aikea_list_fabricators.

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?

"Call this first" gives explicit sequencing guidance relative to the other aikea_* tools, which is valuable for a discovery-listing tool. There is no when-not guidance or named alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, and the description is consistent with a safe read operation. It usefully adds that the optional step is 1-based and that newly added parts are highlighted and labelled, but says nothing about the return medium (image data vs URL) or rendering cost, which matters with no output schema.

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

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

A single well-formed sentence that front-loads the core action and packs the step semantics and highlight behavior into the remainder. No filler or redundancy.

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

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

With no output schema, the description should say what the caller receives (image bytes, URL, file path), but it leaves the return value unspecified. Combined with the undocumented design_id, the definition is adequate but incomplete for a two-parameter rendering tool.

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

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

Schema description coverage is 0%, so the description carries the burden for both parameters. It explains step well (1-based index selecting a single assembly step) but never clarifies design_id, leaving half the parameters undocumented in both schema and prose.

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 (render) and resource (isometric preview of the finished piece or a single assembly step) plus the distinguishing behavior of highlighting and labelling newly added parts. An agent can differentiate this visualization tool from siblings like aikea_get_design or aikea_build without opening the schema.

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

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

The description implies usage (call it to visualize a design or a build step) but never states when to choose this over alternatives such as aikea_get_design or aikea_build, nor any preconditions like requiring the design to already exist. Guidance is inferable but not explicit.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: it may build the design first, the webhook POST is conditional ('when one is configured'), and it always returns a ready-to-send RFQ email with to/subject/body plus a zip path. It omits permissions/auth expectations and what happens on webhook failure.

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

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

Two sentences, front-loaded with the core packaging behavior and finishing with the actionable imperative, with no filler. Slightly dense but every clause conveys a distinct behavior.

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

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

Against 11 parameters, 18% schema coverage, nested objects, no annotations, and no output schema, the description leaves most inputs (design_id, fabricator_id, finishing, needed_by, delivery/edge_banding/hardware_kit defaults) unexplained. It handles the return shape well but is incomplete for a tool of this complexity.

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 only 18% across 11 parameters, including a nested customer object and several boolean flags (delivery, edge_banding, hardware_kit) with defaults that are never explained. The description only alludes to quantity and contact details via the confirmation instruction, adding almost no semantics 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 ('Package a design for a CNC shop', 'POSTs the RFQ') and enumerates the concrete side effects, which cleanly separates it from siblings like aikea_build or aikea_preview. It stops short of naming an alternative tool, so it is clear but not fully sibling-differentiated.

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 a real precondition ('Confirm quantities and contact details with the user before submitting') and a conditional ('when one is configured'), which is more than pure implication. However, it never says when to reach for this tool versus aikea_build or aikea_preview, nor when not to use it.

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

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

readOnlyHint=true already tells the agent this is a safe calculation. The description adds the model assumptions (uniformly loaded, simply supported), which is genuinely useful for judging validity, but says nothing about units, whether the result is an estimate with error bounds, or what the tool returns.

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

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

One sentence plus a short clause, with the core action and its modeling assumption front-loaded. 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 4-parameter calculator with no output schema and half the parameters undocumented, the description leaves real gaps: undefined material values, no units, and no indication of what the returned deflection looks like. It is workable but not complete.

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

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

Schema description coverage is only 50%: span and depth carry descriptions, but 'load' (enum light/books/heavy) and 'material' (default plywood_18) are undocumented in both schema and description. The description contributes no parameter meaning at all, so it fails to compensate for the coverage gap.

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 ('estimate deflection') and a precise resource scope ('uniformly loaded shelf, simply supported'), which no sibling tool covers. It does not name or contrast with siblings such as aikea_design, but the domain specificity makes overlap unlikely.

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?

'Useful for choosing widths/materials before designing' gives clear context for when to reach for this tool and implies the workflow step relative to aikea_design. It stops short of naming an alternative tool or stating when not to use it.

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