Open Factory

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real behavioral context beyond that: the response bundles cited sources and CSV files, and paywalled articles return truncated text with an explicit notice rather than failing.

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, no filler. The core payload is front-loaded and the paywall caveat is appended where it belongs, so nothing needs to be skimmed past to find the main behavior.

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

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

With no output schema, the description still tells the agent what comes back (metadata, markdown, cited sources, CSV files) and how the paywall case differs. For a single-parameter read tool this is sufficient to call 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?

Only one parameter and schema coverage is 100%, so the schema fully documents the slug and its origin. The description's 'by slug' restates the schema without adding format or edge-case detail beyond it, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('get one Open Factory article by slug') and enumerates the payload: full metadata, markdown body, cited sources, CSV files. This clearly separates it from sibling search_articles, which is the discovery counterpart.

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

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

Usage is implied rather than stated: 'by slug' plus the schema note that the slug comes from search_articles or the URL tells an agent this is the fetch-after-search step. There is no explicit when-to-use/when-not statement or named alternative in the description itself.

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), so the description earns credit for adding context beyond them: the data provenance ('from filings and releases'), the freshness limit ('latest quarter'), and a monetization constraint ('Quarterly history is paid') that tells the agent historical requests will not be served for free.

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 returned metrics and scope, with the paid-tier caveat placed last where it belongs. The long OEM enumeration is dense but functional rather than filler; no sentence 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 no-required-parameter read tool with full schema coverage and no output schema, the description covers what is returned, which quarter, the source, and the paid boundary. The knowable gaps are minor – no explicit routing advice versus siblings and no mention of whether an empty oem returns all companies.

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?

With a single parameter at 100% schema description coverage, the schema already documents 'oem' as an optional company name filter; baseline 3 applies. The description adds indirect value by enumerating valid OEM names (Eaton, GE Vernova, Siemens Energy, ABB, Schneider, Vertiv, Powell, Caterpillar, Cummins, Trane), which hints at accepted filter values, but it never ties that list back to the parameter.

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

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

States a specific resource (orders, revenue, backlog, book-to-bill, backlog growth), the exact scope (electrical, power and cooling OEMs, with named companies), and the freshness window (latest quarter). An agent immediately knows what comes back. It does not, however, distinguish itself from sibling data tools like get_lead_times or get_price_bands, so it stops short of a 5.

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

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

Usage is only implied: 'latest quarter' tells the agent this is a current snapshot, and 'Quarterly history is paid' gates the historical use case. There is no explicit when-to-use statement, no prerequisites, and no named alternative among the sibling data tools. Adequate but leaves the agent to infer routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine context beyond that: the three-value scoring scheme (yes/partial/no) and the fact that every cell is backed by a source document, which tells the agent what the response contains.

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

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

Two tight sentences with no filler, front-loading the resource and its scoring scope before the parameter hints. The first sentence is dense but every clause identifies a distinct scored dimension, so little 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?

With no output schema, the description carries the burden of describing returns and does so adequately: a per-OEM yes/partial/no score with a backing document per cell. It omits pagination and how the OEM list is enumerated, but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100% and both parameters are already documented there, including the default false for cells. The description's phrasing 'evidence rows' adds only slight nuance over the schema's 'evidence cells', so the baseline 3 applies.

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

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

States a specific verb and resource ('get_disclosure_scorecard') and enumerates the exact disclosure dimensions being scored (dated lead-time schedule, list prices, backlog, capacity, delivery performance), which distinguishes it from data-returning siblings like get_lead_times and get_price_bands. An agent can tell this reports publication/disclosure status rather than the underlying numbers.

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 explains how to drive the tool ('Optional filter by OEM; set cells=true for the evidence rows') but never states when to choose it over alternatives such as get_lead_times or get_price_bands. Usage is implied by the resource rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so the safety and determinism profile is covered. The description adds only that values are 'current' and 'public' and that each carries a source document and date — useful payload context, but no disclosure about freshness cadence, historical availability, or result size.

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

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

A single sentence with zero filler. The scope ('every Open Factory model') is front-loaded and the parenthetical lists the payload without 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 carries the return-value burden and does name the returned metrics plus their source document and date. It still omits units/definitions for the metrics and whether the set of models is fixed, but it is adequate for a no-argument snapshot tool whose annotations already cover safety.

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

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

The tool takes no parameters, so per the rubric a baseline of 4 applies. The description correctly implies an unfiltered, complete dump rather than a filtered query, which is consistent with the empty schema.

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

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

States a specific verb+resource ('the current public headline number of every Open Factory model') and enumerates the five metrics the index covers. The 'every model' scope implicitly distinguishes it from the single-metric siblings (get_lead_times, get_book_to_bill, get_disclosure_scorecard), which return one metric at a time rather than a cross-model snapshot.

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 word 'current' implies a snapshot use case and 'every model' implies an overview use case, but the description never states when to reach for this tool versus the per-metric siblings. No exclusions or prerequisites are given, leaving the agent to infer the choice.

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 a safe, idempotent, closed-world read, so the bar is lower. The description adds real context beyond them: the 50 MW eligibility threshold, coverage of 15 utilities/markets, and that every cell is linked to a source tariff or docket, which signals provenance and auditability.

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

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

