FormulaSignal

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

With no annotations, the description carries the full burden and succeeds. It discloses refusal of REGISTERED products, the daily read limits and suspension risk, status semantics (supported/partial/stale/ambiguous/unsupported are Record facts not product facts), observation-date meaning, and a medical disclaimer.

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 front-loaded with purpose and when-to-use, and each paragraph addresses a real failure mode or correctness caveat. It could be tightened, but the length is largely justified by the domain's nuance.

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

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

For a tool with no output schema and no annotations, the description covers purpose, applicability, product-depth constraint, quota behavior, status semantics, date semantics, and exclusions. Missing a precise output structure is minor because the comparison criteria and status behavior are spelled out.

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 with min and max items and canonical id resolution, so the baseline is 3. The description adds meaningful operational constraints: products must be at NORMALIZED depth, at most 3 per call, and each distinct product consumes a daily quota while repeating the same product does not.

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 or three covered products on consistent FormulaSignal criteria, and explicitly says it returns no overall winner or suitability judgement. This clearly distinguishes it from sibling tools like get_product_record or search_record.

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?

Provides an explicit 'When to use' condition for product-difference questions and a 'What it cannot provide' set of exclusions. It does not name a specific alternative sibling for cases where a winner or suitability judgement is needed, but the guidance is otherwise clear.

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

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

There are no annotations, so the description carries the full behavioral burden. It discloses that only approved Signals can be explained, unapproved ids return not found, daily read limits exist, repeated reads of the same product are free, abuse can be refused/scored/suspended, every response has a status, statuses describe the Record rather than product truth, and observation dates/windows are not exact change dates. That is unusually complete 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 long, but it is organized with clear sections ('When to use', 'What it cannot provide', 'Limits') and is front-loaded with the core definition. Nearly every sentence contributes operational or interpretive value, and the length is justified by the absence of annotations and the number of important caveats an agent must respect.

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

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

With no output schema, the description compensates by explaining what responses contain (status, limitations, before/after, observation window, evidence), what statuses mean, and how to interpret them. It also covers access limits, misuse consequences, coverage limitations, and temporal semantics, making it complete for an agent to decide when and how to call the tool.

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

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

The schema already documents signal_id as a canonical id, not a display name, at 100% coverage. The description adds meaningful context: the id must correspond to an approved Signal, and an unapproved id returns not found. It does not give an id format or example, but for a single fully documented parameter the added semantics are sufficient.

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: 'Explain one approved FormulaSignal Signal' and defines it as a confirmed, reviewed change between two comparable product states. It also states what the explanation covers (before state, after state, observation window, evidence), which distinguishes it from sibling list/compare/search tools even though no sibling is named.

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

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

It gives an explicit 'When to use' condition: when a product record or history response named a signal_id and the agent needs before/after state, observation window, and evidence. It also provides exclusions: no unreviewed candidates, review deliberation, or internal queue access, and a warning not to iterate to reconstruct a Record. However, it does not name a specific alternative sibling tool for those excluded cases, so it stops 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?

