FilingDelta

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

Annotations already cover read-only, idempotent, non-destructive behavior, but they do not cover cost. The description adds the critical commercial context: 'Paid USDC on Base', per-bundle pricing, and that unknown ids return 404 with no charge. That is exactly the behavioral disclosure an agent needs before invoking a paid read.

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 constraint ('Paid USDC on Base') is front-loaded, followed by usage, then the complete bundle enumeration. The dense semicolon-separated list is long but every clause carries pricing, contents, or error behavior, so no sentence is wasted.

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

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

With an output schema present, the description needn't explain return values, and it still adds 'Same JSON as the single cards' as a useful compatibility note. Payment, pricing, contents, failure behavior, and a cross-reference to list_filers are all covered, leaving nothing 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?

Schema coverage is 100% and the enum already lists SEMIS, CENTRALBANKS, and BRICS, but the description goes further by unpacking what each id contains and what it costs ($0.06 and $0.08 respectively). This adds real meaning beyond the schema's bare 'Bundle id' label.

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

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

States a specific verb and resource ('get_bundle' → every card in a set at once) and immediately scopes it as a cheaper bulk alternative to buying cards singly. The parenthetical examples (chips filings, major central banks, BRICS central banks) make it distinguishable from sibling singles like get_cpi and get_macro without opening any schema.

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

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

Says explicitly when to call it ('when you need every card in a set at once') and what the alternative is ('cheaper than buying them singly'). It also states the failure branch ('Others return 404 (no charge)') and points to list_filers for discovery, so the agent knows both when and when not to use it.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is to add what they can't: the $0.01 USDC-on-Base payment model, the fact that a 404 for uncovered ids incurs no charge, and that every figure is cited to the statistics office. The no-charge-on-miss detail is exactly the kind of cost/safety behavior an agent needs before spending.

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?

Four tight sentences with no filler, and cost is front-loaded so an agent sees the price before the capability. Minor redundancy: the id enumeration repeats the schema enum almost verbatim, costing a little space for little new information.

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?

An output schema exists, so return shape need not be described. The description covers price, coverage boundary, failure mode, and the free alternative — everything an agent needs to call this correctly and safely.

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 enum already constrains id to US/UK/EA/JP, so the description's id list is partly redundant. It still adds real semantics by stating that non-listed ids yield 404 rather than an error charge, which the schema does not 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?

States a specific verb+resource ('latest inflation (CPI or HICP) print for a covered country or area') and enumerates the payload (headline, core, selected categories, each cited to the statistics office). It also distinguishes itself from the free sibling sample_macro, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use ('Call when you need the latest inflation print'), names the free alternative for the US case (sample_macro id CPI), and states the supported id set plus the consequence for unsupported ids (404, no charge). Both the selection condition and the fallback are spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond the annotations: the $0.01 USDC cost on Base and the fact that unsupported tickers return 404 with no charge. It does not detail the payment flow, but the output schema covers return structure.

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 payment and use-case context, then supported tickers and error behavior. It is mostly efficient, though the long ticker enumeration duplicates the schema enum and adds some 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 presence of an output schema and annotations, the description is complete enough for correct invocation: it covers cost, intended use, distinction from headline data, free alternative, supported universe, and unsupported-ticker behavior.

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 ticker parameter has 100% schema description coverage and an enum, so the schema carries the basic meaning. The description adds useful semantics beyond the schema by listing the supported tickers and specifying that others return 404 with no charge, even though the ticker list partially duplicates the enum.

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: it returns what changed in a company's latest SEC filing versus the prior period. It explicitly distinguishes the output from 'the headline' and points to the free sibling sample_delta, so an agent can identify the tool's role without opening the schema.

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

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

It gives explicit when-to-use guidance ('Call when you need what changed...') and when-not guidance ('not the headline'), plus a named alternative for free sampling: sample_delta. This leaves little inference required for tool selection.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the description adds real value by disclosing the $0.01 USDC charge on Base and that invalid ids return 404 with no charge. The one gap is the payment mechanism itself — whether settlement is automatic or requires a signature — which is the biggest unknown for a paid 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?

Four short sentences with no filler. The cost note is front-loaded ahead of the purpose statement, which is defensible for a paid tool but slightly delays what the tool actually returns.

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

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

With an output schema covering return shape, one fully documented enum parameter, and complete safety annotations, the description fills the remaining gaps: price, valid ids, and error/no-charge behavior. Only the settlement mechanics and the get_cpi overlap are left unresolved.

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 enum already constrains id to NFP/GDP/CPI, so restating the same three ids adds no meaning. The "others return 404 (no charge)" note is the only marginal addition and is somewhat at odds with an enum that makes other values unrepresentable.

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: fetch the latest US CPI, nonfarm payrolls, or GDP release as cited items with the official source. It names the sibling it is not in one respect (sample_macro is the free version), but it never clarifies its relationship to the get_cpi sibling, which plausibly overlaps with the CPI id.

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?