One dense sentence that front-loads the subject and the eligibility threshold before the field list and filter note. It is long but every clause carries information; only mild run-on structure keeps it from a 5.

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, and the description compensates by enumerating the returned fields (study fee, collateral per MW, minimum bill, contract term, ramp, exit fee, energization year) plus their sourcing. An agent knows what it will get and under what eligibility condition.

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 baseline is 3, but the description adds meaning: it clarifies the single filter accepts market, utility OR state values, which is broader than the parameter name 'market' alone suggests. No value syntax or case-sensitivity guidance is given.

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?

Names a specific verb and resource (what a 50 MW+ load pays to connect), states scope (fifteen US utilities and markets) and enumerates the returned fields. It is clearly distinguishable from siblings like get_tariff_rates, get_lead_times and get_price_bands.

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 notes the optional filter by market, utility or state, which implies the intended lookup use. However, it never says when to prefer this tool over related siblings such as get_tariff_rates or get_lead_times, and gives no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and a closed-world source, so the safety profile is covered. The description adds behavior the annotations don't: the unit of the returned value (weeks), that each row carries an OEM/publisher and a date (provenance freshness), and that some adjacent data is paywalled.

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, front-loaded with the payload (lead time in weeks) before the optional filter and the paywall caveat. Dense and mostly waste-free, though the long parenthetical class list is the only part that could be trimmed without losing much.

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 carries the return-value burden and does it: unit, granularity (per class), and per-row metadata are all stated, and annotations cover safety. It does not mention result size or whether the full class list is always returned, a minor gap for a filtering 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% on the single optional 'query' parameter, so the baseline is 3. The description adds real meaning beyond the schema's bare example by specifying the filter targets the class name (so the agent knows it filters rows by equipment class, not by OEM or date).

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

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

States a specific verb+resource pair ('Current published lead time, in weeks') and enumerates the exact equipment classes covered (transformers, switchgear, MCC, busway, gensets, ATS, drives). No sibling tool returns lead-time data, so the topical scope alone distinguishes it from get_price_bands, get_tariff_rates, get_large_load_terms, and the rest.

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 clear context for when this applies (factory and datacenter electrical equipment classes) and flags that 'Edition history and per-product OEM rows are paid', which tells the agent the boundary of what this call can return. It stops short of naming an alternative tool for the paywalled data, so it is not a full when/when-not/alternatives statement.

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 establish readOnly, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: the output composition (p25/median/p75/n/buyers/award-date range) and, importantly, the monetization rule that award rows with document URLs are paid. That paywall disclosure is not derivable from any structured field.

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 no filler: the first covers scope, classes, units and return fields; the second covers filtering, window semantics and the paywall. Front-loaded and efficient, though the first sentence packs enough clauses that it reads as a data dump rather than a lead 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?

There is no output schema, and the description compensates by enumerating the returned statistics (p25, median, p75, n, buyers, award-date range). With only two optional parameters and annotations covering the safety profile, an agent has what it needs to call this correctly; only pagination/result-size behavior is unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by defining the 'recent' enum value concretely (awards since 2024-01-01), which the schema only lists as 'all, recent or both (default both)'. It also clarifies that the class ids are discoverable from the result set, which the schema does not state.

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

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

The description names a specific resource (transaction price bands from public procurement awards), enumerates the exact asset classes covered (pad-mount and power transformers, MV switchgear, gensets, chillers) and the units of measure ($/kVA, $/kW, $/ton). This is far more specific than the sibling getters and an agent can immediately tell what data this returns.

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 explains how to narrow results ('Filter by class and window') and defines the 'recent' window semantics, which is useful invocation guidance. However, it gives no when-to-use vs when-not-to-use guidance and never references any sibling tool, so the routing decision is left entirely 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds domain context — that records carry a resolution date and a scored result, and that forecasts are scored against a public series — but says nothing about volume, pagination, or freshness, which matters for a tool that claims to return 'every' forecast.

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 with the resource content front-loaded and the filter directive last. No filler, though the parenthetical enumeration of forecast types is slightly list-like and could be trimmed.

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, and the description compensates by enumerating the returned fields (forecast, scoring series, resolution date, result). With rich annotations and a single optional parameter, an agent has enough to invoke this correctly; only pagination/volume behavior is unaddressed.

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

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

Schema description coverage is 100% and the single enum parameter is fully documented in the schema, including its default. The description's 'Filter by status' merely echoes that; baseline 3 applies when the schema does the heavy lifting.

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

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

The description names a specific resource — the archive of dated, checkable forecasts with their scoring series, resolution date, and result — which is more than a restatement of 'get_record'. It implicitly distinguishes this consolidated record from siblings like get_lead_times or get_price_bands, though it never names those siblings or states the contrast explicitly.

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

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