With no annotations provided, the description carries the full burden, and it does so thoroughly. It discloses rate limits, the 400-day/25-item caps, the meaning of statuses, the distinction between observation dates and reformulation dates, the coverage caveat, and refusal/suspension risk for abuse. This is far beyond what the bare schema would tell an agent.

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: purpose, when to use, exclusions, limits, status meanings, and caveats. It is front-loaded with the core statement and then structured with clear labels. Some redundancy exists around boundedness, but the density is justified by the tool's complexity and the absence of annotations.

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 that there is no output schema and no annotations, the description is unusually complete. It tells the agent how to interpret every response status, what limitations to read, what to report to users, and what behaviors are forbidden. An agent could invoke this tool correctly and interpret its results with minimal 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 description coverage is only 50%, so the description must compensate. It adds crucial semantics: from/to define a bounded date window capped at 400 days, page size is capped at 25, and next_cursor should be followed for more. It does not describe the cursor format or limit defaults, but it gives enough operational meaning beyond the schema for correct use.

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 a bounded summary of approved Signals and coverage state across the covered pre-workout set for a date window.' It clearly distinguishes itself from product-record and export tools by stating what it is not ('not an export', 'never the product table and never the underlying Record'), so an agent can separate it from siblings like get_product_record or search_record.

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 guidance is provided: 'Use for what changed in the category recently' with from/to dates. It also states what it cannot provide, warns against iterating to assemble the Record, and clarifies that the window and page size are capped. This gives clear when-to-use and when-not-to-use direction.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses daily read quotas, that repeated same-product reads cost no extra, that iterating to assemble a record copy is refused/scored/suspending, and that statuses like `partial` and `stale` are statements about the Record, not facts about the product. It also clarifies observation date vs change date and coverage limitations, making the tool's behavior and caveats unusually explicit.

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 bold section headings and the core purpose is front-loaded before caveats. Each block adds useful operational context. It loses a point only for some redundancy: the observation-window warning appears twice and coverage caveats are repeated, making it longer than strictly 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 a single required parameter and no output schema, the description supplies enough selection and invocation context: when to use it, what it cannot do, quota limits, status semantics, and product coverage boundaries. It does not fully define the timeline's exact response shape or 'state' fields, but the status list and 'controlled historical timeline' may be sufficient for correct use.

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

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

The input schema already fully documents `product_id` as a canonical id, but the description adds meaning beyond that: the product must be a covered FormulaSignal product, absence from coverage is not evidence about the product, and reading many distinct products consumes quota. These product_id-related semantics help the agent interpret results and plan calls correctly.

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 controlled historical timeline for one covered product' and explains that each state is classified by what it can support. It also draws a clear boundary in 'What it cannot provide', distinguishing historical timeline behavior from exact reformulation dating and confirming that unviewed candidates are never reported as changes. This provides enough differentiation from sibling record/history tools even without naming them.

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

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

The 'When to use' section explicitly names three diagnostic purposes: detect product changes, assess recoverable history depth, and compare states. The 'What it cannot provide' and 'Limits' sections add important exclusions and anti-abuse guidance. It stops short of 5 because it does not explicitly point the agent to a sibling tool for alternative cases such as obtaining the current full 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?

With no annotations provided, the description carries the full burden, and it covers a great deal: return limitations, status semantics for `supported` and other states, quota and anti-abuse behavior, the meaning of edition_hash, observation date semantics, and disclaimer boundaries. It explicitly tells the agent how to interpret statuses and not treat record-level responses as facts about products.

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 tightly sectioned and front-loaded with the core return value before caveats. Each paragraph earns its place: what it returns, when to use it, exclusions, limits, and interpretation guidance. The structure makes the length navigable rather than bloated.

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 itself must provide the contract for what comes back, and it does: returned components, statuses, edition_hash meaning, and important interpretation caveats. It also covers operational constraints such as quotas and the prohibition on iterating to assemble a Record. The only minor omission is how to obtain a valid `edition_id`, but the existence of `list_ledger_editions` among siblings covers that.

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 only parameter, `edition_id`, as a canonical FormulaSignal id. The description adds the 'one edition per call' constraint and implies the id selects a specific edition, but it does not add substantial new meaning beyond the schema, 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?

The description opens with a specific verb and resource: 'Return one Category Ledger edition' and enumerates the exact contents it returns, which clearly distinguishes it from sibling tools like list_ledger_editions or get_product_record. It also clarifies what it never returns, sharpening the boundary further.

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 and a 'What it cannot provide' section, giving clear conditions for appropriate use and exclusions. It does not name a specific sibling alternative to switch to, but the usage conditions are concrete enough that an agent can decide when this tool is 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?

With no annotations present, the description carries the full behavioral burden and does so thoroughly: it discloses daily plan limits, refusal and key-suspension risks for misuse, status semantics that must not be treated as facts about the product, observation-date vs change-date meaning, and a non-medical-advice disclaimer. This is exceptional transparency.

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?