"Call when you need the latest US CPI, nonfarm payrolls or GDP release as cited items with the official source" gives a clear use condition, and "Free: sample_macro" routes cost-sensitive callers to the alternative. It stops short of stating when to prefer get_cpi or get_bundle instead.

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

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

Annotations already cover read-only, idempotent and non-destructive semantics, and the description adds what they cannot: a fixed $0.02 USDC-on-Base cost, the free sibling, and that unsupported ids fail with 404 at no charge. That pricing and failure-billing behavior is exactly the context an agent needs before spending money.

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?

Cost, trigger and return fields are front-loaded in one tight sentence, followed by the free alternative. The long enumeration of all 22 policy ids duplicates the schema enum verbatim and consumes space without adding information.

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?

Price, coverage set, failure mode, free alternative and returned fields are all present, and an output schema exists so return structure needn't be re-explained. Nothing material is missing for an agent to decide and call correctly.

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

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

Schema coverage is 100% with a full 22-value enum, so the parameter is already well documented; repeating the ids in prose is largely redundant. The added value is the semantics of out-of-enum input — others return 404 and are not charged — which the schema cannot express.

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

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

The description names a specific verb and resource — the latest central-bank rate decision — and enumerates exactly what is returned: policy rate, change in bps, vote, next meeting, official source. Sibling names like sample_policy, get_macro and get_cpi are implicitly differentiated by the central-bank-decision scope.

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 states the trigger explicitly ("Call when you need the latest central-bank rate decision") and routes the agent to a free alternative ("Free: sample_policy"). The note that unsupported ids return 404 with no charge also tells the agent what happens if it strays outside the covered set.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, so the description rightly spends its words elsewhere: it is free, it exposes payTo/card dates and content hashes, and default output is a compact projection vs. full: true returning the whole /catalog. It doesn't mention rate limits or response size, which would complete the picture.

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 is front-loaded and tight (free, call first, compact vs full). However, three long enumerations of tickers, policy ids, CPI ids and bundles consume most of the text and are catalog data an agent learns from the response itself, so they crowd out behavioral 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?

An output schema exists, so return values need not be explained, yet the description still names the compact field set. With one optional param, full annotation coverage and a cheap read, an agent has everything needed to call it correctly; only pagination/response-size behavior is absent.

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

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

Schema coverage is 100% and the single param is already documented, so the baseline is 3; the description adds real meaning by naming the exact fields the compact mode returns (ids, prices, as_of, content_hash) versus the full catalog. That is incremental value beyond the property description, though not exhaustive.

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

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

States a specific verb+resource (list the current coverage catalog) and immediately scopes what's inside: SEC filers, central banks, macro/CPI ids, bundles, with prices and hashes. An agent can distinguish this from search_coverage or the get_* fetchers without opening the schema.

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

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

"Free. Call first" gives an explicit entry-point signal, which is the key routing decision for this catalog's siblings. It does not name search_coverage as the alternative when looking for one specific id, so exclusions are implied rather than stated.

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

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

Beyond the annotations, the description adds valuable behavioral details: the request is free, the 'what' field is limited to 500 characters, links and HTML are prohibited, and there are rate limits of 5/hour and 20/wallet/day. It also says it returns 'ok', though it does not explain what happens after submission or how the request is processed.

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 extremely compact and front-loaded: it leads with 'Free', then states the request action, constraints, rate limits, and return value. Every fragment earns its place, with no redundant background.

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?

An output schema exists, so the description need not explain return values in detail. However, with five input parameters and 0% schema description coverage, the description is still too thin on parameter semantics and does not fully explain when to use this tool versus checking coverage through siblings.

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 0% for five parameters, and the description only explains the required 'what' parameter with its 500-character limit and content restrictions. It does not describe the purpose or format of 'wallet', 'contact', 'frequency', or 'price_usd', leaving most parameter semantics undocumented.

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 action and resource: ask for a ticker, bank, or release that the service lacks. It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools such as search_coverage, which an agent might need to check first.

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 phrase 'ask for a ticker, bank or release we lack' implies the usage context: request data that is not already covered. However, it provides no explicit when-not guidance or named alternative workflow, such as checking search_coverage before submitting a request.

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 a safe, idempotent, closed read. The description adds real behavioral context they cannot carry: no payment required, only one change is complete, the rest are gated teasers, and hidden counts/gated_fields/buy_with are surfaced. It does not state rate limits or how partial results are flagged in the payload, so it falls short of a 5.

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

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

The opening clause is well front-loaded, but the sentence is dense with nested jargon (magnitude_basis, size bucket, gated_fields, buy_with) and the 28-ticker enumeration duplicates the schema enum, consuming roughly a third of the text for zero informational gain.

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

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

With an output schema present and full annotations, the description needn't explain return shape, and it still covers the paywall/gating model and eligibility. It is essentially complete for an agent to call it correctly, with only the redundant ticker list and unexplained output field names as minor gaps.

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

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

Schema coverage is 100% and the single ticker parameter has a full enum, so the schema already does the work. The trailing ticker list restates the enum verbatim and adds no semantic meaning, leaving the baseline of 3 appropriate.

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

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

