mfgcalcs

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

With no annotations provided, the description carries the full behavioral burden and does so exceptionally well. It discloses the deterministic/no-LLM behavior, the 'needs-clarification' resolution for ambiguous product-family ties, the guaranteed statistic metadata, the detail-mode differences, follow-up context handling, and the citation rule — all beyond what the input schema alone provides.

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 dense but not bloated; every sentence supplies a distinct, useful fact. Core purpose is front-loaded, behavioral invariants are grouped logically, detail modes are compressed into one sentence, and the example is a practical closing illustration. No words are 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?

Even without an output schema, the description gives enough to anticipate what responses will contain: resolution status, statistics metadata, citation behavior, and detail-level differences. It also explains follow-up semantics and engine compatibility, making it complete for an agent deciding how to invoke and interpret this 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 coverage is 100%, but the description still adds meaningful semantic value: it explains how 'detail' modes behave, clarifies that context must come from a previous response, and gives a complete example query. This exceeds the baseline 3 for fully covered schemas, though it does not deeply explain query constraints or edge cases.

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 resource: 'Answer a natural-language U.S. manufacturing question from live committed data.' It also differentiates itself from typical LLM tools by stating it is 'deterministic, no LLM,' which clearly separates it from sibling tools like lookup_tariff and the get_* metadata/search tools.

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

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

The description strongly implies when to use the tool — for natural-language manufacturing questions — and gives a concrete 'Try' example plus follow-up guidance for passing context. However, it never explicitly names alternatives or states when not to use this tool versus its siblings, so the usage guidance is implied rather than fully specified.

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 the work of revealing behavior. It discloses that results are cited, that the tool names facts it could not establish, and that it returns comprehensive facts relevant to the situation. It stops short of detailing any access, latency, or limitations, but the core behavior is transparent enough.

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 compact: it states purpose, contrasts with the alternative, explains a behavioral guarantee, acknowledges a limitation, and gives a sample input. Every sentence earns its place and the key guidance is 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?

For a single-parameter, low-complexity lookup with a schema that already documents the parameter, the description is complete. It explains what the tool does, how to phrase the situation, what output to expect (answered and cited facts), and what happens when it cannot establish facts.

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 gives a plain-words example for the `situation` parameter. The description adds further semantic value by reinforcing the situational framing and offering a second, distinct example ('sourcing bearings from china'), which helps agents understand the expected input style.

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: describing a situation to get every fact bearing on it, with answers and citations. It also explicitly distinguishes itself from the sibling tool `ask` by contrasting a situation-based briefing with a single-figure question.

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 direct when-to-use guidance: 'ask for one figure, brief for a decision.' It also clarifies the input framing by saying to describe a SITUATION rather than a question, and provides a concrete example starting with 'Try:'.

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 a useful quirk: 'requiresPositive marks a field whose documented minimum of 0 is really exclusive,' which helps interpret the output. However, it does not mention whether the operation is read-only, any side effects, or error conditions. The description adds some behavioral context but is not comprehensive given the lack of 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?

The description is concise (~50 words) and well-structured. It opens with the primary purpose, then clarifies a behavioral nuance, and ends with a concrete example. Every sentence adds value with no fluff. The structure front-loads the key 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 simple one-parameter tool with no output schema, the description adequately explains what is returned (inputs and formula) and includes the requiresPositive detail that aids interpretation. It also provides a try example. It does not explicitly state that it is read-only, but that is implicitly clear from the wording. Overall, enough for an agent to call it correctly.

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

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

The schema already provides full documentation for the 'tool' parameter (100% coverage), including an example. The description reinforces that the slug comes from search_calculators and shows a try example, but this is mostly redundant. The baseline of 3 is appropriate since the schema handles the parameter explanation.

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 retrieves a calculator's inputs and formula, distinguishing it from running or searching. It uses a specific verb 'Get' and resource 'calculator's inputs' and explicitly mentions 'before running it,' which contrasts with run_calculator. This makes its 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 description gives clear context: use this tool before running a calculator, and obtain the slug from search_calculators. It even provides a try example. It does not explicitly say 'use run_calculator for execution,' but the 'before running it' phrasing implies that. This is adequate usage guidance without being overly explicit about alternatives.

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 behavioral burden. It discloses that results come in order with a cursor, that it returns both published and revised observations, and that it shares an engine with other endpoints. It does not detail edge cases like rate limits or whether cursor offsets are stable, but it provides meaningful behavioral context beyond the raw 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 three sentences with no filler. The first sentence states the purpose and the result ordering/cursor mechanism; the second explains the polling use case; the third ties it to known endpoints. Every sentence earns its place, and the most important information is 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?