Although the description is long, it is structured into labeled sections and every sentence carries meaningful guidance. Given the absence of annotations and output schema, the length is justified rather than bloated. It is front-loaded with return-value content and then moves to usage, exclusions, limits, and status semantics.

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 one-parameter read tool with no annotations and no output schema, the description covers return contents, exclusions, status vocabulary, quota behavior, misuse consequences, and temporal semantics. An agent has enough context to invoke the tool correctly and interpret its response appropriately without guessing.

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 product_id is already fully documented in the schema with 100% coverage: 'A canonical FormulaSignal id, not a display name.' The description reinforces that the tool works on one covered product and that distinct products consume quota, but it adds no necessary parameter-format information beyond the schema. With 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 opens with a specific verb and resource: 'Return the controlled current Record for one covered product' and enumerates the exact data categories included. It also carves out exclusions (no source bytes, no internal identifiers, no review notes, no suitability verdict), which helps separate it from sibling tools like get_record_version or get_research_context.

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 telling the agent to use it when it needs 'what a product declares right now, with the dates and limitations attached.' It also warns against iterating through products to assemble a Record copy, which is a clear anti-pattern. However, it does not name specific sibling alternatives, so the routing is contextual rather than 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?

With no annotations provided, the description carries the full burden and does so richly. It discloses that the tool exposes no internal scoring or proprietary methodology, explains daily read limits and key suspension risk, describes status values like 'supported' and 'partial' as statements about the Record rather than the product, and clarifies observation dates and non-medical-advice scope.

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: 'When to use', 'What it cannot provide', 'Limits', and coverage/status context. It front-loads the core purpose, and while dense, the extra length earns its place given the serious limitations and status interpretation warnings.

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

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

For a zero-parameter tool with no output schema and no annotations, the description is remarkably complete. It explains what is returned, when to call it, what is deliberately not exposed, usage limits, status semantics, data freshness caveats, and safety disclaimers, leaving no critical gap for an agent deciding whether and how to invoke 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 input schema has zero parameters and 100% schema description coverage, so there are no parameter semantics for the description to add. The baseline for zero parameters is 4, and the description appropriately focuses on output meaning rather than input syntax.

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: 'Return the public Record version, the methodology version, the supported category, coverage counts, and source freshness.' The 'When to use' section further clarifies the intent, distinguishing it from product-record or comparison tools by focusing on version attribution and coverage movement.

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?

Provides explicit when-to-use guidance: 'Call this to state which version of FormulaSignal intelligence an answer came from, or to detect that coverage has moved.' It also gives clear anti-usage guidance, warning not to iterate through products to assemble a Record copy, and explains limits and consequences.

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?

There are no annotations, so the description must carry the behavioral burden, and it does: records are returned with their actual class, filings are never misrepresented as approvals/warnings/findings of harm, daily limits and misuse consequences are stated (refused, scored, can suspend the key), and the coverage boundary is explained. This is far more transparent than typical definitions.

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 front-loaded and uses clear section headers that make its length readable. It loses a point because the trailing fragment 'Add a response carries ...' is garbled and does not earn its place; otherwise the structure is strong.

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 no annotations and no output schema, the description is remarkably complete: return semantics, record-class caveats, non-goals, mutual-exclusivity, cost/quota behavior, enforcement of misuse, and the scope of coverage are all covered. An agent has enough information to invoke the tool correctly and interpret results cautiously.

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 canonical IDs and the resolve_product step, so the baseline is 3. The description adds one key parameter-level rule beyond the schema — ingredient_ids and product_id are mutually exclusive ('not both') — plus quota and iteration restrictions. That is meaningful, but much of the added text is about plan limits rather than the parameters themselves.

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 action and resource: 'Return regulatory records and documented cautions for named ingredients,' then lists the content types (filings, advisories, label warnings, interactions, enforcement actions). This makes the tool's scope unmistakable and distinguishes it from the other get_* siblings, which are not specifically about regulatory context.

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 has an explicit 'When to use' section and a 'What it cannot provide' section, so an agent knows when the tool applies and when it does not (no approvals, no medical clearance). However, it never names alternative sibling tools such as get_research_context or get_product_record, so the guidance is not quite as strong as it could be.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It discloses the daily read limits, that excessive iteration can suspend the key, that statuses like partial/stale/unsupported are about the Record rather than the product, and that observation dates/windows have specific meanings. It also includes a clear disclaimer that the output is not medical advice.

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 nearly every sentence carries operational value: purpose, usage, limits, status semantics, and disclaimers are all relevant. It is organized with labeled sections like 'When to use,' 'What it cannot provide,' and 'Limits,' which makes it scannable despite the length. It could be tightened slightly, but it is 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?

