FormulaSignal

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

Annotations already mark the tool read-only and idempotent, but the description adds substantial behavioral context: status semantics (`supported`, `partial`, `stale`, etc.), the distinction between record status and product facts, coverage limitations, observation-date caveats, and even the anti-iteration/suspension policy. This goes well beyond the annotations without contradicting them.

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 long, but every section earns its place: use case, exclusions, limits, anti-abuse constraints, status meanings, and interpretation caveats. It is front-loaded with the core purpose and uses clear headings, making it navigable for an agent despite its length.

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 sensitive regulatory domain, the description is unusually complete: invocation constraints, rate-limit behavior, status interpretation, coverage scope, and warning labels are all covered. An output schema exists, so detailed return-value documentation is not required here. Nothing an agent needs to call this correctly seems 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%, and both parameters are already documented with mutual-exclusivity and cardinality notes. The description reinforces 'at most 5' and 'not both,' but adds little semantic detail about the parameter values themselves 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 opening sentence states a specific verb and resource: 'Return regulatory records and documented cautions for named ingredients.' It also adds a crucial distinguishing detail, 'each carrying the class of record it actually is,' and the body names concrete content types (filings, advisories, label warnings, interactions, enforcement actions) that separate this from ingredient research or product lookup siblings.

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

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

There is an explicit 'When to use' section with concrete conditions, and the description clearly states what the tool cannot provide (approval, medical clearance, suitability judgement). However, it never names a sibling tool as an alternative, so the guidance stops short of full when-vs-alternative 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 readOnlyHint and idempotentHint annotations, the description discloses important behavior: statuses describe the Record, not the product; observation dates are read times, not change times; coverage is partial; and abusive iteration can be refused, scored, and suspend the key. This is substantial non-obvious context that aligns with 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 purpose is front-loaded, and each paragraph is clearly scoped to a distinct concern: when to use, limitations, quotas, coverage/statuses, date semantics, and disclaimer. Although longer than most descriptions, the density of operational caveats justifies the length, and there is little redundancy.

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?

Because an output schema exists, the description does not need to restate return fields. It supplies the missing context needed for correct invocation: status interpretation, limitation reporting, quota behavior, coverage boundaries, and date semantics. An agent has enough information to select and call the tool confidently.

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 material guidance: pass ingredient_ids (at most 5) or one product_id, not both; daily quotas apply across products, Signals, and ingredients; repeated reads of the same product are free; and iterating to assemble a copy of the Record is prohibited. This directly affects how an agent chooses and reuses parameter values.

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 operation: 'Return the dose range used in the selected evidence set for named ingredients, with the citation and its limitations.' This goes beyond the title and differentiates ingredients.research from siblings like ingredients.regulatory and products.compare by focusing on dose evidence and cited limitations.

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 provides explicit guidance in 'When to use: Use to place a declared amount against published work' and clearly states what the tool cannot provide. It does not name sibling tools as alternatives, but the intended use case and exclusions are specific enough for an agent to route correctly.

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?

While annotations already mark this as read-only and idempotent, the description goes far beyond that: it discloses that it never returns unreviewed candidates, explains the meaning of edition_hash, details the semantics of the status field ('supported', 'partial', etc.) and warns that those statuses are not facts about the product. It also clarifies observation date vs. change date and explicitly removes medical-advice ambiguity.

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 long, but every section earns its place: when to use, what it cannot provide, limits, status semantics, and date semantics are all essential for correct use. The clear section headers and distinct paragraphs keep it scannable, so the length is justified given the tool's behavioral complexity.

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 one fully documented parameter, annotations covering read-only and idempotent behavior, and an output schema present, the description still goes beyond the minimum. It covers usage scenarios, exclusions, rate-limit behavior, misuse warnings, and output semantics (statuses, edition_hash, observation dates), making it fully complete for an agent to decide when 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?