Only 'Filter by status' is offered as usage guidance; there is no statement of when to reach for this tool over the narrower sibling getters, nor any exclusion or prerequisite. Usage is implied by the content description rather than spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by enumerating what each row contains (the duty components and the instrument behind each rate), which matters because there is no output schema. It does not address auth or rate limits, so not a 5.

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, no filler: the first front-loads what the dataset contains and its coverage, the second covers filtering. Dense but every clause carries information; the parenthetical equipment list is long yet useful for matching queries.

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 compensates by naming the returned rate columns and the originating instrument, and the dataset is bounded at 22 lines so pagination details are unnecessary. What is missing is whether multiple origin rows are returned per HTS line or how partial matches behave.

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 each parameter already has an example, so the schema does the heavy lifting. The closing sentence echoes the three filter dimensions (HTS prefix, origin, description word) but adds no new syntax or format detail beyond the schema, which is the baseline-3 case.

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 (US import tariff rates) and pins the exact scope: 22 HTS lines for factory/datacenter equipment (transformers, switchgear, gensets, chillers, machine tools, robots) with MFN, Section 232, Section 301 and total ad valorem rates. That level of specificity clearly separates it from the other get_* dataset tools like get_price_bands or get_lead_times.

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 when the tool applies (US import tariff questions for this equipment class) and tells the agent how to narrow results via HTS prefix, origin, or description word. It never states when NOT to use it or names an alternative tool, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and a closed-world hint, so safety is covered. The description adds genuinely non-obvious behavioral context: the actual calculation happens client-side at the tool URL, so this tool yields source data rather than computed results — an important expectation-setting detail agents cannot get from the 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 lead sentence is reasonably front-loaded, but listing all eight enum slugs in the prose is pure duplication of the input schema and bloats the text. The second sentence about browser execution is useful but awkwardly worded and tacked on.

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

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

For a single-parameter read tool with full annotations and a fully-described enum schema, the definition is mostly adequate, and 'with every input's provenance' signals the shape of the return payload despite the absent output schema. However, it never clarifies what the returned table actually contains field-by-field or whether it can be empty for a given slug.

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 single 'tool' parameter has an enum plus a description ('Tool slug.'), so the schema already carries the semantics. The description restates all eight slug values verbatim, adding no format, default, or error-behavior detail beyond the schema — baseline 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 identifies the resource ('the source table one Open Factory calculator runs on, with every input's provenance') and the sibling set of calculators it applies to, but it never uses a retrieval verb and 'source table' is domain jargon. An agent can infer this returns underlying input data for a named calculator, but the phrasing is indirect rather than a clear verb+resource statement.

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

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

No when-to-use guidance is given, nor any exclusions or alternatives among the many sibling get_* tools. The trailing note about the calculation running in the browser hints at scope, but it is a caveat rather than routing guidance.

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, closed-world behavior, so the safety profile is covered. The description adds useful content-level context beyond that: results are grouped by article, carry download URLs, and rows retain a source column naming the originating filing/tariff/docket/award/series.

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 tight sentences, front-loaded with the resource and scope, then grouping/download detail, then the filter. Nothing is padding, though the final sentence largely mirrors the schema's parameter 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?

With no output schema, the description carries the return-shape burden and does so well, explaining grouping, download URLs, and the source column. It omits only secondary details such as result ordering, pagination, or total counts.

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 single 'query' parameter is fully documented in the schema. The description restates the same filter semantics ('article slug or topic word') without adding syntax, matching rules, or examples, so it neither compensates nor detracts.

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

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

The description names the concrete resource ('CSV files behind every chart Open Factory publishes'), how they are grouped (by article), and what comes with them (direct download URLs). This is specific enough to distinguish it from siblings like get_article, get_record, and search_articles, which return different content.

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 says the filter is optional and accepts an article slug or topic word, which implies how to scope results, but it never states when to reach for this tool versus get_article or search_articles. Usage is implied rather than directed.

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, closed-world and non-destructive, so the safety profile is covered. The description adds real value beyond that by disclosing the return shape (slug, URL, date, pillar, summary, and the CSV files behind charts) in the absence of an output schema. It does not discuss rate limits or result ordering beyond "best matches."

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 no filler. The capability statement is front-loaded and the follow-up routing detail is appended, so an agent gets scope first and navigation second.

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 carries the burden of describing results and does so concretely, including the slug handoff to get_article. For a three-parameter, read-only search tool this is sufficient to invoke and follow up 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 coverage is 100%, so the baseline is 3; the description earns an extra point by clarifying that the single query parameter absorbs many entity types (topic, equipment class, company, tag, series ID) that have no dedicated field in the schema. The limit and pillar parameters are left to the schema.

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

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

States a specific verb and resource ("Search Open Factory articles") and enumerates the searchable facets: topic, equipment class, company, tag, series ID. It also implicitly separates itself from the sibling get_article by noting the slug "identifies an article for a full-text read."

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 clear context for when to reach for this tool (broad lookup across several facets) and signals the follow-up path to a full-text read via the returned slug. It never names an alternative tool or states an explicit exclusion, so it stops short of full when/when-not routing.

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