Given that there is no output schema and no annotations, the description compensates well by describing the output as a dose range with citation, limitations, and a status field, and by explaining what each status means. It also covers edge behaviors like the distinct-read limit and key suspension. It does not spell out the exact JSON response structure, but it provides enough behavioral context for an agent to call and interpret 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?

Although the schema already covers 100% of parameter descriptions, the tool description adds meaningful semantics beyond the schema. It clarifies that ingredient_ids and product_id are mutually exclusive, that ingredient_ids accepts at most 5, that ids are canonical FormulaSignal ids rather than display names, and that names should be resolved with resolve_product first. This materially improves correct invocation.

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 dose range used in the selected evidence set for named ingredients, with the citation and its limitations.' This clearly identifies what the tool produces and distinguishes it from related tools like regulatory context, formula history, or product records. The 'When to use' sentence reinforces the intended purpose by tying it to placing a declared amount against published work.

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' guidance and clearly states what the tool cannot provide, which helps an agent avoid misusing the output as effectiveness or safety evidence. It also provides strong operational constraints such as not passing both ingredient_ids and product_id and not iterating to assemble a copy of the Record. It does not explicitly name alternative sibling tools, but the exclusions and limits are clear enough for 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?

No annotations are provided, so the description carries the full disclosure burden, and it does so extensively. It explains status semantics, coverage limitations, observation-date meaning, list-price rules, promotional-versus-list distinction, daily limits, anti-scraping consequences, and the non-medical nature of the output. This goes well beyond a typical tool description.

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 clearly structured with sections: what it does, when to use, what it cannot provide, limits, and coverage/status semantics. It is front-loaded with the core purpose, and most sentences earn their place given the absence of annotations and output schema.

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 supply enough about response meaning. It lists the returned economics fields, explains status values and limitations, and warns about key suspension. It does not give a precise response shape, but it is complete enough for an agent to select and 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 input schema already describes product_id as a canonical FormulaSignal id rather than a display name, providing 100% schema coverage. The description adds no additional parameter-level guidance, so 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 first sentence names a specific verb and resource: it returns 'captured commercial facts and the deterministic price arithmetic for one covered product.' The following sentence enumerates the exact fields (package price, price basis, serving count, price per serving, observation date), which clearly separates this tool from siblings like get_product_record or get_formula_history.

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 listing the questions this tool answers. There are also strong behavioral prohibitions, such as not iterating through products to reassemble the Record. However, it does not explicitly name alternative sibling tools for cases outside its scope.

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

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

With no annotations, the description carries the full burden and does so extensively: it discloses rate limits, suspension risk for misuse, partial-coverage semantics, status meanings, observation-date caveats, and that absence from coverage says nothing about a real product. This goes far beyond what the schema or title could 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 it is deliberately structured with labeled sections ('When to use', 'What it cannot provide', 'Limits') and the core purpose is front-loaded in the first sentence. Most sentences add non-obvious operational knowledge, though the length is substantial enough to prevent a 5.

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

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