States exactly what it is: a free sample of get_filing_delta, with one change returned in full and the rest as teasers. The name of the paid sibling is embedded, so an agent can distinguish this from get_filing_delta without opening either schema.

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

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

"Use it to test before paying" gives a clear selection context and implicitly routes production use to get_filing_delta. It stops short of an explicit exclusion (e.g. 'do not rely on this for full change data'), so the alternative is implied rather than spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely non-redundant behavior: no payment is required and the output is deliberately truncated, with the item count exposed via comparison_basis. It does not discuss rate limits or auth specifics, which keeps it below a 5.

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

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

One dense sentence, front-loaded with the identifying noun phrase and followed by the two facts an agent needs (trimmed sample, same schema as get_macro). No filler and nothing buried.

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?

The tool is simple: one enum parameter, annotations covering safety, and a full output schema. The description covers the only non-obvious aspects - free versus paid, truncated versus full, and where the truncation count appears - so an agent has everything needed 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?

Schema coverage is 100% and the single 'id' parameter is already enum-constrained to NFP, GDP, CPI. The description repeats those ids and adds no format or semantic detail beyond the schema, so it lands at the baseline for a fully documented 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 names the resource (US macro release card for CPI, payrolls, GDP) and states its scope precisely: a trimmed, free sample of the latest card. It explicitly distinguishes itself from get_macro by saying it has the same schema but is a trimmed view with no payment; only the lack of an explicit action verb keeps it from a 5.

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

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

It makes the primary choice clear - take this free trimmed sample, and get_macro is the full counterpart with identical schema - and it clarifies that the number of returned items is reported in comparison_basis. It stops short of an explicit 'use this when / not when' statement, so it is strong but not exhaustive.

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

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

Annotations already establish a safe read-only operation, and the description adds substantial context beyond them: access='full', sample_of='previous_meeting', a disclaimer, the same schema as get_policy, and a latest object containing only paid metadata and a buy_with pointer. This is exactly the kind of behavioral detail an agent needs.

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 dense and front-loads the free-sample purpose and return shape. It is somewhat long and redundantly repeats the full id enum already present in the schema, but the remaining sentences earn their place by explaining the return structure and paid boundary.

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

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

With an output schema present and annotations covering safety, the description still supplies the critical missing context: what the free sample contains, how it differs from the paid current card, and what the latest object exposes. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter has a full enum with description. The description repeats the policy id list but adds no syntax or format detail beyond what the schema already provides, 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 states a specific resource and scope: a free sample rate-decision card covering a central bank's PREVIOUS meeting, with full card fields. It explicitly distinguishes this from the paid get_policy card that contains the current decision.

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

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

It clearly says this tool provides the previous meeting for free and that the current decision is in the paid get_policy card, which gives the agent a practical alternative. It stops short of an explicit 'use this when...' sentence, but the routing is 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?

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable context beyond that: the tool is free, returns a tool recommendation rather than actual data, and should be followed by request_data when coverage is missing. Auth or rate-limit behavior is not described, but the annotations reduce the burden.

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 three short, front-loaded sentences with no wasted text. The core action, return behavior, and fallback are all communicated efficiently.

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 an output schema exists and annotations cover the safety profile, the description is largely complete: it explains the routing purpose, fallback path, and cost context. A small gap remains around query syntax and matching behavior, but an agent can still 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 single query parameter has 0% schema description coverage, so the description must compensate. It does so partially by saying the query can be a name or topic, but it does not explain format, examples, matching behavior, or constraints such as the 100-character limit.

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 ('find') and names the exact resource scope: covered companies, central banks, and US macro releases. It also distinguishes itself from retrieval siblings by stating that it 'Returns the tool to call,' and it names the fallback sibling request_data for missing coverage.

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

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

It clearly indicates when to use the tool: when looking up a covered entity or release by name or topic. It also names the alternative request_data for missing items, though it does not explicitly state when not to use this tool or compare against other siblings.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the description adds useful context beyond them: the tool is free, returns one-line headlines, and provides content_hash so unchanged cards can be skipped. It does not state what happens when the optional 'since' parameter is omitted.

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 two tight sentences, front-loading the tool's purpose and then the fallback path. Every phrase earns its place.

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?

An output schema exists, so the description need not explain return values in detail, and it already highlights the important content_hash and headline fields. The main gap is the unstated behavior when the optional 'since' parameter is omitted.

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 one optional 'since' parameter with a YYYY-MM-DD pattern in the schema, but schema description coverage is 0%. The description mentions 'since a date' but adds no format, default, or omission behavior, so it fails to compensate for the lack of schema descriptions.

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 resource and scope: cards changed since a given date, with headline fields and content_hash. It distinguishes itself from request_data for coverage gaps, though it does not explicitly differentiate from other sibling tools like get_filing_delta or get_bundle.

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 a clear alternative path: if coverage is missing, use request_data. However, it does not explain when to choose this tool over related siblings such as get_bundle or get_filing_delta.

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