Costable — Parametric Should-Cost Analysis

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

With zero annotations, the description carries the full burden of behavioral disclosure. It does disclose a genuine behavioral trait — that the tool searches the materials database by name rather than requiring exact IDs — which is useful. However, for a mutation tool it stays silent on important behaviors: whether adding a duplicate material is an error or a no-op, whether changes are persisted immediately, how multi-match or zero-match searches are handled, and what the response contains. Credit for the search semantics, but an agent can't predict the tool's behavior on edge cases.

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: the first front-loads the purpose, the second carries the key behavioral trait. Every word earns its place and there is zero fluff or redundancy with the schema. A third sentence on error/return behavior would have earned a 5, but as written it's efficient and well-ordered.

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 tool with 5 params (3 required), no output schema, and no annotations, the description is functional but not comprehensive. It communicates the essential flow — add a material, searchable by name — and the schema carries parameter documentation. However, for a mutating operation, the lack of any stated expectation about return values, idempotency, or validation behavior (e.g., what if materialQuery has zero matches?) leaves an agent without enough to anticipate failures. It's adequate for the happy path but falls short of what a well-rounded mutation tool description should cover.

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%, with each of the five parameters already well-explained (e.g., modelId references create_cost_model, qty and scrapFactor state their defaults, materialQuery has examples). Per the rubric, a baseline of 3 applies. The description's 'Searches the materials database by name query — no need for exact IDs' does add marginal meaning by confirming materialQuery is fuzzy-match, not an identifier — a useful clarification that justifies the baseline rather than below. But there's no additional parameter semantics in the description that goes beyond what the schema already says.

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?

Uses a specific verb+resource ('Add a material (BOM line) to an existing cost model') and adds the search-by-name behavioral differentiator, which cleanly distances it from the exact-ID workflow an agent might assume. Together with the sibling name add_process_to_model, an agent can immediately tell which tool handles materials vs. processes. The 'no need for exact IDs' clause is the kind of behavioral detail that makes the purpose unambiguous.

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 intended use case — adding a material to a model by name — is implied and correct, but the description never explicitly states when to prefer this over related siblings like add_process_to_model or search_materials, nor does it mention any when-not-to-use conditions. An agent could infer 'materials go here, processes go to the other one,' but that inference rides on sibling tool names rather than anything the description states. There is also no mention of what happens if the materialQuery returns no results or multiple results, which is a meaningful usage gap for a fuzzy-search mutation.

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 provided, the description must carry the full transparency burden. It adds the useful behavioral detail of a name-based fuzzy search, which is beyond what the schema states. However, it doesn't mention what happens on no match or multiple matches, nor the output of the operation, which would be helpful for a mutating 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?

Two sentences, each earning their place. The core action and the key differentiator (search by name) are front-loaded. No fluff or repetition.

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

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

For a mutation operation with no output schema, the description covers the basic operation and search behavior. However, it omits details that would be valuable for an agent, such as return values, error conditions (e.g., model not found, no process match), or whether this modifies an existing step or appends. Given the tool's 6 parameters, a bit more context would improve completeness.

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 six parameters. The description's mention of 'name query' aligns with processQuery but doesn't add new parameter-level semantics beyond what's in the schema. The description adds no extra insight for other parameters like modelId or stepOrder.

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 clearly states a specific action ('Add a manufacturing process step') and target ('existing cost model'). It also explains the search-by-name mechanism, which differentiates it from sibling tools like 'add_material_to_model' and 'search_processes'. This is a concise, unambiguous purpose.

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 'Searches the process database by name query — no need for exact IDs' implies when this tool is appropriate (when you have a name, not an ID). While it doesn't explicitly name alternatives or exclusions, it provides enough context for an agent to avoid using ID-based tools. It stops short of a full comparison with siblings.

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. The description implies a read-only calculation by saying 'Run' and 'Returns', but does not explicitly state side effects (e.g., whether it mutates the model) or any prerequisites like the model having materials/processes. It discloses outputs but not error conditions or permissions.

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 a single sentence, immediately states the action and the returns, and avoids any redundant or filler content. Every word adds 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?