For a list/polling tool with no output schema, the description covers what it returns, the ordering, cursor mechanics, and relationship to sibling endpoints. It doesn't explicitly mention that no parameters are required or describe pagination behavior beyond 'bounded server-side' in the schema, but the provided context is largely sufficient for an agent to select and begin using 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 itself fully documents all five parameters. The description adds a bit of context by explaining the polling model (the 'since' parameter as an offset), but it does not add meaning beyond what the schema descriptions already provide. This meets 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?

The description states a clear, specific verb+resource: 'Get every published or revised observation in order with a cursor.' It distinguishes the tool by its cursor/offset polling model and explicitly compares it to related endpoints ('Same engine as /api/events and the vintage archive'). This allows an agent to understand what it does and how it differs from sibling tools like get_revisions or get_vintages.

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 explicit guidance on when to use this tool: 'Poll by offset instead of re-pulling series.' This conveys a clear use case compared to alternatives. It does not name a specific sibling tool as the alternative, but the context of 'polling' versus re-pulling makes the intended scenario clear. It lacks explicit 'when not to use' guidance, but for a data-retrieval tool this is adequate.

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 of behavioral disclosure. It goes beyond the schema by explaining the vintage-tracked asOf URL, the stable site identifier instead of a DOI, and notes that the payload indicates this lack of DOI. It does not mention error conditions or rate limits, but it discloses the key behavioral traits.

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 efficiently structured, leading with the core purpose and then layering essential context about the asOf URL and DOI absence. Every sentence earns its place, and the 'Same engine as /api/cite' note is a helpful reference without being redundant.

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 lack of an output schema, the description adequately explains what the tool returns (a citation, possibly with an asOf URL, and the catalogue when no dataset is provided). It doesn't detail the exact citation format, but for a citation tool this is a standard and acceptable gap. The description is sufficient for an agent to call it correctly.

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

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

The input schema already provides 100% coverage of both parameters, so the baseline is 3. The description adds minor semantic value by stating that 'dataset' comes from the catalogue and that omitting it returns the catalogue, which helps interpretation but doesn't significantly exceed what the schema describes.

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 it 'Get a ready-to-paste citation for an MFG Calcs dataset', identifying the specific verb and resource. It further distinguishes itself from siblings by mentioning the asOf URL behavior and the lack of a DOI, making its purpose unambiguous even without examining 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 gives explicit guidance on when to omit the dataset parameter to get the catalogue of citable datasets, which is a clear usage context. It doesn't explicitly mention when not to use this tool, but the sibling tools have distinct purposes (e.g., ask, get_calculator), so the appropriate context is clear.

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 transparency burden. It discloses that the data is derived from a 'committed data-status census,' that stale series are reported as stale, and it enumerates the honest state values (current | due | stale | unknown). This conveys read-only, non-live behavior without relying on 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?

Three sentences, each earning its place: the first defines the output contract, the second gives the decision-use case, and the third explains the data source and stale handling. It is front-loaded with the core purpose and contains 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 single-optional-parameter tool with no output schema, the description covers the return concept well: fields per series, possible state values, and the derived source. It could go slightly deeper on how 'due' vs 'stale' is determined, but it is complete enough for correct selection and 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?