The schema already provides a complete description of edition_id ('A Category Ledger edition id, as returned by ledger.list'), so the description adds little about the parameter itself. It does reinforce that each call retrieves exactly one edition and implicitly ties edition_id to a published document, but this does not add substantial meaning beyond the 100% 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 opens with a specific verb and resource: 'Return one Category Ledger edition' and then lists the exact contents it returns. It clearly distinguishes this from ledger.list and other siblings by framing it as the single-edition retrieval companion to ledger.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 has an explicit 'When to use' section that names the precise scenarios ('needs the month's category intelligence with every denominator attached', 'needs to cite a figure a customer is reading on the web edition'). It also has a 'What it cannot provide' section that tells agents which data it will never return, effectively steering them to alternatives, and includes a warning against iterating to assemble the Record.

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 this read-only, idempotent, and closed-world, and the description adds useful behavior beyond that: closed editions are safe to cache while in-progress ones move until period close, and there is an explicit no-scraping caution. No contradiction with readOnlyHint or idempotentHint 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 front-loading is excellent, but the description becomes bloated: the caching point is stated twice, and the long tail about product coverage, statuses, observation dates, and medical advice is generic boilerplate not specific to listing ledger editions. Those later sentences do not earn their place in this tool's definition.

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 list tool with an output schema, the description is functionally complete: it names the returned fields, gives the expected call sequence, states limits, and clarifies caching. The main deduction is for irrelevant and repetitive boilerplate, not for missing information needed to invoke the tool 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 tool has zero parameters and the schema covers 100% of them (there are none), so the baseline is 4. The description does not need to add parameter details; it appropriately explains what the list returns and how to use it.

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: 'List the published Category Ledger editions' and names the exact fields returned (period, status, data-as-of date, count released). It also distinguishes itself from the sibling ledger.get by noting that the list is the first call and fetching an edition by id comes next.

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 'When to use' section is explicit: call this first to find which edition covers a period, then fetch that edition by id. 'What it cannot provide' further prevents misuse by stating it returns no edition figures and no product data, so an agent knows not to use it for those needs.

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, openWorldHint, and idempotentHint, and the description adds substantial context: refusal of REGISTERED products, no winner/suitability judgement, daily read limits, anti-iteration policy, status semantics, and observation-date caveats. This goes far beyond the annotations and is consistent with them.

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 long but well-structured with clear sections: purpose, when to use, what it cannot provide, limits, and status semantics. It is front-loaded with the core purpose, and every sentence adds operational or interpretive value rather than 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?

Given the tool's complexity, the description is remarkably complete. It covers invocation criteria, exclusions, limits, status interpretation, coverage caveats, and temporal semantics. The presence of an output schema means return-value details are not required, and the description covers everything else an agent needs 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 documents product_ids well, including canonical IDs, min/max items, and resolving names with products.resolve. The description adds important semantics beyond the schema: products must be 'covered', must be at NORMALIZED depth, and each distinct product read counts against a daily limit. This meaningfully enriches the 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 opens with a specific verb and resource: 'Compare two or three covered products on consistent FormulaSignal criteria.' It clearly distinguishes this from single-product tools by emphasizing multi-product comparison and names the comparison dimensions (formula, serving economics, stimulant load, record depth).

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 provides an explicit 'When to use' trigger and clear exclusions ('no overall winner', 'no suitability judgement', REGISTERED products refused). It also gives limits and anti-abuse guidance. However, it does not explicitly name alternative sibling tools, so the routing is clear but not fully 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=true and idempotentHint=true, but the description adds substantial behavioral context beyond that: daily read limits with cost semantics, refusal/suspension for abuse, the meaning of each status value, the distinction between observation date and change date, and the disclaimer about medical advice. This richly discloses how the tool behaves and how responses should be interpreted.

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 longer than a typical tool description, but it is structured into labeled sections (What it returns, When to use, What it cannot provide, Limits, coverage/status notes) and each section serves a distinct purpose. The main capability is front-loaded in the first sentence. It could be slightly tightened, but the length is justified by the semantic complexity of the coverage and status model.

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 a defined product coverage notion, status semantics, and usage restrictions, the description covers all essential context: what is returned, what is not returned, daily limits, anti-abuse rules, how to interpret statuses, and caveats about observation dates and non-medical-advice. An output schema exists, so return-value details need not be repeated. Nothing critical for correct invocation and interpretation 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?

The schema already provides 100% coverage for the single parameter, describing it as a canonical FormulaSignal product id and referencing products.resolve. The description adds little parameter-level meaning beyond the schema; it reinforces that the input is one covered product but does not introduce new format or constraint details. A baseline 3 is appropriate given the high 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 opening sentence states a precise verb and resource: 'Return the controlled current Record for one covered product' and enumerates exactly what is included (identity, serving configuration, declared ingredients, captured price context, freshness). The 'What it cannot provide' section explicitly bounds the scope, distinguishing it from related tools like products.history or record.version without needing to name 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?

A dedicated 'When to use' section states the intended context: 'when you need what a product declares right now, with the dates and limitations attached.' The 'What it cannot provide' list gives clear negative guidance, and the limits section warns against misuse (iterating to assemble a copy). Sibling alternatives are not named explicitly, but the exclusions imply when other tools would be more appropriate.

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

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

The description adds substantial behavior beyond readOnlyHint and idempotentHint: daily limits, status semantics (supported, partial, stale, etc.), observation-date vs. change-date nuance, coverage warnings, and a disclaimer. It enriches the agent's understanding of what these responses mean and how to interpret them, with no contradiction to 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 long but deliberately structured: core purpose first, then when-to-use, then exclusions, limits, and detailed semantics. Every paragraph adds necessary operational context for a tool with subtle interpretation rules. It is not overly terse but earns its length.

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 an output schema (which is not shown here), the description provides all essential behavioral context: how to interpret statuses, coverage boundaries, limits, and the distinction between observation and reformulation. An agent would have enough to call it correctly and interpret results.

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 only parameter product_id is fully described in the schema (canonical id, not display name). The description does not add further parameter-specific syntax or format details beyond this, and with 100% schema coverage the baseline of 3 is 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?

The description states a specific verb ('Return'), a resource ('controlled historical timeline'), and a scope ('one covered product'). It clearly distinguishes from siblings like products.get (current info) and record.version (overall record) by focusing on historical states and their classification.

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?

Explicitly says 'When to use' with three concrete use cases (changed, depth, comparability). It also lists what it cannot provide (reformulation dates, unreviewed candidates). However, it does not name specific sibling tools as alternatives, only general conditions, so it falls short of a full 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 declare readOnlyHint, idempotentHint, and openWorldHint=false, so the bar is lower, but the description adds substantial behavioral detail beyond that: never guesses, returns candidates on ambiguity, no match for uncovered products, daily limits and refusal/suspension risk, and the meaning of statuses like 'partial' and 'stale.' It also prescribes how to report statuses without overclaiming facts about the product.

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 longer than average but well-structured: it front-loads the core purpose and when-to-use guidance, then covers exclusions, limits, and status semantics in labeled paragraphs. Some repetition could be tightened, but each section carries meaningful operational guidance.

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 tool with an output schema, annotations, and clear sibling context, the description is remarkably complete. It explains success and failure modes, rate-limit implications, status semantics, observation-date caveats, and the non-medical-advice scope, leaving little an agent needs to infer.

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 identifier parameter is already described as 'a brand, product name or alias as the user wrote it' with an example. The description adds little parameter-specific semantic beyond what the schema provides, which is acceptable given 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 opens with a precise verb and resource: 'Resolve a brand, product name, or alias to one canonical covered product.' It also differentiates from siblings by stating this is the first call to obtain the canonical product_id that every other capability takes, so an agent can distinguish products.resolve from products.get or record.search.

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?

Explicitly states when to use it ('Call this first whenever you hold a user-supplied product name') and what it cannot provide ('It never guesses... ambiguous or generic name returns the candidate list...'). It also warns against iterating to assemble a copy of the Record, and the coverage note clarifies when the tool is not appropriate.

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?

While annotations already declare readOnlyHint, openWorldHint=false, and idempotentHint, the description goes far beyond by disclosing coverage limits, status semantics (supported, partial, stale, etc.), the meaning of observation dates vs change dates, and the refusal/suspension policy for misuse. This adds substantial behavioral context that annotations alone do not convey.

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

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

The description is long but each section earns its place: purpose, when to use, limitations, coverage, statuses, and caveats. It is well-organized with clear headings and front-loads the core function. While some could argue it is verbose, the density of critical information justifies the length.

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 complexity—covering product scope, statuses, observation semantics, and refusal behavior—the description is remarkably complete. It addresses edge cases (absent coverage, statuses as facts about the Record, not the product) and provides the operational constraints needed to call the tool correctly. The presence of an output schema covers return format, so 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?

There is only one parameter (product_id) and the schema already provides a complete description (canonical id, not display name). The description does not add extra parameter-level detail, but since schema coverage is 100%, a baseline 3 is appropriate. No further elaboration is needed.

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: 'Return the captured commercial facts and the deterministic price arithmetic for one covered product.' It then lists exactly what data it provides (package price, price basis, serving count, price per serving, observation date), which unambiguously differentiates it from sibling tools like products.get or products.history. The scope is precise and actionable.

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 when-to-use criteria ('Use for package price, price basis...') and a clear what-it-cannot-provide section that effectively routes agents away from overreach. It also warns against iterating over products to assemble the Record and explains the daily limit and refusal behavior, giving concrete operational 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?

Even though readOnlyHint and idempotentHint annotations are present, the description adds substantial behavioral context: daily quota accounting, repeated-question pricing, prohibition of iteration with possible key suspension, and the meaning of statuses like partial, stale, and unsupported. It also clarifies observation dates and windows, plus the non-medical-advice caveat.

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 long for a one-parameter tool, but it is organized with clear section labels and front-loads the core purpose before limits and status guidance. Nearly every sentence carries operational or semantic value, though some tightening could reduce reading load.

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 output schema exists and annotations cover read-only and idempotent behavior, the description fills the remaining gaps: status semantics, reporting requirements, quota costs, prohibited iteration, and data-source caveats. An agent receives enough context to invoke the tool correctly without needing to inspect the output 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?

The schema already fully describes the query parameter with maxLength and an example, so the baseline is high. The description adds meaning by requiring one question per call, noting that rewording returns the same answer, and explaining that repeating a question about the same product costs no additional quota.

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: 'Answer one specific, bounded question from FormulaSignal's covered pre-workout Record.' It then enumerates exactly what kinds of questions are in scope and explicitly lists what the tool cannot provide, which distinguishes it from broad product or export 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 has a clear 'When to use' block covering natural-language questions about declared content, changes, cost per serving, or a numeric condition, plus a 'What it cannot provide' block with exclusions like listing the database, exporting products, and answering medical questions. It does not explicitly name sibling tools as alternatives, so it stops short of the top anchor.

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, openWorldHint=false, and idempotentHint=true, so the safety profile is covered. The description adds substantial behavioral context: daily limits on distinct products read, refusal/scoring/suspension for iterating, status values (supported, partial, stale, under_review, ambiguous, unsupported), and the meaning of observation dates. It doesn't contradict annotations. A 4 is appropriate because the description goes well beyond annotations but doesn't exhaustively document every behavior.

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

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

The description is longer than average but every section earns its place: purpose, when-to-use, exclusions, limits, and interpretation guidance. It is front-loaded with the core purpose before diving into caveats. It could be slightly tighter, but the density of useful information justifies the length.

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 read-only tool with an output schema, the description is remarkably complete. It covers what the tool returns, when to use it, what it cannot provide, rate limits, coverage semantics, status interpretation, and caveats about observation dates and medical advice. Nothing an agent needs 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?

The tool has 0 parameters, so the schema is trivially complete. The description adds meaning by explaining what the returned version/coverage data represents and how to interpret statuses. With no parameters, the baseline is 4, and the description earns it by clarifying the semantics of the tool's output rather than 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?

The description states a specific verb and resource: 'Return the public Record version, the methodology version, the supported category, coverage counts, and source freshness.' It clearly distinguishes this from siblings like record.search by focusing on version/coverage metadata rather than searching records. The title 'Get record version' is expanded with concrete deliverables.

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 'When to use: Call this to state which version of FormulaSignal intelligence an answer came from, or to detect that coverage has moved.' It also provides exclusions: 'What it cannot provide' and 'Limits' with specific prohibitions against iterating through products to assemble a copy of the Record. This is exemplary usage 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?

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It explains that only approved signals are accessible, that unapproved ones return not found, daily reading limits, consequences of iterating (refused, scored, can suspend the key), and the meaning of status values (supported, partial, stale, under_review, ambiguous, unsupported). It also clarifies that observation dates and windows are not exact reformulation dates. This is rich behavioral context that annotations cannot convey.

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

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

The description is quite long but well-structured with clear paragraphs: definition, when to use, what it cannot provide, limits, coverage, statuses, observation date, and disclaimer. Key information is front-loaded. However, some repetition exists (e.g., the point that statuses are not facts about the product is made twice), and the length might be trimmed without losing meaning. Still, each paragraph earns its place, so a 4 is appropriate.

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 complexity and the existence of an output schema (which handles return structure), the description covers all necessary context: purpose, usage, limitations, status interpretation, date semantics, coverage, and disclaimers. There are no obvious gaps that would prevent an agent from using the tool correctly. The description even addresses edge cases like partial, stale, and unsupported statuses, which is essential for proper interpretation.

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 defines signal_id as 'A Signal id, as named by a product record, a formula history, or signals.list.' The description adds that only approved signals are valid and that non-approved returns not found, which is additional behavioral context. Since schema coverage is 100%, the baseline is 3, but the description enriches the parameter's meaning by tying it to the approval status and source locations, earning a 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 first sentence defines the tool precisely: 'Explain one approved FormulaSignal Signal: a confirmed, reviewed change between two comparable product states.' It uses a specific verb (explain) and resource (approved FormulaSignal Signal), and describes the output as the before state, after state, observation window, and evidence. This clearly distinguishes it from sibling tools like signals.list (listing) and signals.snapshot (snapshot), even though it doesn't name them 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?

The description includes an explicit 'When to use' paragraph: 'Use when a product record or history response named a signal_id and you need the before state, the after state, the observation window, and the evidence.' It also states what it cannot provide (unreviewed candidates, review deliberation, internal review queue) and that non-approved signals return not found. This gives clear guidance on when to use the tool versus alternatives, even if it doesn't name the alternatives explicitly.

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 mark this as read-only and idempotent, and the description adds substantial behavioral context beyond that: page cap of 25, incremental polling model, daily plan limits, exclusion of unreviewed candidates, coverage boundaries, status semantics, and observation-date caveats. This is unusually rich and directly helps an agent reason about consequences such as over-reading and getting the key suspended.

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 long, but it is organized into clear sections ('When to use', 'What it cannot provide', 'Limits') and front-loads the primary purpose before caveats. Almost every sentence adds either usage guidance, a boundary, or a safety-relevant limitation, which justifies the length for this complex 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?

Given the tool's semantic complexity, the description covers everything an agent needs: what is returned, pagination, polling strategy, filters, limitations, coverage meaning, status interpretation, and plan-level constraints. The output schema exists, so return-value details are not required here. Nothing important for correct invocation appears to be 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?

All 8 parameters are fully described in the input schema (100% coverage), so the baseline is 3. The description reinforces how to use `since` and `cursor` for polling and mentions filterable fields like product, brand, dimension, and category, but it does not add substantial meaning beyond what the schema already states for each 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?

The description opens with a specific verb and resource: 'Return approved FormulaSignal Signals in release order, newest first, for incremental polling.' It clearly defines the operation, the scope ('approved'), ordering, and intended use. The later statement that it is 'not an export of the product table' also helps distinguish it from plain product retrieval 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 gives explicit usage context: 'Use to keep a system in step with the Record' and tells the agent to pass `since` with the last seen release date or follow `next_cursor`. It also warns against walking the feed. However, it never names an alternative sibling tool or gives a direct 'use X instead' condition, so it stops short of a full when-to-use vs 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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds substantial context: the capped window (400 days, 25 per page), the daily read limits, and the nuanced meaning of status values like 'partial' and 'stale', emphasizing they are not facts about the product. This exceeds what annotations provide, though it does not cover every potential behavior (e.g., pagination mechanics are implied via next_cursor).

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 efficient, front-loading the core purpose and then covering usage, limits, and interpretation. Every sentence earns its place, though the section on statuses and disclaimers is a bit dense. It could be trimmed, but it is not verbose. Slightly above average in structure.

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 complexity (bounded windows, status semantics, daily limits) and the presence of an output schema (which handles return structure), the description is complete enough. It clarifies the tricky aspects (coverage is not the whole category, observation dates vs. reformulation) that an agent needs to interpret results correctly. No critical gaps remain.

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%, meaning the schema already documents each parameter clearly (dates, limit, cursor). The description adds context on defaults and caps, but these are also implied by schema descriptions. The description does not add novel meaning beyond what the schema provides, so a baseline 3 is 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?

The description states a specific verb ('Return a bounded summary') and resource ('approved Signals and coverage state across the covered pre-workout set for a date window'), making it distinct from siblings like signals.list and ledger.get. It clearly identifies what it provides and what it is not (not an export), which separates it from alternatives.

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 states when to use it ('Use for 'what changed in the category recently'') and what it cannot provide (not an export), and it names alternatives implicitly through sibling context. It also warns against misuse (e.g., iterating to assemble a copy of the Record), which is strong usage 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?

Beyond the annotations, the description discloses refusal conditions (outside covered set, watch limit, account binding, entitlement), anti-scraping enforcement ('can suspend the key'), and the meaning of statuses. It also explains that absence from coverage says nothing about the product, which is valuable behavioral context.

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 well-structured with labeled sections and front-loads the purpose, but it is lengthy and includes generic FormulaSignal caveats (statuses, observation dates, medical advice) that are not specific to adding to a watchlist. Some sentences could be trimmed without losing essential guidance.

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 output schema exists, the description covers all necessary operational context: prerequisites, coverage constraints, account binding, watch limits, refusal behavior, plan limits, and response status semantics. An agent has enough information to call the tool correctly and avoid misuse.

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 single parameter is already fully described in the schema (canonical product id, resolve names first), so the description adds little new parameter-specific meaning. It reinforces the need to resolve names, but schema coverage is 100%, so 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?

The description opens with a specific verb and resource: 'Add one covered product to the bound account's watchlist.' This clearly identifies the operation and scope, and the 'Watch product' title aligns with the add-to-watchlist action, distinguishing it from sibling tools like watchlist.remove and watchlist.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?

It provides an explicit 'When to use' condition ('when a person asks to start watching a product') and a prerequisite ('Resolve the product first if you were given a name rather than an id'). It does not explicitly name alternative tools or state when not to use it, but the context is clear enough.

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 annotations (readOnly, openWorld=false, idempotent), the description discloses the single-account scope, daily read limits, enforcement consequences ('refused, scored, and can suspend the key'), and the meaning of statuses as Record states rather than facts about products. It also warns against misusing coverage or treating observation dates as reformulation dates.

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 longer than average but front-loaded with the primary purpose and organized with clear sections: 'When to use', 'What it cannot provide', 'Limits', and status interpretation. It is dense rather than padded, though a few warnings could be tightened without losing value.

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 parameterless, read-only list tool with an output schema and annotations, the description covers account binding, daily limits, prohibited iteration, status semantics, date semantics, and non-medical scope. Nothing needed to decide whether and how to call it 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?

The input schema has zero properties, so there are no parameter semantics to document. The description appropriately adds no parameter details and avoids inventing arguments; baseline 4 applies for parameterless tools.

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: 'Return the watchlist of the one Founding Pro account this key is bound to, with each product's monitoring state.' It also distinguishes itself from siblings by stating what it cannot provide, such as candidate detail, source URLs, and internal identifiers, and by framing itself as the list operation rather than a coverage 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?

There is an explicit 'When to use' block listing concrete questions the tool answers: what a person is watching, last read times, next check due, and unreadable items. The 'What it cannot provide' and 'Limits' blocks add exclusions, but the description does not name a specific sibling tool as the alternative, so it stops short of fully routing the agent.

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 declare readOnlyHint and idempotentHint, but the description goes far beyond: it explains the status values (supported, partial, stale, etc.), clarifies that a count of valid checks is not a claim of product stability, details daily read limits and refusal/score/suspend consequences for iterating, and stresses that statuses reflect the Record, not product truth. This is exemplary 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?

The description is longer than typical but every section earns its place: core purpose, when to use, limitations, and crucial interpretation nuances. It is front-loaded with the primary function and then layers context. A slight deduction for verbosity, but it remains structured and not 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?

For a tool with one optional parameter and an output schema, the description is exhaustive. It covers return contents, status meanings, data-source interpretation, daily limits, and the distinction between Record status and product facts. An agent has everything needed to call it correctly and interpret results without ambiguity.

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% (the only param, period, is well described as 'A calendar month, YYYY-MM. Defaults to the current month (UTC).'). The description mentions 'for one period' and explains how an unreached period is reported, which is more about output semantics than parameter syntax. It adds no new format or value constraints beyond the schema, so baseline 3 is 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?

The description opens with a precise statement: 'Return the monitoring receipt for one period: valid checks, attempts that returned nothing, recoveries, and confirmed Signals.' It specifies a verb, resource, and scope, and clearly differentiates from sibling watchlist tools (add/list/remove) by focusing on the receipt of monitoring activity, not manipulation of the watchlist.

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?

Explicit 'When to use' section: 'Use to answer whether anything a person watches changed in a period, and what monitoring did in the period whether or not anything did.' It also explains what it cannot provide, including the nuance that a period not reached is reported as 'partly covered' rather than zero, which guides correct interpretation and avoids misuse.

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 indicate idempotentHint=true and destructiveHint=true. The description adds significant context: 'Future alerts stop; everything already delivered stays.' It also details the daily limit on reading distinct products and warns against iterating to assemble a Record, which is a behavioral constraint beyond the annotation. However, it does not explicitly mention the idempotent nature of the operation, but the annotation already covers that, so no 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?

The description is concise and well-organized: the first line states the main action, followed by a 'When to use' section, then 'What it cannot provide', then 'Limits' and 'FormulaSignal' sections. It is front-loaded and each section adds value. However, there is a minor inefficiency: the 'FormulaSignal' section is extensive and covers broader platform context that may not be strictly necessary for calling this specific tool. It still earns a 4 for its overall clarity and structure.

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 one required parameter, full schema coverage, and an output schema (not described but present), the description covers the tool's purpose, usage, limits, and exclusions. However, the 'FormulaSignal' section introduces concepts like 'status' and 'limitations' that may be overkill for this simple mutation tool, but they do not omit essential information. The tool is simple enough that the description is more than 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 schema description for product_id is 100% covered with 'The canonical product id to stop watching.' The description does not add any further parameter-specific details, but given full schema coverage, baseline 3 is 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?

The description clearly states the primary action: 'Remove one product from the bound account's watchlist.' It identifies the verb (remove), the resource (watchlist), and the scope (one product from the bound account). It also clearly distinguishes itself from siblings like watchlist.add and watchlist.list, making 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 explicitly states when to use: 'Use when a person asks to stop watching a product.' It also provides clear exclusions: 'It cannot delete an account, cancel a subscription, or remove history.' This goes beyond typical guidance by directly addressing what the tool cannot do, setting accurate expectations.

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