Given no output schema and no annotations, the description does an unusually complete job of covering response semantics, statuses, limitations, and misuse risks. It is missing a concrete explanation of the period parameter's syntax and default behavior, which prevents full completeness for an agent that must call 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 schema has 0% description coverage and the description never explains the period parameter's format, allowed values, or behavior when omitted. The phrase 'one period' and 'a period the monitoring ledger does not reach' give some context, but an agent still cannot confidently know whether to send '2025-03', a date range, or nothing at all.

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 monitoring receipt for one period' and names the exact content of the receipt (valid checks, attempts, recoveries, confirmed Signals). The 'What it cannot provide' section further distinguishes it from broader product-record tools, so an agent can tell it apart from siblings like get_product_record or get_ledger_edition.

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 stating the exact kind of question the tool answers, and a clear 'What it cannot provide' section listing exclusions such as not proving product stability and not reporting candidate or source URL. It also warns against iterating to reconstruct the Record, which is a strong when-not-to-use signal; however it rarely names alternative sibling tools 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?

With no annotations, the description carries the full burden and goes beyond a basic read: it discloses cache safety for frozen editions, the volatility of in-progress editions, daily usage limits, the risk of suspension for iterating to rebuild the Record, and the semantics of statuses and observation 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 well front-loaded with a one-sentence summary and clear headings, but it is overlong for a no-argument list tool: the cache-safety point is made twice and the final paragraph contains generic API-wide caveats (coverage, statuses, medical advice) not specific to listing ledger editions.

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?

Despite the absent output schema, it names the returned fields and gives enough behavioral and limits context to call and interpret the result. It is complete for selecting the tool, invoking it with zero arguments, and knowing what the listing will and will not provide.

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 parameters and 100% coverage, so the zero-param baseline of 4 applies. The description adds no parameter detail because none is needed; it instead clarifies what the returned list contains.

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

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

The description uses a specific verb and resource: 'List the published Category Ledger editions' and enumerates the returned fields (period, status, data-as-of date, count released). It also sets boundaries by stating it returns no figures from inside an edition and no product data, which distinguishes it from edition-content/product-data 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?

Explicitly instructs when to use it: 'Call this first to find which edition covers a period, then fetch that edition by id.' It also gives a when-not-to-use signal by noting it cannot provide figures or product data, pointing toward the alternative of fetching an edition by id.

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

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

With no annotations provided, the description carries the full transparency burden and does so thoroughly. It discloses approval gating, page limits, daily quota behavior, suspension risks for misuse, response status meanings, the distinction between observation dates and reformulations, and non-medical scope. This goes far beyond the structured metadata.

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 front-loaded with the core behavior and organized into labeled sections ('When to use', 'What it cannot provide', 'Limits'). It is long but justified by the tool's semantic complexity. Some redundancy exists around not walking the feed versus not iterating to assemble a copy of the Record, which costs a point.

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 8 optional parameters, no annotations, and no output schema, the description supplies enough for an agent to select and invoke the tool: it explains purpose, filters, cursors, page limits, quota semantics, status meanings, and important caveats. It does not describe the exact shape of returned Signal objects, but that is secondary for correct selection and call construction.

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 describes only 3 of 8 parameters, so description compensation matters. It operationalizes `since` as the last-seen release date, implies `cursor` via 'follow next_cursor', and explains how product/brand/dimension/category filters work. Minor gaps remain: `until` is not mentioned, and `next_cursor` is not explicitly mapped to the `cursor` parameter name.

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 distinguishes itself from generic exports and product-table reads by stating it returns only approved Signals and excludes unreviewed candidates, clarifying its unique scope among 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?

The 'When to use' section explicitly frames the tool as a polling mechanism: 'Use to keep a system in step with the Record. Pass since... or follow next_cursor...' It also explains what it cannot provide, such as unreviewed candidates or product-table exports. However, it does not name specific sibling tools as alternatives, so the routing remains partly implied.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the tool reaches exactly one account, that statuses like 'partial' and 'stale' are real answers about the Record and not facts about the product, that observation dates differ from change dates, and that excessive iteration can suspend the key. This is far beyond minimal disclosure and gives the agent accurate expectations for a sensitive data tool.

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

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