For a single-parameter tool with a clear schema and no output schema, the description sufficiently explains the purpose and return values. It lacks only mention of potential errors or prerequisites (e.g., that the model must exist), but this is largely covered by the schema field description. No major gaps remain.

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% (modelId documented as 'Cost model ID returned by create_cost_model'), so a baseline of 3 is appropriate. The tool description adds no additional meaning about the parameter beyond what the schema already states.

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 uses a specific verb-resource pair ('Run the Monte Carlo should-cost calculation on a cost model') and explicitly lists the outputs (P50, P80, P90, and cost breakdown). It clearly differentiates from siblings like estimate_part by focusing on a cost model rather than a part estimate.

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 the model must already exist via 'on a cost model' and the schema notes the ID comes from create_cost_model, but it does not state when to prefer this over alternatives like estimate_part, nor mention any exclusions (e.g., when a cost model is not ready). No explicit guidance for tool selection is given.

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

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

No annotations are provided, so the description carries the disclosure burden. It clearly states that the tool runs the cost model and returns P50/P80/P90 per country with a percentage delta vs baseline, giving the agent a solid picture of the output 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 sentences with no filler. The first sentence front-loads the action and purpose; the second states the return values. Every word contributes meaning.

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 two-parameter tool with no output schema, the description covers the core invocation context and the main return shape. The only minor gap is that 'baseline' is not defined, but this does not prevent an agent from correctly selecting and invoking the 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 100%, so the schema already fully documents both modelId and countries, including an example and maximum length for countries. The description adds little parameter-level meaning beyond reinforcing that countries are the comparison 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 action — running the cost model across multiple manufacturing countries simultaneously — and names the output (P50/P80/P90 per country and % delta vs baseline). This clearly distinguishes it from siblings like calculate_cost_model by emphasizing the multi-country comparison use case.

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 provides clear context: use this tool when you need to compare multiple manufacturing countries and identify the optimal sourcing location. It does not explicitly mention when not to use it or name an alternative, but the purpose clause is concrete enough for an agent to infer when it 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?

There are no annotations provided, so the description must carry the full burden of disclosing behavioral traits. It mentions it creates a model and returns an ID, but doesn't disclose side effects, such as whether creating a model modifies any existing data, or any required prerequisites (e.g., must be logged in, specific permissions). It also doesn't mention if the creation is reversible or if there are any constraints on the inputs beyond the schema. For a mutation tool, this is a significant gap.

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 concise, a single sentence that states the action and the return value. It's front-loaded with the main purpose. It could be slightly improved by including key parameter details, but it's efficient and easy to parse.

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?

Given the tool has 5 parameters with full schema coverage and no output schema, the description is moderately complete. It tells you what it does and what it returns, but for a creation tool with no annotations, it lacks information about preconditions, side effects, and error scenarios. The description is adequate for basic understanding but not comprehensive for all contexts.

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 schema description coverage is 100%, so all five parameters are documented with meaningful descriptions. The description adds no additional parameter meaning beyond what the schema already provides, so it relies on the schema. The baseline for high coverage is 3, and the description doesn't add extra context (e.g., interaction between parameters or typical values), so a 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 clearly states the tool's purpose: creating a new parametric cost model. It explicitly names the resource ('parametric cost model') and the verb ('create'), and it mentions the return value (model ID). However, it doesn't explicitly differentiate from sibling tools like estimate_part, which might also involve creating models, but overall it's clear.

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 the usage by stating the return ID is used by other tools, but it doesn't provide explicit when-to-use versus alternatives. It doesn't mention when NOT to use this tool, such as when a user might need to estimate a part directly (estimate_part). The guidance is implicit: it's for creating a model for later cost calculations, but no explicit exclusions or alternatives are given.

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

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

With no annotations provided, the description carries the full burden. It discloses output statistics (P50, P80, P90), input uncertainties (material price, labour rate, cycle time), and the operational context (per-unit cost-at-risk). This goes beyond a minimal definition, though it omits potential side effects or error 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 sentences capture the action, methodology, outputs, and use case without fluff. Information is efficiently front-loaded.

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?

The description covers purpose, method, outputs, and usage context, which is sufficient for a tool with only three well-documented parameters. Minor omissions like default currency or handling of unsupported country codes are non-critical given the clarity elsewhere.

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 parameters are documented in the schema. The description adds modest context by referring to 'natural language' but does not elaborate on batchQty or countryCode behavior beyond the schema. This matches the baseline for full schema coverage.

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 clearly states a specific verb ('estimate'), resource ('should-cost of a manufactured part'), and method ('Monte Carlo simulation'). It differentiates itself from siblings by noting this is for 'quick feasibility checks before building a full cost 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?

The description provides an explicit when-to-use directive: 'Use this for quick feasibility checks before building a full cost model.' However, it does not name specific sibling tools or enumerate when-not-to-use scenarios, leaving some routing 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?

