Maker Machines Atlas

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description adds valuable calculation boundaries by disclosing the absence of tax/wage deductions and sales prediction. It still does not describe result format or edge-case handling, but it adds real context beyond annotations.

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

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

Two sentences, front-loaded with the purpose and followed by key exclusions; no wasted wording. It is appropriately sized for a calculation 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?

For a 13-parameter calculation tool with full schema descriptions and no output schema, the description names the computed outputs and the major assumptions/exclusions. It could be richer about the returned result shape, but it is broadly 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 coverage is 100%, so the schema already documents all 13 parameters, including currency and zero-value semantics. The description adds no parameter-specific syntax, defaults, or constraints beyond 'explicit user inputs', leaving this at the 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 opens with a specific verb and enumerates the computed quantities (profit, break-even sales/months, capacity), and the tool name adds Etsy payback context. It does not explicitly differentiate from calculate_maker_price or calculate_laser_setup, so it stops short of 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 signals that inputs must be explicit user-provided figures and rules out tax/wage deductions, predicted sales, and prefilled Etsy fees. However, it never names a sibling alternative or gives an explicit when-to-use trigger, so usage is only implied.

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 annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful input-contract details, notably that all eight checklist entries must be included and that unknown costs should be null rather than assumed zero, but it does not describe the return value or calculation 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?

The description is two focused sentences with the core operation front-loaded and no wasted wording. The follow-up sentence adds a concrete input rule without bloating the 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?

For a calculation tool with no output schema, the description should explain what result is returned, but it does not. It does cover important input constraints, yet leaves gaps around machineId and how the computed setup cost is presented.

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%, so the description should compensate more. It repeats the null-versus-zero rule already present in the cost schema and does not explain machineId or the included boolean, leaving key parameter meaning undocumented.

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: add a machine quote and accessory costs in one currency. It is clear what the tool computes, but it does not explicitly distinguish itself from sibling calculators such as calculate_maker_price or compare_machines.

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 explicit when-to-use guidance or comparison to alternatives. The implied use case is calculating a total laser setup cost, but the description never says when to choose this tool over the other calculate_* 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, non-destructive behavior, and closed-world scope. The description adds useful scope behavior by ruling out fee lookup and currency conversion and by framing the result as a "starting" price, but it does not describe the return format, rounding behavior, or calculation formula, which is a gap given there is 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?

The description is two compact sentences with no wasted language. The purpose and the key scope constraints are front-loaded, making it easy to parse quickly.

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 calculator with full schema coverage and strong annotations, the description adequately explains what the tool computes and its explicit-data-only scope. It is slightly incomplete because it does not describe the return value or calculation result shape, though the tool name and description make the output concept reasonably clear.

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 11 parameters in detail. The description summarizes the input categories (costs, minutes, hourly costs, fees, buffer) but adds no parameter-level syntax or format details beyond what the schema provides.

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 ("Calculate") and a precise resource ("a starting selling price"), and it distinguishes the operation from sibling tools by focusing on explicit costs, minutes, fees, and a profit buffer. An agent can tell this is a pricing calculator rather than a payback, setup, comparison, or lookup tool.

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

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

The description gives clear context: use explicit per-item costs, minutes, hourly costs, fees, and a profit buffer. The clause "No fee lookup or currency conversion" provides a useful scope exclusion, though it does not explicitly name alternative tools or state when-not-to-use conditions beyond that exclusion.

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 and closed-world behavior, so the bar is lower. The description still adds real value beyond them: it enumerates what the comparison returns (dated specifications, setup requirements, strengths, limitations, sources) and states an explicit behavioral constraint — no overall score or invented compatibility — which is a meaningful guardrail an agent could not infer from structured 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 and scope, followed by the output dimensions and the negative constraint. Every clause carries information; nothing is redundant padding.

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 usefully names the sections a comparison contains, so an agent knows what to expect back. Gaps remain around the language parameter and ID validation behavior, but for a simple read-only two-parameter tool the core picture is 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 0%, so the description must carry parameter meaning. It partially does for machineIds (two to four known IDs), though the schema already encodes minItems/maxItems, and it never mentions the lowercase-hyphen ID format. The language parameter is not mentioned at all, leaving a required-to-call choice undocumented.

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 (compare machines) and pins the scope: two to four *known* machine IDs, compared across named dimensions. The word 'known' implicitly separates it from the discovery sibling find_machines, but that sibling is never named, so differentiation is inferred rather than stated.

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?