The core result is front-loaded in the first sentence, followed by clearly marked sections for usage, limitations, and data interpretation. The description is long, but most length is justified by rate limits, status semantics, and key-suspension risk. Only a little end-of-description legal/medical boilerplate keeps it from being perfectly concise.

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?

Despite having no output schema, the description tells the agent what the response contains, what status values mean, what they do not mean, and what data is deliberately absent. It also explains coverage semantics and plan limits, so the agent can form correct expectations and avoid forbidden iteration. For a zero-parameter list tool, this is exceptionally complete.

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 input schema is empty, so there are no parameter semantics for the description to add. Per the baseline for zero-parameter tools, the description correctly focuses on return behavior and interpretation instead. This is appropriate compensation for the lack of output schema.

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

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

The first sentence names the exact operation: returning the watchlist of the one Founding Pro account bound to the key, including each product's monitoring state. It also explicitly excludes what it does not return, such as candidate detail, source URL, and internal identifiers, which helps differentiate it from sibling read tools. This is a specific verb+resource description with clear boundaries.

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 listing concrete questions it answers, such as what a person is watching, when products were last read, when the next check is due, and whether anything is unreadable. It also provides when-not guidance by saying it is not a way to read the covered set and that iterating is refused. It does not name sibling tools as alternatives, so it stops short of the strongest possible routing guidance.

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

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

With no annotations, the description fully carries the burden of behavioral disclosure. It discloses that the tool never guesses, what happens for ambiguous and unsupported inputs, and daily limits, including the fact that iterating through products is refused and can suspend the key. It also clarifies the meaning of status values and warns that statuses are about the Record, not about the product. This is exceptionally transparent for a tool that has no annotations and no output schema.

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

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

The description is long but deliberately structured with 'When to use,' 'What it cannot provide,' and 'Limits' sections, making it easy for an agent to scan. Each section carries meaningful operational guidance; the repeated cautions about status semantics and medical-advice disclaimers add length but serve a real purpose for a safety-critical resolution tool. It earns a 4 rather than a 5 because a few clauses are redundant and could be tightened without loss.

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?

Despite having no output schema, the description tells the agent exactly what kinds of results to expect: candidate list, no match, or a status value, and it enumerates the possible statuses. It also covers the daily limit, refusal behavior, and the boundary between Record facts and product facts. For a tool whose calling contract is otherwise mostly unstructured fields, the description is unusually complete.

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 provides only the parameter name and maxLength with zero description. The description compensates by defining the identifier as 'a brand, product name, or alias' and 'a user-supplied product name,' and it explains what kinds of identifiers are meaningul to the tool. A small gap remains: the description does not explicitly label the identifier parameter or state its format, but for a single simple free-text parameter, the compensation is strong.

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: 'Resolve a brand, product name, or alias to one canonical covered product.' It clearly identifies the main output, the canonical product_id, and contrasts with siblings by saying this is the entry point every other capability uses. This unambiguously distinguishes resolve_product from related tools like search_record or get_product_record.

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 'Call this first whenever you hold a user-supplied product name and need the canonical product_id every other capability takes.' It also includes a 'What it cannot provide' section and a 'Limits' section that tells the agent when not to use the tool or how to avoid misuse. This is exactly the kind of when-to-use/when-not-to-use guidance that an agent 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?

