Boring API

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: unreadable values become open cases rather than false 'unchanged', other device classes are refused, and it discloses its own validation limits ('a real pair with an actual value change has not been tested yet'). This is unusually candid behavioral disclosure.

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

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

Front-loaded with the trigger and reads as information-dense rather than padded, but it is one long run-on paragraph whose validation statistics and nested scope/limitation clauses make it heavy to scan. Every sentence earns its place, yet tighter structuring would improve it.

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 an output schema present, return-format details are unnecessary, and the description still covers scope, prerequisites, refusal behavior and known limitations. For a complex 11-parameter comparison tool, an agent has everything needed to decide whether and how to call it.

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

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

Schema coverage is 100%, so the nine input channels (file object, URL, path, base64 for each revision) are already documented. The description adds only that text-based PDFs may come via upload or URL and that older revisions are often on web.archive.org; it does not clarify precedence when multiple input modes are supplied or mention path/base64 modes, so it stays at the high-coverage baseline.

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

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

States a specific verb and resource ('Compares two revisions' of MOSFET datasheets) and enumerates exactly which parameters it reports (VDS, ID, RDS(on), etc.) with page/table-row/quote provenance. It also carves out a clear boundary ('discrete Si and SiC MOSFETs only') that separates it from sibling tools like table_diff or supplier_compare.

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?

Opens with an explicit trigger ('Use when a PCN or a new datasheet revision arrives...') and lists when-not via OUT_OF_SCOPE refusals for IGBTs, modules, diodes and gate drivers, plus a prerequisite ('Needs both revisions'). It does not name an alternative tool for cases it declines, so it falls just 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?

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantive behavior: a quality level per table, header/title/footnote detection, conservative cross-page merging ('only with evidence'), no-guess policy, and any-language support. That is real operational context beyond the hints.

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?

Front-loaded with purpose and limits, then behavior. Sentences are information-dense with no filler, though the first sentence stacks several facts (formats, size, page cap) and could be split for readability.

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

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

For a 7-parameter tool with nested objects, rich schema descriptions and an output schema, the description covers the remaining gaps (input modes, quality reporting, merge policy) plus a useful summary of return metadata (page, bounding box, quality level). Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by clarifying the accepted input channels ('PDF can be passed as upload or URL'), helping the agent choose between the four file-input parameters. It does not add detail on max_rows or the options object, which the schema already covers.

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 ('Extracts tables from a text-based PDF') and immediately bounds scope with formats, size (20 MiB) and page limit (60 pages). Sibling tools (merchant_validate, supplier_compare) are unrelated, so no differentiation is needed; the resource is 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?

Gives a clear condition for use ('text-based PDF... price list, data sheet, report') and an implicit exclusion: scanned pages return OCR_REQUIRED and 'nothing is guessed,' so the agent knows not to expect OCR. It does not explicitly name an OCR/alternative tool, but none exists among the siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces that with 'nothing is changed' rather than contradicting it. It adds substantive behavioral detail beyond the annotations: the exact rule classes checked (required fields, GTIN check digit, price format, duplicate IDs, Shopify variants) and the shape of the reported issues (row, column, rule code, fix hint). Rate limits, auth requirements and size limits are not covered.

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

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

Three dense sentences with the purpose, scope and the key output guarantee front-loaded. The long middle clause enumerating validation rules is information-rich but slightly list-heavy; still, nothing is padding and the essential facts come first.

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 an output schema present, the description is not obliged to explain return values, yet it still characterizes the issue payload, which is a bonus. Combined with full schema coverage, rich annotations and the profile/options enumeration, an agent has everything needed to invoke this validator correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the profile enum values and the options reference. The description only restates the three transport modes (upload, URL, CSV text) at a high level and does not add format or constraint details beyond the schema. 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?

States a specific verb and resource ('Checks a product feed or catalog export') plus the target platforms (Google Merchant Center, Shopify, Meta) and the pre-upload timing. An agent can immediately tell this is a read-only feed validator and distinguish it from siblings like documents_tables and supplier_compare, which serve different purposes.

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 'before upload' framing gives clear context for when to call this tool, and the accepted input formats (CSV, TSV, XLSX) and platforms narrow the use case further. It does not, however, name an alternative tool or state a when-not condition, so the routing guidance is contextual 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's remaining job is behavioral context, and it delivers: the 20 MiB size limit, that unclear values stay empty with an issue, that Shopify and Google output is validated against platform feed rules, and that the result includes summary, mapping, issues and CSV text. Not exhaustive on auth or failure modes, but well beyond 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?