'Known machine IDs' implies the caller must already have IDs (i.e. obtained via find_machines), and the 2-4 range is clear. However, no explicit when-to-use/when-not guidance or named alternative appears, and nothing says what happens if an unknown ID is supplied.

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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real substance: it discloses that results are cautious guidance with cited sources and explicitly disclaims certification of safety or exact machine compatibility — a meaningful caveat the 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?

Three short sentences with no filler, and the core action is front-loaded. The middle sentence about unknown material could be placed even earlier since it is the highest-value operational rule, but nothing is wasted.

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-enum, read-only lookup with no output schema, the description covers enough: what comes back (guidance plus sources), the safety caveat, and the unknown-material stop condition. It does not sketch the shape of the returned guidance or how sources are presented, which would help further, but the essential call-time information 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 0%, but both parameters are fully enumerated and largely self-describing (cut/mark, wood/leather/etc.). The description contributes the one genuinely non-obvious semantic — that material='unknown' should halt the workflow — but says nothing about how task interacts with material or how results differ per combination.

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 verb ('Return') plus the resource ('source-level laser/material/task guidance and sources') make it clear this is a lookup, not a calculator, which implicitly separates it from siblings like calculate_laser_setup or compare_machines. The wording is somewhat jargon-heavy ('cautious source-level'), but an agent can still tell what it retrieves.

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?

One usage rule is explicit: 'Unknown material means stop,' which tells the agent what to do for the 'unknown' enum value. However, nothing explains when to prefer this over calculate_laser_setup or the other material/machine siblings, so the routing between tools is left 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds two genuinely non-obvious rules: unknown requirement values never satisfy an explicit filter (conservative matching, so results are a floor not a ceiling), and market links are not a stock/availability signal. Still silent on pagination behavior, result ordering, and whether prices are converted or raw reference values.

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 compact sentences, no filler, with the filtering scope front-loaded and the two caveats trailing. 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?

A 16-parameter, fully optional filter tool with 25% schema coverage and no output schema needs more: nothing says what a result record contains, how 'reference price' relates to currency, or that limit caps at 20 and offset at 1000. The two caveats given are high value, but the parameter surface is largely undescribed.

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 25% across 16 parameters, so the description needs to compensate and does so only partially: 'reference budget' usefully implies maxReferencePrice is non-binding, and 'buying-link market' explains the market enum's meaning. But scale, limit/offset, search, currency, language, minPowerW, minWorkWidthMm, and software get nothing, and 'process'/'material/use' map to the enums only by guesswork.

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 ('Filter') and resource ('researched machines') plus the dimensions filtered on (process, material/use, budget, market, workshop requirements). It is clearly a search/list tool rather than a calculator like the siblings, though the vocabulary ('process', 'workshop requirements') does not map 1:1 to the schema's 'category'/'ventilation'/'enclosed' fields, so the match takes a small 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?

No statement of when to use this versus compare_machines, find_laser_material, or get_buying_options, and no prerequisites. The two sentences present are matching semantics, not usage guidance. The agent must infer that this is the discovery step that precedes comparison/pricing 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real value beyond them: it discloses affiliate disclosures, dated observations (data freshness caveat), and that it does not verify live stock or transact.

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 dense sentences with the primary purpose front-loaded and the caveats trailing. No filler, nothing restating the tool name.

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 3-parameter read-only tool with no output schema, this covers purpose, data provenance, and negative capabilities well. The only meaningful gap is guidance on the optional language parameter and whether market constrains 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 description coverage is 0%, so every parameter's meaning rests on the description. "Explicitly chosen buyer country" usefully clarifies that market is the buyer's country (not a store location) and "one machine" scopes machineId to a single ID, but the language parameter, its default, and the relationship between market and language are entirely unaddressed.

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 precise verb+resource ('Read existing retailer links') scoped to one machine and one buyer country, which cleanly separates it from the sibling calculators and finders. An agent knows exactly what this returns without opening the schema.

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

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

"For one machine and an explicitly chosen buyer country" tells the agent the required input shape and implies no bulk or inferred-market lookups. "Never purchases or confirms live stock" sets a clear boundary, though no alternative sibling is named for related needs (e.g., machine comparison).

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