Additive Atlas

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

Adds substantial behavior beyond the annotations: exact matching against the in-scope alias vocabulary, the meaning of matches: [] (unresolved, open-world ambiguity between 'not an additive' and 'unknown additive'), the required axis+lang pairs, and the explicit caveat that results are drafts requiring verification rather than safety judgements. Note a mild tension with openWorldHint=false in the empty-match semantics, but it describes vocabulary ambiguity, not external-world interaction, so it is not a contradiction.

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-loads the purpose in the first sentence, then layers mechanics, constraints, and caveats in a logical order. Dense with parentheticals, but nearly every clause carries operative information; only the HTTP-endpoint equivalence is arguably 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?

With no output schema, the description carries the return-value burden and does so: per-token SubstanceSummary records plus known interactions between detected substances, with the empty-match case explained. Combined with the axis/lang constraint and the draft-verification caveat, an agent has everything needed to call and interpret 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 baseline is 3, but the description adds real value the schema lacks: the enumerated legal axis+lang combinations (JP+ja, US+en, EU+nl/fr/de/es/pl/el/bg) and confirmation that either raw text or pre-split arrays are acceptable.

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 ('Find the additives named on a label') and describes the transformation (tokenize the additive section, resolve substances, surface interactions), so the agent knows exactly what the tool produces. It does not, however, distinguish itself from the sibling analyze_label_diff, which an agent must infer on its own.

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 input-scope guidance ('cutting the additive section out of the label is the caller's job; sending the whole ingredient section is allowed'), which is useful precondition context. But it never says when to prefer this over analyze_label_diff, get_substance, or search_substances, leaving routing to inference.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses that the tool is paid, absent from MCP, returns no analysis data, and gives the concrete endpoint (POST /v1/labels/analyze/diff), pricing (0.01 USDC per request) and payment rail (x402 on Base). This is unusually rich behavioral context that annotations cannot convey, and nothing contradicts the read-only hint.

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

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

Three short sentences with the two most decision-relevant facts (paid, not available via MCP) front-loaded in parentheses. There is mild redundancy between 'each detected substance carries the cross-axis derivation' and 'This tool does not return that data', but the clarification is warranted given the counterintuitive 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 carries the burden of explaining what the agent gets back, and it does so fully: not the data, but the endpoint URL, request shape and cost. Combined with 100% schema coverage on inputs, nothing an agent needs in order to call and act on this tool 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 text, axis and lang are already fully documented in the input schema, which sets the baseline at 3. The description only adds that the input matches analyze_label, which is useful for parity but not new per-parameter meaning.

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 definition states exactly what the tool is (a routing shim that returns an HTTP endpoint) and how it relates to its sibling analyze_label: same input, but the paid variant carries cross-axis derivation. An agent can tell without opening either schema that this tool does not perform the analysis itself and what it returns instead.

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 signals the condition that selects this tool over analyze_label (you need cross-axis derivation) and warns that it is unavailable through MCP, which is critical for invocation decisions. It stops short of an explicit 'do not use this if...' exclusion or pointing to alternatives like get_substance_diff.

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 openWorldHint=false, and the description adds genuinely new semantics: axis-specific keys appear only where the roster has that concept, empty lists are meaningful ('use_standards: [] = no use standard'), and every record is a draft needing verification. This is substantive context beyond the safety profile.

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-loads the core resource statement and then layers scope, boundary, and caveats. The second and third paragraphs earn their place, though the long parenthetical key list is dense and slightly heavy for a single tool.

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

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

There is no output schema, so the description must carry the return shape — and it does, enumerating the returned keys and the meaning of empty lists. Combined with the boundary and draft-status caveats, an agent has everything needed to call 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 description coverage is 100% and the single id parameter is documented with format examples in the schema itself. The description adds no additional syntax or format detail beyond what the schema provides, 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 resource (one substance's full roster record) and enumerates the exact contents it returns (identifiers, category, aliases, translations, ledger row, groups, axis-specific fields). It explicitly carves out the sibling boundary: 'nothing here crosses an axis (that is get_substance_diff)'. An agent can distinguish this from get_substance_diff without opening either 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?

Names the alternative (get_substance_diff) and the condition that selects it ('crosses an axis'), and the id schema points to search_substances/analyze_label as upstream sources. It stops short of saying when to prefer this over analyze_label, so it is clear but not fully exhaustive 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?

Beyond the readOnly/openWorld annotations, it discloses the critical behavior that this tool does NOT return the diff data but instead returns the endpoint (GET /v1/substances/{id}/diff), along with cost (0.01 USDC per request) and the payment rail (x402 on Base). This is exactly the kind of non-obvious operational context an agent cannot get from the schema or 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 paid/HTTP-only warning is correctly front-loaded in parentheses. The first sentence is dense and describes data the tool does not itself return, which costs some clarity, but it still earns its place by telling the agent what the paid endpoint would yield before routing them there.

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 must explain the return value, and it does state that the response is the HTTP endpoint rather than the diff. It could be more explicit about the exact response shape (bare URL vs. structured field), but for a 1-parameter routing tool the essential context is present.

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

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

There is a single 'id' parameter with 100% schema description coverage, including format examples, so the schema carries the semantics. The description adds nothing about the id beyond the {id} path placeholder, matching the baseline-3 case where 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 name/title and description clearly state that this retrieves the cross-axis derivation for one substance (all axes other than the substance's own), and the second sentence uniquely clarifies that the tool returns an HTTP endpoint rather than the data itself. That non-obvious distinction separates it from siblings like get_substance and analyze_label_diff, though the purpose sentence is wordy and indirect.

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 to use it (you want the per-axis derivation with source separation and refusals) and flags it as paid/HTTP-only, but it never explicitly contrasts it with get_substance or analyze_label_diff, nor states conditions under which an agent should prefer those siblings instead.

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 readOnlyHint/openWorldHint already covering the safety profile, the description adds substantial non-obvious behavior: NFKC normalisation, exact-only matching against axis-specific name sets, what the response rows contain (SubstanceSummary plus the matched text), and an explicit caveat that records are drafts requiring verification.

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 core action and matching semantics, and the dense sentences each carry information rather than filler. It is still a fairly long block for a three-parameter lookup, and the HTTP GET parenthetical is conveniences rather than essentials.

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 appropriately explains the return shape (matching SubstanceSummary rows plus the matched text). Combined with the draft-verification caveat and the axis/lang constraint, an agent has everything needed to invoke and interpret this 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 baseline is 3, but the description materially exceeds the schema by constraining axis+lang to an enumerated pair list (the schema has no enums) and by explaining what each axis's vocabulary actually contains (E numbers for EU, 品目名 for JP, CFR names for US) and how the input name is transformed before matching.

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 ('look up substances by name') scoped to one regulatory axis, and the exact-match semantics clearly frame it as a name-lookup rather than an ID fetch. It does not explicitly name or contrast itself with the sibling get_substance, so the differentiation is only implied.

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

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

The description implies the use case (resolve a printed name or label term to substances) but never states when to use this versus get_substance or the analyze_label family, nor any when-not condition. The accepted axis/lang pair list gives practical invocation guidance but is not routing guidance.

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