Front-loaded with the conversion action and its output targets, and each subsequent sentence adds distinct information (input formats, normalization behaviors, validation, return contents) with no filler. It is long but dense rather than padded.

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 complex 8-parameter tool with nested objects and an output schema, the description covers inputs, targets, limits, transformation behavior and error handling. Since a return-value schema exists, the brief mention of the return payload is sufficient and nothing critical 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 description coverage is 100%, so all eight parameters (including the file object and the options blob) are already documented in the schema, including the target enum values and the NormalizeOptions pointer. The description adds only the source-format list and the notion of derived/default/missing columns, so the baseline of 3 applies.

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

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

States a concrete verb (converts) and resource (a product table/supplier list, ERP or shop export) plus all four supported output targets. An agent can distinguish this from merchant_validate and supplier_compare purely from the description, since this one builds an import file rather than validating or comparing.

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

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

The description makes the input formats (CSV, TSV, XLSX up to 20 MiB) and output targets explicit, which gives strong implied context for when to pick this tool. However, it never names or contrasts the sibling tools (merchant_validate, supplier_compare, documents_tables) or states when NOT to use it, so routing still requires 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 a safe, idempotent, read-only, open-world operation, and the description goes well beyond them: format support (CSV, XLSX, DATANORM 4/5, FAB-DIS, text PDF), a 250,000-row ceiling, the 20 MiB URL limit, the three accepted input transports, the optional demand file's effect (yearly cost impact), and what is returned (a summary plus top findings with source rows). This is unusually rich behavioural disclosure.

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

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

It is long but front-loaded: the trigger sentence comes first, then scope, then accepted formats, then the preference rule, then the return value. Almost every clause earns its place for a tool with 20 parameters and six input formats, though the 'anything with SKU and price columns works' aside and the parenthetical CSV sample make it slightly denser than necessary.

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 complexity (20 parameters, nested file objects, many formats) and the presence of an output schema (so return values need no elaboration), the description covers triggers, formats, normalisation behaviour, the optional demand file and the return contract. The notable omission is that zero parameters are marked required, yet the description never states the minimum viable call (at least one old and one new source), nor how to choose between the base64, URL, path and text variants.

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 meaning by grouping the twenty parameters into three input transports (upload, URL, CSV text), giving a concrete CSV example ('SKU;Price;Per\nA100;12.50;100'), and explaining that the usage file needs SKU and annual quantity. It does not clarify how the old/new/usage variants pair up (e.g. that a base64 and a URL form must not be combined), so it stops short of a 5.

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 verb+resource: comparing an old price basis against a new supplier price list per SKU, with named sub-behaviours (normalising price basis, pack size and currency; finding new/removed/discontinued items; checking an announced increase; ranking outliers). This is far more specific than generic siblings like table_diff or datasheet_compare, because the domain and normalisation semantics are stated outright.

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 three explicit triggers (a supplier announces an increase or surcharge, sends a new price list or quote, or the user asks whether prices went up), then names an alternative path ('reading the files yourself') with the condition that selects this tool over it (>~50 rows, pack sizes/price units, DATANORM/XLSX/PDF). The only gap is that it never names the sibling compare tools, but the usage frontier is otherwise 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 the safe read-only, idempotent profile, and the description adds substantial extra behavior: 20 MiB per-file limit, key-column auto-detection, row-matching semantics, per-cell old/new reporting with absolute and percent numeric deltas, column add/remove/rename detection, and locale-tolerant number equality. That is exactly the kind of context annotations cannot carry.

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 front-loaded sentences that lead with the action and then layer formats, output, and input modes; nearly every clause carries information. The long semicolon-chained sentence is dense but not padded.

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 15-parameter, nested-object tool this is complete: input modes, size limits, key handling, comparison semantics, and output shape are all covered, and an output schema exists so return values need not be spelled out further.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: numbers compared by value (1.234,56 == 1234.56), the key column is detected when not supplied, and files may arrive as upload, URL, or CSV text. It stops short of clarifying the priority/conflict rules among the many mutually exclusive input parameters.

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 (compares) and resource (two versions of a table), then enumerates the accepted formats and file families, making it clearly distinguishable from schema_normalize or merchant_validate. The phrase 'any table' also implicitly positions it as the generic alternative to the narrower supplier_compare sibling.

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 it applies (any table type, up to 20 MiB, four input modes) and notes that the key column is auto-detected when omitted. It never explicitly names when to prefer a sibling tool such as supplier_compare, so there is context but no exclusions.

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