The input schema fully documents the single optional parameter (series key, slug, title, or alias; omit for all series), so the description needs to add little. It does not add new parameter syntax or format details beyond the schema, landing at 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 uses a specific verb-resource pair ('Get the freshness contract for MFG Calcs' live data') and enumerates exactly what the result contains: cadence, latest period, age in days, and state. This scope is distinct enough from siblings like get_change_events or get_vintages that an agent can identify the tool's job without opening any schema.

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

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

The description gives clear context for when to call it: it 'decides answer from memory or call the tool' and is 'the cheapest way to know whether a re-sync is worth it.' It does not explicitly name alternatives or state when not to use it, but the decision trigger is explicit and actionable.

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 disclosure burden. It adds meaningful caveats: tariff targets are observed rates, origins are statistically associated not causal, and unsupported/dependent/conflicting fields return invalid params. Missing rate-limit or authentication detail, but the interpretive caveats exceed the baseline for a fetch 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?

Three sentences each earn their place: purpose, interpretive caveat, and schema-guidance plus a working example. It is front-loaded and efficient. The only issue is the second sentence is dense and slightly jargony, which is a minor readability cost.

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?

Complexity is high – ten parameters, a large oneOf switch over many index constants, and no output schema. The description points to schema branches and gives a concrete example, but it does not enumerate the available indexes, explain result shapes, or guide selection among overlapping artifact types. Without an output schema, this leaves the agent to infer a lot from the input branches alone.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by telling agents to consult the selected branch of the schema for accepted fields, offering a concrete runnable example (get_state_cost_index plus Ohio filter), and clarifying the tariff/origin semantic distinction – guidance that the parameter descriptors alone do not provide.

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?

Opens with 'Fetch a published MFG Calcs index...' – a specific verb plus a clear list of artifact types it can return. It communicates the tool's broad fetch-and-dispatch role, though it doesn't explicitly distinguish itself from sibling tools like get_revisions and get_vintages that overlap in the 'vintage' and 'revision record' categories.

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 vs alternatives guidance is provided. It never tells the agent when to prefer get_index over get_revisions, get_vintages, or lookup_tariff even though those are plausible competitors. The 'Try:' example and schema-branch advice address parameter usage, not tool selection.

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 full burden. It discloses that the tool takes no arguments, returns hashes/provenance data rather than compute output, and is read-only in nature. It clearly states the semantic limits of the verification (proves integrity/reproducibility, not data correctness). It doesn't mention performance or failure modes, but given zero annotations, it does substantially better than baseline.

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 dense but well-structured: it states what the tool returns, gives a concrete usage workflow, notes a caveat, and ends with an actionable instruction—all in four sentences. Nothing is wasted and the critical usage guidance is front-loaded after the initial purpose statement.

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-argument tool with no output schema and no annotations, the description is remarkably complete: it explains the return content (hashes, generator, page), provides the verification workflow, discloses limitations, and notes citation behavior. There are no ambiguity gaps for an agent invoking this 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 coverage is 100% and there are zero parameters, so the description is not required to explain any. The description correctly states 'Takes no arguments,' preempting any agent confusion about input. The baseline for 0-param tools is 4, and the description's explicit confirmation elevates it further since there is nothing left ambiguous.

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 pairing ('Get the MFG Calcs Provenance Manifest') and clearly enumerates what the manifest contains: SHA-256 hashes, generator, page, and git history for every indexed/ledger artifact. It distinguishes itself from sibling data-retrieval tools by being specifically about provenance/verification rather than data values.

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 explicitly says 'Use this to VERIFY a number before quoting it' and provides a concrete three-step workflow (re-hash for integrity, re-run generator for reproducibility, read git history for timestamp). It also gives an explicit caveat about what the tool does NOT prove (correctness of underlying government data) and instructs the user to cite the returned url.

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 delivers: it discloses append-only semantics, revision retention, Ed25519 signing, and what the no-series call returns (catalogue, keyId→publicKey map, yearly ledger URLs). The read-only archival nature is clear; no side effects or auth caveats are needed.

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 packed sentences, front-loaded with purpose, followed by usage behavior and a concrete example. Each sentence earns its place; 'Try: {}' is a useful shorthand for the no-series call. 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?

No output schema and no annotations, so the description must explain return behavior, and it does: entry fields, catalogue form, keyId map, ledger URLs, rolling window, and append-only retention. For a one-param, non-nested tool, nothing essential 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 covers series at 100%, so baseline is 3. The description adds the meaningful consequence of omitting series – returning the catalogue plus the keyId map and ledger URLs – which enriches the agent's understanding beyond the schema's type description.

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 ('Get') and a precise resource ('append-only archive of Ed25519-signed data receipts'), then details what each entry carries: claim, claimHash, signature, keyId, and the rolling-window scope. This gives a concrete, distinctive purpose even amid noisy sibling names.

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 call guidance: 'Call with no series for the catalogue plus the keyId→publicKey map and the permanent yearly ledger URLs,' and offers a concrete invocation hint ('Try: {}'). It provides clear context on parameter behavior, though it doesn't explicitly contrast with alternatives or state 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?

No annotations are provided, so the description carries the full burden. It discloses what is returned (old and new values, first-known date), the filtering behavior, the no-filter aggregate mode, and instructs the agent to cite the returned URL. It does not mention error behavior, authentication, or explicitly note that it is read-only, but the core behavior is transparent enough.

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

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

Three sentences with no filler. The purpose is front-loaded, the filter list is compact, and the usage directive and citation instruction are stated directly. 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?

With no output schema and no annotations, the description adequately covers return values, filtering, the no-filter behavior, and the intended use. For a read-oriented retrieval tool, this is sufficient for an agent to call it correctly without missing critical context.

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%, setting a baseline of 3. The description adds value beyond the schema by naming all four filters and, more importantly, explaining the non-obvious behavior when all filters are omitted: you get the full record and a per-series revision summary. This is extra context an agent would not infer from the schema alone.

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: get every restatement of a published figure, and enumerates the returned fields (old value, new value, first-known date). This clear scope distinguishes it from siblings like get_change_events, get_vintages, or get_freshness without needing to open 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?

It gives an explicit use case: use this tool to judge whether a recent print needs a revision caveat. It also clarifies that omitting filters returns the full record and per-series revision summary. However, it does not name alternative tools or state when not to use it, 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?

No annotations are present, so the description carries the disclosure burden. It reveals meaningful behavioral semantics: multiple entries per period indicate revisions, and the caller must cite the returned URL. It does not address permissions or rate limits, but for a non-mutating archive lookup these are minor.

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: first states purpose, second gives the three usage modes. 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 tool with no output schema and no annotations, the description covers the core invocation patterns, output interpretation, and a required follow-up action (citation). The only omitted details, such as limit behavior, are already covered by the schema.

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 already defines all three parameters with descriptions; the description adds relational semantics (asOf depends on series, and what each parameter combination returns). This goes beyond the schema's individual property descriptions.

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

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

Description opens with a specific verb and resource ('Get the MFG Calcs Vintage Archive') and clarifies the exact value: reproducing a series' value as of a past date before revisions. This cleanly distinguishes it from sibling tools like get_revisions or get_change_events, even without naming them.

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 explicitly lays out three invocation modes: series + asOf for snapshots, series alone for revision trail, omit both for catalogue. This provides clear when-to-use guidance for the tool itself, though it does not explicitly contrast with sibling tools or state exclusions.

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 discloses the digest's components, how restated values are listed separately, that empty days are reported with a reason and never padded, and that 'nothing moved' when the date hasn't advanced. This is rich behavioral context, though it does not cover return format or rate limits.

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 tightly structured: purpose first, a scannable list of contents, then usage guidance. Every sentence earns its place with no redundant or filler wording.

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 tool with no annotations or output schema, the description fully explains what the digest contains, when to call it, and how empty days are handled. The 'Try: {}' example confirms invocation, leaving no significant gaps for an agent.

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 has zero parameters and an empty schema, so there is nothing to explain. The description adds a 'Try: {}' invocation example, which is the only meaningful addition. Baseline for 0 parameters is 4.

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 'Get the daily what-changed digest for the newest data day' and enumerates its contents (new readings, restated values, projections, Market Wire editions), making the tool's purpose explicit and distinguishing it from the more specific sibling get_* tools.

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

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

It explicitly frames itself as 'the first call of an agent's day' and explains the 'if date hasn't advanced since your last look, nothing moved' check, providing clear when-to-use context. It does not name alternatives or when-not scenarios, but the digest role makes its usage intent obvious.

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 succeeds. It discloses data-source limitations ('USITC reference data, not a customs ruling'), legal non-effect ('do not establish entry liability'), and measurement caveats ('unit value is not a transaction price'). These are behavioral traits an agent needs before relying on the output.

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 dense and front-loaded with a purpose sentence followed by search modes, caveats, citation instruction, and an example. Each sentence contributes value, though the first sentence is a long list of domain-specific fields that could overwhelm some agents.

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's technical trade-data complexity and lack of an output schema, the description does a strong job: it lists returned fields, search modes, disclaimers, citation requirement, and an example. Some terms like 'HHI floor' and 'retained-board coverage' are left undefined, but this is likely acceptable for a specialized tariff lookup.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates the schema's query semantics and adds an example, but does not meaningfully expand on limit or query format beyond what the schema already 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 begins with a specific verb and resource: 'Look up U.S. manufacturing import tariffs', and then enumerates the exact data elements returned (HTS fields, Chapter 99 references, effective duty rate, customs unit value, source shares, HHI). It clearly distinguishes this tariff look-up from the broader sibling tools such as search_site, run_calculator, or ask.

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 practical usage guidance: search modes ('Search by keyword, family, or HTS code'), a concrete example ('Try: {"query":"steel"}'), and a required action ('Cite the returned url'). It does not explicitly name alternatives or state when not to use this tool, 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 a thorough job. It discloses the use of the HiGHS solver, guaranteed exact optimum with dual prices, reproducibility of the LP text, and the need to cite the returned URL—none of which are derivable from the input 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 dense but every sentence contributes: purpose, solver guarantee, questions answered, input format, example, no-arg behavior, reproducibility, and citation requirement. It is front-loaded and contains 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 3-parameter tool with no output schema, the description covers the essential outcomes: allocation, dual prices, binding constraints, echoed LP text, and a returned URL. It does not fully specify the response structure, but the key behaviors are disclosed well enough for an agent to call and interpret 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?

Although the schema already describes all three parameters (100% coverage), the description adds critical semantics: the landed cost formula, the optional supplier fields, interpretable examples, and the behavior when suppliers are omitted. This materially enriches parameter understanding.

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: solve the cheapest legal supplier mix as a real linear program and return the exact cost-minimizing allocation. It also explicitly contrasts with heuristic ranking, which distinguishes it from other calculation tools in the sibling list.

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 clearly communicates when to use the tool: when splitting volume across suppliers under demand, capacity, and diversification constraints. It also explains the no-arguments invocation for documentation, but does not explicitly discuss when not to use it or name alternatives.

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 fully carries the burden, and it does well: it discloses that inputs are validated against min/max and impossible values are refused by name, and that derivation.confidence grades the output with 'none' for incomplete computation. It also notes the citation URL should be shared, which is a behavioral expectation. It does not explicitly state read-only nature, but for a calculation tool that is implied and no contradiction exists.

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

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

The description is moderately lengthy but every sentence carries weight: purpose, input handling, output content, validation, confidence grading, and an example. It is front-loaded with the core action and then flows logically into supporting details. The structure is effective, though slightly verbose; it could trim some phrasing, 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 tool with no output schema, the description provides a remarkably complete picture: it lists the return elements (labeled results, units, formula, citation URL), the confidence field's meaning, and a concrete example. An agent can confidently invoke this tool and understand what to expect. No significant gaps remain 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 coverage is 100% (both parameters and the nested inputs object are described), so baseline is 3. The description adds significant value beyond the schema by explaining how to reference input keys (field key or slugified label), that defaults are applied for missing inputs, and that validation occurs—details not present in the schema. This helps the agent construct valid and complete input objects.

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 ('Run') and resource ('manufacturing calculation') and immediately clarifies what that means: executing a calculation with inputs and defaults, returning results, formula, and citation URL. It also distinguishes itself from sibling tools like get_calculator (which likely retrieves calculator metadata) and search_calculators (which finds calculators) by focusing on execution.

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?

Explains how to provide inputs (by field key or slugified label) and points to get_calculator for details. It explicitly mentions that missing inputs use defaults, giving the agent a clear path for validation. The example call further demonstrates usage. While it does not explicitly state 'use this when you want to perform a calculation,' that is strongly implied, and it effectively guides the agent on the prerequisites and expected flow.

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 behavioral disclosure burden. It establishes the tool as a non-destructive search operation, describes that it returns matching calculators with slugs, and gives a realistic example. It does not mention pagination or empty-result handling, but those are minor for this 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?

The description is compact, front-loaded with the main purpose, and every sentence serves a real end-user need. The example JSON snippet is useful without bloating the description.

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 search tool with only two parameters, full schema descriptions, and no output schema, the description provides enough: what is searched, the scope of search, the return payload's key fields, and a concrete query example. Nothing critical is missing for correct selection and 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 schema itself documents both query and limit. The description adds a useful example and a list of content categories but does not meaningfully extend parameter 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?

The description clearly states that the tool searches MFG Calcs' library of 5,000+ manufacturing calculators and lists broad categories. It also explains the key output—matching calculators with tool slugs for run_calculator—which distinguishes it from sibling tools like get_calculator and run_calculator.

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: this is the discovery/search entry point, and its result is meant to feed run_calculator. The example query 'OEE' gives an agent a concrete model for invocation. However, it does not explicitly state when to prefer this over get_calculator or search_site.

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 disclosure burden. It is transparent about what the tool searches, that results are typed matches, and that the returned matches include URLs to cite. It could add more about pagination or exact return shape, but for a search tool this is sufficient.

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 three tight sentences with no wasted wording. It front-loads scope, adds supporting examples, gives a sample query, and includes the sibling routing all in a compact, readable format.

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 there is no output schema, the description helpfully explains that results are typed matches with citing URLs. It also names the main alternative tool and gives concrete example queries. It could describe the resulting match fields more fully, but the description provides enough operational context for an agent to correctly invoke 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 baseline is already 3. The description offers a useful concrete example query and confirms the tool is broadly queryable, but it does not add substantial parameter meaning beyond what the schema already provides for 'query' and 'limit'.

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 precise resource ('everything on mfgcalcs.com beyond calculators'), then enumerates covered content types (economic series, tariffs, state data, categories, datasets). It also explicitly differentiates itself from search_calculators, so an agent can distinguish the tools without inspecting 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?

It clearly says when to use this tool: for anything beyond calculators. It explicitly routes agents to search_calculators for the calculators themselves, providing the key alternative callout. This leaves no judgment call about overlapping scope.

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