With no annotations, the description carries the full behavioral burden and does so exceptionally. It discloses meaningful traits: daily read limits, per-product costs, anti-abuse enforcement, refusal and suspension risk, the meaning and correct reporting of response statuses such as 'supported', 'partial', 'stale', and 'unsupported', coverage limitations, observation-date semantics, and the non-medical-advice caveat. This goes far beyond a basic tool summary and materially changes how an agent should use the response.

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 front-loaded with a crisp one-sentence purpose, followed by well-labelled sections for usage, exclusions, limits, and interpretational caveats. Although it is long, every sentence carries necessary operational or interpretive information; none of it is filler. The structure makes it easy for an agent to scan and extract the relevant constraint.

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 a single-parameter tool with no annotations and no output schema, the description is remarkably complete. It explains what the tool answers, what it cannot answer, how to phrase the query, what limits apply, how to interpret statuses, how to handle limitations, and what not to infer from observation dates. An agent has enough context to call and correctly interpret this tool without additional documentation.

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 only provides 'query' with a maxLength of 300 and 0% description coverage, so the description must explain the parameter. It does: the query must be a single natural-language question, bounded and specific, at most 300 characters, and not used to iterate across products or date windows. This gives the agent practical guidance for constructing valid queries that the schema alone cannot convey.

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 leads with a precise, specific statement: 'Answer one specific, bounded question from FormulaSignal's covered pre-workout Record.' It clearly identifies the resource (the Record), the action (searching/answering), and the scope (single, bounded, about covered products). This also distinguishes it from sibling tools like get_product_record, compare_products, and list_ledger_editions, making the tool's unique role obvious.

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 explicitly enumerates the exact kinds of questions the tool is for: current declarations, changes, cost per serving, and one numeric condition. The 'What it cannot provide' section adds clear exclusions: no database listing, no exports, no medical/suitability answers, and no coverage of products outside FormulaSignal's set. This gives an agent a strong, explicit decision boundary even without naming sibling tools.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It states future alerts stop, already-delivered content stays, and that removal does not erase history. It also discloses plan limits and anti-abuse consequences, which goes beyond the schema.

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

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

The operation is simple, but the description is long and padded with broad FormulaSignal boilerplate about coverage, observation dates, status semantics, and medical advice. These are not specific to unwatch_product and dilute the useful, tool-specific instruction.

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

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

There is no output schema and no annotations, yet the description never clearly states what a successful unwatch returns or how failures/non-watched products are handled. It also misses practical guidance such as using resolve_product to obtain the canonical product_id.

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 provides 100% coverage for the single parameter, product_id, including the key note that it is a canonical FormulaSignal id, not a display name. The description adds no additional parameter-level detail, so the schema 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 opens with a specific verb and resource: 'Remove one product from the bound account's watchlist.' It clearly differentiates from siblings like watch_product by stating the action is stopping alerts, not adding or deleting anything else.

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

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

It explicitly says when to use it: 'Use when a person asks to stop watching a product.' It also gives useful exclusions ('cannot delete an account, cancel a subscription, or remove history'), though it does not explicitly name alternative sibling tools.

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

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

With no annotations provided, the description carries the full burden, and it does so thoroughly. It discloses account binding, coverage limits, watch limits, entitlement refusal, daily read limits, anti-abuse suspension risks, and status semantics. This goes well beyond what a skeletal 'adds a product to a watchlist' description would provide.

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 headers and front-loaded purpose. While some content near the end reads as general platform caveats, the organization makes it navigable, and the constraints are important enough to justify 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 single-parameter tool with no output schema, the description is unusually complete. It explains when to use the tool, what pre-processing is needed, what limitations apply, how responses should be interpreted, and what the tool cannot do. An agent has enough context to invoke it 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 schema already documents product_id as a canonical id, and the description reinforces that an id is required and that names must be resolved first. It also adds that exactly one covered product can be added per call, which clarifies the cardinality and coverage expectation beyond the raw schema.

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

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

Description opens with a direct, specific action: 'Add one covered product to the bound account's watchlist.' It identifies the resource (watchlist), the scope (covered product), and the account binding, and it is clearly distinguishable from sibling tools like unwatch, list_watched_products, and get_product_record.

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' guidance: use when a person asks to start watching a product, and resolve the product first if given a name rather than an id. It also lists exclusions like not starting a subscription and refusing when the account is not entitled. It does not explicitly name alternatives such as unwatch_product or list_watched_products, 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.