With no annotations, the description carries the full burden. It usefully discloses coverage (16 skill levels, 25 countries) and sourcing (ILO/BLS/ABS), but it does not describe behavior for unsupported country codes, data vintage, or whether rates are averages/medians. This is a meaningful but incomplete 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?

Two sentences with no filler. The first sentence front-loads the action and resource; the second adds valuable coverage/sourcing context. Every sentence 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 low-complexity tool with one parameter and no output schema, the description covers what is returned, the unit, and the data scope. It could mention the behavior for countries outside the 25 covered, but the core information needed to call it correctly is present.

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

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

Schema description coverage is 100% and the single countryCode parameter is already well documented with an ISO example. The description adds no parameter-specific detail beyond restating the country context, so the baseline of 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?

The description states a specific verb ('Get'), a precise resource ('manufacturing labour rates ($/hr)'), and a clear scope ('for all skill levels in a given country'). This distinguishes it from sibling tools like compare_manufacturing_countries and search_materials without needing to inspect schemas.

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

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

The phrase 'in a given country' clearly implies this tool is for single-country labour rate lookups, which separates it from compare_manufacturing_countries. However, it does not explicitly state when not to use it or name alternative tools.

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 provided, the description must carry the behavioral disclosure burden. It effectively communicates the analysis nature of the tool and specifies the exact return shape, including the verdict scale and top challenges. It does not discuss side effects, but 'Analys' strongly implies a non-mutating operation.

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

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

The description is exactly two sentences: the first states the action and object, the second lists return values. It contains no filler, restates no schema details, and is front-loaded with the core purpose.

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 tool with no output schema and no annotations, the description provides sufficient context about inputs, outputs, and intended use. The only minor gap is a lack of explicit mention of edge cases or dependencies on Costable benchmark availability, but this is not critical 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 the input schema already fully documents all parameters. The description adds context about line-by-line analysis and negotiation output but does not materially enhance parameter understanding beyond the schema, which is the expected baseline.

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

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

The description clearly states the specific action: analyzing a supplier quote against Costable's should-cost benchmarks, and enumerates concrete outputs (delta percentages, verdict, top negotiation items). This distinguishes it from sibling tools like estimate_part or calculate_cost_model by focusing on quote review and negotiation support.

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 a clear use case: when an agent has a supplier quote and needs to evaluate pricing against should-cost benchmarks for negotiation. It does not explicitly name alternatives or exclusions, but the context is strong enough to route the agent correctly among siblings.

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 discloses the read-only nature and the return structure (name, category, price per kg, density, strength properties), which is useful. However, it omits ordering, empty-result behavior, and how limit interacts with a broad query.

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 with zero waste: the first front-loads the core purpose and scope, the second enumerates the return fields. 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?

Complete for a read-only search tool with three optional parameters and 100% schema coverage. Return fields are spelled out and the database scope is explicit. Remaining gaps (ordering, default behavior when query is omitted) are minor and do not block 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 coverage is 100%, so limit, query, and category are each documented in the schema with descriptions, defaults, and examples. The description adds LME-pricing context but no parameter-specific semantics beyond what the schema already provides, matching the baseline of 3.

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') and a specific resource ('the Costable materials database') with scope detail (37 materials, LME-sourced pricing). Because one sibling is literally search_processes, the materials-vs-processes distinction is immediate and clear.

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 guidance on when to use this tool versus alternatives. The sibling search_processes implies a materials-vs-processes split but is never named, and no conditions, exclusions, or complementary-tool hints are given. An agent must infer usage purely from the name.

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 itself. It clearly indicates this is a read/search operation and lists what is returned (name, category, machine rate, cycle time model) and the fixed database size of 41 processes. It does not detail search semantics like empty-query behavior or matching rules, but for a simple search tool this is reasonable.

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 delivers the resource, scope, and return shape with no filler. It is front-loaded and every part adds 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?

There is no output schema, so the description's list of returned fields is valuable. All parameters are optional and well-documented in the schema. The main missing contextual detail is what happens when no query or category is provided, but the overall definition is sufficient for an agent to use the tool 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 all three parameters already have meaningful descriptions in the schema, including examples for query and a full category list. The tool description itself adds no parameter-level meaning beyond the schema, so the baseline of 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?

The description states a specific verb ('Search') and a concrete resource ('the Costable manufacturing process database'), and it names the returned fields. It is easily distinguished from sibling tools like search_materials because the resource is explicitly a process database.

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 makes the intended use clear: find manufacturing processes by querying the process database. It does not explicitly state when to prefer this over search_materials, but the resource distinction gives adequate context. No exclusions or alternative routing are provided.

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