Next Everything

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

With no annotations, the description carries the full load and does well: it discloses the state change ('Becomes the project's current BOM') and the side effect of creating a project when project_id is absent, plus the JLCPCB fee implications of assembly=true. It does not cover failure modes, latency for large BOMs, or whether re-checking overwrites a previous BOM.

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

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

It is front-loaded with the core action and every sentence carries distinct information, but the whole thing is a dense run-on with the side-effect and return-value details buried mid-paragraph. Some clauses (the parenthetical about a distributor-named pack) read as internal notes rather than agent-facing 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?

For an 8-parameter mutation tool with an output schema, the description covers what it computes, what it changes, how it links to projects, and what the caller needs back (quote_id, dashboard_url). 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 100%, so the baseline is 3, but the description adds real meaning beyond the schema: boards interacts with price breaks and MOQ, assembly gates extended-part fees and no-fee alternatives, and a 'Pack size' column changes ordering to whole packs. That is genuine semantic value, though the pack-size behavior is not tied explicitly to a named parameter.

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 chain (match, price, flag) on a specific resource (BOM lines), and enumerates the exact problem classes it detects. It is clearly distinguishable from find_parts, find_alternatives and place_order, which it references by name.

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 strongly implied by the workflow hooks: it returns a quote_id 'for place_order' and becomes the project's current BOM, so an agent knows it sits between create_project and place_order. It never states explicit exclusions (e.g. when to use find_parts instead for a single lookup), which keeps it off 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?

With no annotations, the description carries the behavioral burden and does disclose the key side effect: this creates a live page where the user sees the BOM, 'every step you take', quotes and orders — an important transparency signal that the project is user-visible. It omits auth/permission requirements and idempotency (what happens if called twice for the same build), keeping it out of 5 territory.

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

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

Three short sentences, front-loaded with the action and scope, then the return values, then the workflow instruction. Every sentence carries distinct information and nothing repeats the title or 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?

Even though an output schema exists, the description usefully explains the two return values in user-facing terms (dashboard_url is a live page, project_id threads through later calls). Combined with full schema coverage, the definition is nearly complete; only permission/duplicate-creation behavior is unaddressed for a mutation tool with no annotations.

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

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

Schema description coverage is 100%, so all three parameters (name, reason, description) are already fully documented with examples, and the description adds no further semantics about them. Baseline 3 applies when the schema does all the heavy lifting.

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 project') and pins the scope to 'one hardware build', which is unmistakably different from the BOM, parts, and order siblings. It also names the two returned identifiers, so the agent knows exactly what artifact it produces.

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 downstream usage: 'Give the user the link and pass project_id to every later call for this build', which establishes this as the entry-point step of a workflow. It does not name a when-not-to-use condition or a concrete 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?

With no annotations, the description carries the full burden and does disclose real behavior: results are compared spec by spec, confidence is defined (high = every rule verified, medium = some spec unreadable), and categories without rules degrade to 'unverified similar parts' that are clearly marked. It does not state that the call is read-only or whether results are ranked, but the verification/confidence semantics are the substantive part and they are covered.

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

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

Three dense sentences, front-loaded with what the tool returns before explaining confidence levels and the no-rules fallback. No filler, though the parenthetical spec list is slightly list-heavy for the value it adds.

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 7-parameter tool, completeness largely rests on the schema (86% described) and the output schema, both present. The description fills the remaining conceptual gap — how 'compatible' is determined and what confidence means — leaving only minor gaps such as result ordering and the cost/latency of the verification.

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 86%, so the schema already documents part, qty, manufacturer, same_package, no_assembly_fee, and project_id. The description's spec list (voltage, current, tolerance, dielectric) describes the matching engine, not any parameter, so it adds little parameter meaning beyond what is already structured. 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+resource — compatible replacements for a part, validated spec by spec (value, polarity, voltage, current, tolerance, dielectric). This is meaningfully distinct from the sibling find_parts (search) and get_part (lookup), though it never explicitly names those siblings as the alternative.

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: use it when you need to replace an existing part rather than find a new one. There is no explicit when-to-use/when-not framing, no mention of prerequisites (e.g., unresolved MPN, manufacturer disambiguation), and no routing to find_parts or check_bom.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses that results are restricted to in-stock items and that pricing is quantity-dependent, but it says nothing about latency, external supplier lookups, or whether results are cached/limit-capped. The live Mouser/DigiKey check behavior is documented only in the schema's query field, not here.

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 search capability and followed by the return summary. No hedging, no boilerplate, every clause carries 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 an 11-parameter retrieval tool with an output schema and 91% schema description coverage, the description covers the essential what-and-what-returns. It leaves the caller to the schema for filter semantics and doesn't address result limits or fallback behavior, minor gaps given the rich structured 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 91%, so the schema already explains qty, sort, limit, filters, package, category, min_stock, and manufacturer in detail. The description maps loosely onto query/category/package/filters and clarifies that price is at the requested quantity, but it adds no syntax, units, or defaults 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 ('search') plus the resource ('in-stock electronic components') and enumerates the search axes (part number, words, category, package, electrical specs). It also names what comes back (stock, unit price at quantity, specs, footprint availability), so the agent knows this is a discovery/lookup tool. It never names a sibling (get_part, find_alternatives) to sharpen the boundary, keeping it below 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?

The 'in-stock' framing implies this is for discovering available parts rather than retrieving a known part, but there is no explicit when-to-use statement. Nothing tells the agent how this differs from get_part (single-part fetch) or find_alternatives (substitution search), even though those are the obvious alternatives in the sibling set.

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?

No annotations are supplied, so the description carries the full burden. It does add real behavioral color ('warns when it keeps going out of stock'), which is genuinely useful context beyond a plain read, but it says nothing about failure modes for an unknown part number, or that supplying project_id links the call to a project dashboard (a side effect only the schema hints at).

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 whose subordinate clauses are all content items rather than filler. Dense but every phrase earns its place; only the parenthetical warning is slightly tacked on.

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?

An output schema exists, so the description did not need to enumerate return fields yet spends its whole length doing so, while omitting routing guidance against five sibling tools and the project_id side effect. Adequate to recognize the tool, incomplete for deciding when to call it.

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

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

Schema coverage is 75%, so the baseline is 3. The description's mention of a 'full price ladder' implies quantity-break pricing and therefore gives indirect meaning to the undocumented qty parameter, but it never addresses qty, manufacturer disambiguation, or project linking directly.

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 resource ('one part') and enumerates the exact payload: specs, offers with price ladder, datasheet, pinout, footprint, stock trend. The singular framing implicitly contrasts with the plural find_parts sibling, but no sibling is named, so differentiation is left to inference.

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

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

Usage is only implied: 'one part' plus the required identifier parameter suggests 'call this when you already know which part you want'. There is no explicit when-to-use, when-not, or pointer to find_parts/find_alternatives for discovery or substitution.

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 it does disclose the payload returned (status, history, payment link, tracking), which is useful behavioral context. However, it omits that this is a non-mutating read, any permission/auth requirements, how many 'recent orders' are returned, and pagination or ordering 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?

A single sentence, front-loaded with the data returned and ending with the alternative listing mode. It is dense but slightly run-on, packing two distinct invocation modes into one clause chain rather than separating them.

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?

An output schema exists, so return values need not be explained, and both params are schema-documented. What remains underspecified is mode precedence between the two optional params and the scope of the 'recent orders' listing — reasonable gaps but real ones for a dual-mode tool with no annotations.

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 both parameters are already documented, giving a baseline of 3. The description restates the dual-mode semantics (single order vs. recent list vs. project-scoped list) but adds no format or precedence detail beyond the schema — e.g., what happens if both order_id and project_id are supplied.

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

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

The description names the resource (an order) and enumerates the data returned — status, history, payment link, shipment tracking — plus the fallback listing mode for user or project orders. It is clearly a read/retrieval tool and implicitly the counterpart of the sibling place_order. It lacks an explicit verb ("get"/"retrieve"), which keeps it just 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?

The 'or the recent orders of the user or of one project' clause hints at the two modes, and the schema pins it down ('Omit to list the user's recent orders'). There is no explicit when-not guidance, no mention of exclusivity between order_id and project_id, and no pointer to siblings such as place_order for creating orders.

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 does substantial work by clarifying that nothing is charged, that the team re-checks live stock and price, that a payment link is emailed, and that the order appears in the project dashboard. It also flags the user-confirmation requirement, though it does not cover permissions, duplicate handling, or failure modes.

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

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

Three short sentences, front-loaded with the core action, followed by key side-effect clarification and the confirmation instruction. No wasted text.

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?

An output schema exists, so return values need not be explained, and the description covers the main behavioral risks: no immediate charge, team verification, email payment link, dashboard visibility, and required user confirmation. It could be slightly more complete by addressing duplicate or stale-quote scenarios, but it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description only implies that a quote is required and adds no additional parameter semantics beyond that, which is the expected baseline when the schema does the heavy lifting.

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: request an order for a quote. The description makes clear this is an order-request action, not a direct purchase, and distinguishes it from read-only sibling tools such as check_bom or order_status.

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

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

Gives a strong behavioral prerequisite: always confirm with the user before calling. However, it does not explicitly say when to use this versus alternatives like check_bom first or order_status afterward, leaving sequencing implicit through the quote reference.

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 so well: it discloses that the whole BOM is repriced, that a new quote_id is returned, and critically that older quotes of the project can no longer be ordered — an irreversibility warning most definitions omit. It also explains the verbose flag's effect and that reason is surfaced to the user in the activity log.

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

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

A single dense sentence with one parenthetical, front-loaded with the core action and scope before the side-effect and return-value details. Slightly overpacked with clauses, but each one carries distinct 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 13-parameter mutation tool with no annotations, the description covers the mutation surface, repricing side effect, quote invalidation, and response shape; an output schema also exists so return-value detail is not required. It stops short of covering error cases (e.g. invalid part or line number) and confirmation that unrelated lines are preserved.

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 each parameter well (qty=0 means do not populate, omitting line adds a new line, pack_size semantics). The description adds value by mapping user intents to parameters ('swap a line's part', 'change its quantity or pack size', 'add or remove a line', 'change the board count') and by restating the verbose contract, which is already in the schema.

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

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

States a specific verb (change) and resource (the project's current BOM) and enumerates the concrete mutations supported: swap a part, change quantity/pack size, add/remove a line, change board count. It clearly is not a read tool like check_bom or find_alternatives, but it never names a sibling to disambiguate routing 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?

The phrase 'without sending it again' implies this is the path for editing an existing BOM rather than re-uploading, and 'accept an alternative' hints it follows find_alternatives. However, there is no explicit when-to-use/when-not guidance and no stated prerequisite flow (e.g. call check_bom/lines_detail first to get line numbers).

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