KeyVex

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

Annotations cover only the safe-read profile; the description carries everything else. It discloses the January 2024 ingestion floor and that pre-2024 queries return zero by boundary rather than entity gap, explains that 13D/A exit rows with shares_owned:0 are correct rather than missing data, and warns that include_filing_narrative adds ~58.5% to each row / ~548 KB per 50-row page. That is exactly the kind of behavior an agent cannot infer from structured fields.

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

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

Front-loaded with the definition, then bolded subsections for 13D vs 13G, coverage floor, exit filings and the narrative flag, so a skimmer hits the decision-relevant facts first. It is long and the 'THIS TEXT USED TO SAY Item 4 WAS NOT AVAILABLE' passage is meta-commentary that costs space, but almost every other sentence 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?

For a 14-parameter, no-output-schema research tool, the description supplies the domain frame (13D/13G semantics), the coverage boundary, the zero-value edge case, and the optional-heavy-field tradeoff — everything an agent needs to call it correctly and interpret empty or zero results. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: is_activist is framed as the 13D-intent vs 13G-passive distinction, include_filing_narrative is explained item-by-item (Item 2/2(d)-(e)/3/4/6) with its cost and its 13D-only limitation, and min_percent_of_class is offered as the way to separate live stakes from exit rows. It stops short of adding syntax beyond the 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?

States a specific verb+resource ('Returns Schedule 13D / 13G beneficial-ownership disclosures'), defines the record grain (one reporting person per filing, joint filings emit multiple rows), and pins the 5% threshold that makes the data meaningful. An agent can distinguish this from get_institutional_holdings, get_insider_filings and get_proxy_filings 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?

Explicit when-to-use list ('who's accumulating large stakes, activist campaigns, takeover targets, hostile bids, institutional concentration'), plus the exact user phrasing it answers. It also names the internal alternative — filter is_activist:true for signal vs the 13G 'firehose' of routine Vanguard/BlackRock quarterly filings — which is a genuine routing decision.

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 only declare readOnly/openWorld/non-destructive. The description adds substantial behavioral context the annotations cannot: it is a CURRENT-roster monthly snapshot of a daily-updated FAA file, snapshot_date staleness implies deregistration, deregistered history is a planned (not yet available) follow-up, and results are FAA records republished verbatim rather than inferred. These disclosures directly shape how an agent should interpret and caveat results.

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?

Content is front-loaded: what it returns first, then use cases, then lookup semantics, then caveats. Most sentences earn their place given nine parameters and no output schema. It is somewhat over-long and includes mildly editorial framing ('Pure-publisher posture ... parsed by KeyVex'), plus a stray hyphen in 'Deregistered- aircraft', but nothing that obstructs use.

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

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

With no output schema, the description carries the full return-value burden and does so: it enumerates the aircraft and registrant fields, the five-co-owner cap, the FAA type-code legend, and the snapshot/staleness semantics. Combined with 100% parameter coverage and read-only annotations, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all nine parameters (including n_number's N-prefix tolerance and registrant_name's co-owner matching). The description reinforces those semantics and adds interpretive nuance for registrant_name — that a missing company match does not disprove ownership — which meaningfully aids filter choice.

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+resource ('Returns FAA aircraft registrations') and quantifies scope (~314K US-registered aircraft, one record per N-number). It further enumerates exactly what a record contains (aircraft attributes and registrant details), so the agent knows precisely what it is getting and can distinguish it from any sibling in this large tool set.

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 enumeration of triggering user intents: 'who owns an aircraft (by N-number), what aircraft a company / person / nonprofit registers, corporate-jet fleets, aircraft registered in a state, or to join tail numbers seen in flight-tracking data to owners.' It also supplies a crucial when-interpreting caveat (trustee-bank and management-LLC registrations mean an absent company name is not proof of no ownership). No sibling overlaps, so no alternative needs naming.

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 burden and does so: it discloses dedup behavior ('a later modification of an award you were already alerted to does not alert again'), the no-history-replay rule, that each alert's data has KeyVex internal `_` fields stripped, pagination via next_cursor, and the full webhook contract (HMAC signature over '<timestamp>.<raw body>', 5-minute replay window, no redirects, 5s 2xx deadline).

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 first sentence front-loads the core identity and the kind list follows immediately, with eligibility and webhook rules after. It is dense but nearly every clause carries operational meaning; the webhook paragraph is the only slightly tangential block for a read/polling tool.

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

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

Despite having no output schema, the description explains the shape of the returned `data` (the source record as stored, internal fields removed) and the pagination token, and it clarifies authentication scope (the API key determines whose watchlist) and where the watchlist is managed. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the prose goes beyond it: it enumerates and defines each enum value for `kind` (congress_trade, initial_13d, federal_contract) and confirms cursor usage ('Paginate with next_cursor'). The semantics of `since` and `limit` are left to the 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?

States a specific verb and resource ('Your watchlist alerts, newest first') and scopes it precisely to events matched against the tickers, members and UEIs on YOUR watchlist for the calling API key. It distinguishes itself from raw-data siblings by noting 'the matching tool may present the same record differently,' so an agent knows this is the alert feed, not get_congressional_trades or get_federal_contracts.

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?

Explains what each of the three kinds means and states the eligibility condition (event date within 7 days of detection and not before the entry was added), which tells the agent exactly when results appear. It implies the raw-source alternatives ('the matching tool may present the same record differently') but never explicitly says when to prefer those over this feed, so it falls short of full when/when-not 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?

Annotations cover the read-only, non-destructive, open-world profile, and the description adds substantial behavior beyond that: content_parsed/coverage_note flags, parse_unreliable rows with report_url as authoritative, House vs Senate parsing differences, income_range empty cases, and the deliberate omission of net-worth roll-ups. This is exactly the added context the dimension rewards.

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

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

Front-loaded with the core purpose, then organized into SCOPE, CONTENT, USE-this-when, and DIFFERENT-from blocks, so a long description is justified by the 12-parameter surface. A few sentences (the 'honest coverage boundary is never a silent omission' framing) lean rhetorical rather than informative, keeping it short of 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?

For a 12-parameter, no-output-schema, open-world disclosure tool, the description covers chambers, filing cadence, report types, parse reliability, data provenance, and the intentional coverage boundaries. Nothing an agent needs to call it correctly or interpret results is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it defines each report_type flavor ('Annual' covers prior calendar year, 'New Filer' initial disclosure, etc.) that the schema only labels as 'one filing flavor', and clarifies the range-vs-point-estimate semantics of value_range/amount_range. It does not add syntax detail for the remaining filters.

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 (returns Form 278 annual financial disclosure filings), enumerates the content (assets, income sources, liabilities, transactions, gifts, outside positions) and explicitly differentiates from the sibling get_congressional_trades with a clear PTR-vs-year-end-snapshot contrast. An agent can identify this tool 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?

Provides an explicit 'Use this when the user asks about...' list (asset composition, outside income, board seats, liabilities, news reporting) plus a named alternative and a combine-both recommendation for the full activity+position view. Both when-to-use and the sibling relationship 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 readOnly/destructive/openWorld, and the description adds substantial context beyond them: Call Report provenance, ~4,400 institutions and 1984-present coverage, the YTD income-statement convention, FDIC-annualized ratios, the ~60-day progressive fill for the latest quarter, and the 'pure-publisher, no derived health scores' caveat.

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

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

Front-loads purpose and is well-organized under labeled sections (CONVENTIONS, Matching a bank, League tables), with each section carrying usable content. It is dense and long, but almost every sentence earns its place; minor trimming would still be possible.

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?

No output schema exists, and the description fully covers the return shape (identity, balance sheet in $ thousands, income statement, FDIC ratios) plus conventions and key-resolution guidance. 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%, so the baseline is 3, but the description adds real workflow meaning: cert is the exact stable key to resolve once via a name substring, the report_date + sort_by='total_assets' league-table recipe, and valid quarter-end formats. It does not add syntax beyond the schema, so it stops short of 5.

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

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

States a specific verb and resource ('Returns quarterly financials for every FDIC-insured US bank') with scope and provenance, and explicitly distinguishes itself from the sibling get_fundamentals as 'the banking-sector complement.' An agent can identify the tool 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?

Provides an explicit when-to-use list (assets/deposits/profitability/capital ratios, league tables, deposit flight, NPA trends, pairing with enforcement/complaints) and names the alternative (get_fundamentals) plus the condition that selects it (parent holding company SEC financials).

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/openWorld/non-destructive, and the description goes well beyond by disclosing exactly what v1A returns (metadata only) versus what is deliberately not included (sponsors, cosponsors, action history, text, CRS summaries), plus the 'pure-publisher, no predictions' posture. This is rich behavioral context not present in structured fields.

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

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

Front-loaded with purpose and usage before details, and every section serves a purpose. It is lengthy and the full bill-type enumeration partially duplicates the bill_type enum already documented in the schema, which is mild redundancy, but overall it is well organized and skimmable.

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

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

With no output schema, the description carries the full burden of describing returns and does so explicitly (title, type+number, originating chamber, latest action, links) and redirects to api_url/congress_gov_url for detail. Nothing an agent needs to call this 12-param, all-optional tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the composite {congress}-{TYPE}-{number} key format, that bill_id is the fastest direct-lookup path, and the semantic distinction between latest-action filters and introduction-date filters. It reinforces rather than merely repeats the 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?

States a specific verb+resource (returns congressional bill metadata) plus scope (all bill types, from api.congress.gov). It explicitly distinguishes itself from siblings by naming the roll-call-vote bridge use case and pointing prose detail to other sources, so an agent can tell what it does versus get_roll_call_votes or unified_search.

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

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

Gives an explicit when-to-use list mapped to concrete user questions (bills this Congress, status of a specific bill, House vs Senate volume, topic mentions, roll-call bridge). It also names the fastest path (use bill_id) and disambiguates since/until vs introduced_since in the schema. Alternatives and exclusions are covered.

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 the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false), and the description adds real context beyond them: Friday 3:30 PM ET release cadence for the prior Tuesday close, the public Socrata endpoint, free/unauthenticated access, and the 'pure-publisher posture' with no derived sentiment scores. It stops short of pagination or rate-limit behavior, so a 4 rather than 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?

Purpose is front-loaded in the first sentence, followed by release timing, trader classes, query patterns and provenance in a logical order. It is long and the trader-class/query-pattern blocks are somewhat list-heavy, but nearly every sentence carries decision-relevant information, so only mild trimming is warranted.

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 10 parameters, no required params, and no output schema, the description does the heavy lifting well: it explains the dataset, coverage, freshness, and the derived fields an agent will see in results. It omits pagination/return-shape details and the meaning of the concentration fields beyond a brief mention, leaving 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%, so the baseline is 3, but the description adds value the schema does not: it demonstrates how parameters combine (latest_only semantics, sort_by='noncomm_net' with sort_order='desc', commodity_name='GOLD' + since=) and names the derived fields (noncomm_net, comm_net, nonrept_net) that back the sort enum. That is meaningful enrichment over the structured fields.

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 ('Returns CFTC Commitments of Traders (COT) report rows') and immediately defines the payload: weekly aggregated futures + options-on-futures positioning by trader class. No sibling tool covers COT data, so an agent can place this unambiguously.

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 'Killer query patterns' section gives concrete, goal-oriented parameter recipes (latest_only=true for a weekly snapshot, commodity_name + sort_by='noncomm_net' for large-spec extremes, since= for history). It does not name a when-not-to-use condition or an alternative tool, which keeps it short of a 5, but the usage context is clear and actionable.

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

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

Annotations cover only the read-only safety profile, and the description adds substantial behavioral context beyond them: per-field provenance envelopes (source_type, fetched_at, as_of), UNKNOWN/INSUFFICIENT_DATA staleness semantics, paid-plan gating for price_eod, unlicensed stub fields, and the assembled-not-mirrored caveat. This is exactly the kind of disclosure the annotations cannot carry.

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

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

The field enumeration is front-loaded and the key constraints are stated early, but the description is very long and dense, with some detail (Tiingo attribution, the price_iex_last stub note) that adds bulk relative to decision value. It is informative but not tightly trimmed.

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 carries the full burden of describing return values, and it does so thoroughly — enumerating fields, provenance, staleness handling, and error behavior. 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%, so the baseline is 3; the description adds real value beyond the schema by specifying that ticker matches only current EDGAR-listed tickers (renamed/delisted miss, use CIK) and that ambiguous tickers return a named-candidate error. It also notes the hyphen convention for class shares.

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 ('Returns ONE company's reference profile') and enumerates the exact fields returned, so an agent knows precisely what it gets. It explicitly distinguishes itself from siblings like get_daily_prices (price history) and get_federal_contracts (contract detail).

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 explicit lookup rules ('exactly one of ticker/cik'), names the failure modes (renamed/delisted tickers miss, ambiguous ticker errors with candidate CIKs), and routes follow-ups to get_daily_prices and get_material_events. When-to-use and when-not-to-use are both covered.

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 only declare read-only/open-world/non-destructive; the description goes well beyond by disclosing the up-to-45-day reporting lag, the disclosure_date vs transaction_date distinction, that amounts are ranges not exact values (11 standard STOCK Act brackets), and how party is attributed for dates outside a member's terms. These are material interpretation caveats an agent cannot get from the annotations.

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

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

Front-loads what the tool returns, then usage, then the 'Important' caveats block — a sound ordering with no redundancy against the schema. It loses a point for the promotional sentence ('published free as news at https://keyvex.com/disclosures'), which does nothing to help an agent select or invoke the tool.

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

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

For a 16-parameter, no-output-schema tool, the description supplies the domain model an agent needs (lag, date semantics, ranges, amendment/supersession implications at a high level). The response envelope fields (superseded_rows_included, coverage_warning, unclassifiable_records_retained) are only explained in schema text, so return-shape expectations are not fully covered here.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine query-level meaning: which date field to sort/filter on for which question, how amount ranges map to amount_min/amount_max for filtering, and what owner/party values actually represent. It does not touch the heaviest parameters (exclude_superseded, include_non_open_market), which remain schema-only.

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 ('Returns trade records disclosed by U.S. members of Congress under the STOCK Act') and pins the exact sources (Senate eFD and House Clerk PTRs), plus the granularity ('each record is one disclosed transaction by a member or their immediate family'). An agent can distinguish this from get_insider_transactions or get_annual_financial_disclosures on the entity alone.

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 explicit triggering questions ('who in Congress traded a specific stock', 'what trades a specific member made', 'recent congressional trading activity', 'filings within a date range') and even routes between sort_by choices for two question shapes. It does not name alternatives or state when NOT to use it (e.g., use get_member_profile for enrichment, which is only mentioned in the schema), so it stops short of a 5.

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

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

With readOnlyHint/openWorldHint already covering the safety profile, the description goes further: it explains the live-vs-cache fallback, the presence of a coverage_warning, that volume must not be inferred in cache mode, and that total_count is authoritative but omitted when issue/sub_product filters are active. These are non-obvious operational traits that materially affect interpretation. It stops short of covering pagination mechanics or rate limits.

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?

Well front-loaded: purpose first, then usage, then coverage/behavioral caveats. The taxonomy and company-response value lists are long but genuinely useful for constructing valid filters; a couple of enumerations 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?

With 13 optional params, no output schema, and open-world behavior, the description compensates fully — it explains the return surface (total_count vs results, source, coverage_warning), filter interactions, and fallback semantics. An agent has everything needed to call and interpret 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%, so baseline is 3, but the description adds real meaning: it enumerates the exact product taxonomy values and clarifies that company matching is word-based rather than arbitrary-substring. It also warns that issue/sub_product are applied post-upstream (changing what total_count means), 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?

The description opens with a specific verb+resource ('Returns consumer complaints filed with the CFPB') and defines the record granularity ('Each record is one filing against a bank, credit reporting agency...'). It names the concrete fields returned (company response status, timeliness flag, narrative), which clearly separates it from siblings like get_enforcement_actions.

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 enumerates explicit use cases ('complaint volume against a specific company, top issues at a credit reporting agency, regional complaint patterns, untimely responses...'), including forward-looking use as an enforcement indicator. It also names an alternative and the condition to pair with it (get_enforcement_actions with source-specific params), which is exactly the when/when-with guidance the dimension rewards.

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 only cover readOnly/openWorld/destructive, but the description adds substantial operational behavior beyond them: live-first querying over a ~12.9M-application index, since/until applied at the source, fallback to a cached recent slice on outage with source:'cache' + coverage_warning and the warning not to infer totals, and browse behavior with no company_name. This is exactly the kind of context annotations cannot carry.

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

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

Front-loaded and logically ordered (returns → usage → caveat → coverage), but over-long for the content; the list of eleven example applicant strings is excessive and the coverage paragraph is dense. Several sentences restate schema content, so not every sentence 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?

No output schema exists, so the description must cover return semantics, and it does: record shape, source_url follow-up, live/cache coverage semantics, and the applicant-naming pitfall. For a 6-param, complex, open-world tool this is complete enough to 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%, so baseline is 3, but the description adds real meaning: the critical caveat that patents are filed under an IP-holding entity rather than the household brand (with 11 concrete legal-string examples), case-insensitive matching, and the live-vs-cache behavior tied to company_name. Some of this duplicates the schema descriptions, so it is above baseline but not fully additive.

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 precise verb+resource: returns US patent applications from the USPTO Open Data Portal, keyed on the corporate APPLICANT. It enumerates exactly what each record contains (title, applicants, inventor count, dates, status, entity size) and names the follow-up source (source_url at USPTO Patent Center), so an agent knows precisely what it gets. No sibling tool covers patents, so differentiation is inherent.

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 explicit, concrete usage contexts ('what is a company patenting', 'how many patents did a company file', cross-referencing R&D against insider/congressional activity, contracts, fundamentals). This maps user intent to the tool clearly, though it never states when NOT to use it or names an alternative sibling.

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 read-only, non-destructive, open-world behavior. The description goes well beyond them: it discloses the pure-publisher posture, that financials are issuer-reported and generally unaudited, that fields are null where a variant omits them, and the C → C-U → C-AR chain structure — genuinely useful context an agent needs to interpret results.

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?

Dense but well front-loaded: what it returns first, then usage, then enum mapping, then exclusions and caveats. Every sentence carries information, though the block is long enough that a tighter edit is conceivable.

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

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

With no output schema, the description carries the full burden and does so — it enumerates the returned fields (issuer, portal, offering terms, financials, employee count) and flags the caveats that affect interpretation. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema: it maps filing_type enum values to form families, explains the cik + sort asc pattern for reading filing chains, and notes null-semantics for financial fields. Minor gap: it references is_withdrawal, which is not an exposed 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?

States the specific resource (SEC Form C filings / Reg CF offerings), the covered period (2016-05→present), and the exact record shape. It explicitly names and excludes sibling form families (Reg A+ via get_reg_a_offerings, Reg D via get_private_placements), so an agent can disambiguate without opening a 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 'Use this when the user asks about:' list of concrete intents (portal market share, early-stage issuers in a state, revenue/assets of a crowdfunding company) and routes alternative form families to named sibling tools. Both when-to-use and when-not-to-use are present.

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 flag readOnly/openWorld/non-destructive, and the description layers on genuinely useful behavior: paid-plan gating, no pagination (full window in one call), survivorship-bias-free coverage back to 1962, weekly/monthly aggregation semantics (first open, highest high, lowest low, summed volume), and the Tiingo data source.

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

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

Front-loaded with the core purpose and scope, and each sentence carries information an agent needs (coverage, plan gating, row schema, flag behavior, pagination). Dense but not padded; slightly long, so not a clean 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?

For a read tool with no output schema, the description effectively documents the returned row fields and their adjusted variants, coverage limits, and aggregation behavior, leaving nothing material an agent would need before calling it.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further, explaining what adj_close is for ('use THIS for charts and return calculations'), that div_cash is tied to the ex-date, and how include_ohlc aggregates on weekly/monthly—interpretation the schema alone doesn't 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 and resource ('returns daily end-of-day closing-price history for one US-listed ticker') plus the instrument scope (stocks, ETFs, mutual funds, delisted names). This cleanly separates it from intraday quote, fundamentals, and holdings siblings without ambiguity.

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 concrete when-to-use guidance: prefer frequency='weekly'/'monthly' for multi-year ranges, and 'one call = one ticker, compare with multiple calls.' It states the PAID PLANS ONLY prerequisite. It stops short of naming specific sibling tools to prefer over this one (e.g. intraday vs daily), so 4 rather than 5.

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

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

Annotations cover the safety profile (readOnlyHint, openWorldHint, destructiveHint), and the description goes well beyond them: EDGAR coverage windows by form family (15 from 1994, issuer 25 from mid-2001, 25-NSE from 2005 Q4), which fields are XML-populated vs metadata-level, and the 'pure-publisher posture' read-only guarantee.

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 sentence is front-loaded with the core purpose and the subsequent dense passages on coverage windows and field provenance earn their place for a 10-parameter tool. It is long and could be broken into clearer sections, but there is little redundant filler.

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

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

With no output schema, the description still explains the return surface (structured 25-NSE XML fields, 15-family records are metadata-level, follow filing_index_url for the document) and the historical coverage limits. An agent has everything needed to call and interpret the results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real interpretive meaning: action='delisting' vs 'deregistration' is a faithful form-to-rule mapping, 25-NSE is filed by the exchange (exchange_name/exchange_cik set) while a bare 25 is issuer-filed, and rule_provision carries the cited provision verbatim.

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 specific resource (SEC delisting/deregistration filings) and distinguishes the Form 25 family from the Form 15 family, including the Rule 12d2-2 basis and the 15F foreign-issuer variant. An agent can tell exactly what this tool returns and how it differs from other SEC-filing siblings 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 enumerates concrete user intents ('was/is a company being delisted', 'which companies went dark recently', 'what securities did an exchange remove') and suggests pairing with tender offers/8-Ks/insider sales around an exit event. This is clear context, but it never names a competing tool as an explicit alternative nor states 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 cover the safety profile (readOnlyHint, openWorldHint, destructiveHint=false), yet the description adds substantial context: a LIVE passthrough, the fact that total_count is authoritative while the results array is only the requested page, that records are 5-15KB and limit should stay small, and FDA's own caveat that reports are unverified with no denominator. This is genuinely additive beyond structured data.

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

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

Front-loaded with what the tool returns and well-organized into matching/filter/caveat blocks. It is dense and long (~250 words) with mild repetition in the honesty note, but nearly every sentence earns its place for an 11-param, output-schema-less tool.

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

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

With no output schema, the description carries the return-value burden and does so: records are openFDA fields verbatim, deeply nested (patient.drug[], patient.reaction[]), 5-15KB, while count_by returns top terms plus counts and total_count is the authoritative filtered count. Nothing an agent needs to call and interpret it is missing.

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

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

Schema coverage is already 100% (baseline 3), but the description exceeds it with matching semantics not in the schema: drug matches brand/generic/verbatim product as a PHRASE, reaction is a MedDRA phrase, serious vs. outcome are distinguished, since/until window on receivedate, and a concrete count_by example. It meaningfully deepens parameter understanding.

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

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

States a specific verb and resource ('Returns FDA FAERS drug adverse-event reports') with scope (~20M reports, 2004→present, live passthrough to openFDA). It explicitly distinguishes itself from adjacent tools by describing its role alongside recalls, approvals, and insider activity, so an agent can place it among the ~65 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?

Gives an explicit 'Use this when the user asks about' list (safety signals, reactions, outcome counts, manufacturer footprint) and goes further with a decision rule: count_by is 'the right first move' for side-effect questions, followed by a record query for detail. This is exactly the when/when-not/alternatives guidance the dimension asks for.

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

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

Annotations cover only the safety profile (readOnlyHint, openWorldHint, destructiveHint), and the description adds substantial behavior beyond that: the 'pure-publisher posture' disclaimer that no YoY deltas or alternate seasonal adjustments are computed, the fact that units live in a `unit` field, the client-side dedup of daily series under latest_only, and the fiscal sign convention (positive = deficit). This is exactly the extra context annotations cannot carry.

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

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

Front-loaded with the purpose and then organized into scannable bullets (sources, trigger phrases, categories, period format, latest_only, posture), so an agent can find what it needs quickly. It is still long, and the per-source bullets partially restate the `source` enum description in the schema, which is mild redundancy rather than waste.

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

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

With no output schema, the description carries the full burden and does so: it explains what a record contains (series, unit field, period), the period encoding, sign conventions, and that raw values are unmodified so agents compute derived metrics themselves. For a 10-parameter, zero-required cross-source tool, nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes further by explaining the fixed-width period format (2026M04, 2026Q01, 2026W18, 2026D258) so lexicographic sort equals chronological, describing what each `source` value contains, mapping the `category` buckets to concrete series, and clarifying the `latest_only` snapshot behavior. That materially enriches semantics the schema alone only gestures at.

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

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

The opening sentence states a specific verb+resource (returns observations of key US macro, energy, and fiscal indicators) and immediately names the four publisher sources. It is easily separable from siblings like get_daily_prices, get_fundamentals, or get_treasury_auctions because it scopes itself to macro indicator series across BLS/FRED/EIA/FiscalData.

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 extensive explicit trigger list ('Use this when the user asks about: unemployment rate, jobs report, CPI / PCE, Fed Funds rate, national debt...') plus a category taxonomy for filtering, which gives an agent strong positive routing signals. It never states when NOT to use it or names a sibling alternative for overlapping cases (e.g., Treasury auction or price data), so it falls short of full when/when-not 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?

Annotations only declare readOnly/openWorld/destructive=false; the description goes well beyond by disclosing per-source freshness and window behavior (SEC rolling ~50-item RSS, DOJ latest ~200, CFTC HTML scrape with no body extracted), the v1A truncation cap (~3000 chars, empty for CFTC), stable identifier formats per source, and Fed terminated_date semantics. It also states the 'pure-publisher posture: no derived severity or outcome prediction', which prevents an agent from expecting scoring signals.

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

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

Front-loads purpose, then trigger scenarios, then a scannable per-source block with aligned labels, ending with cross-source tips — a sensible structure for an 8-source aggregator. It is long (~450 words) and the source list is effectively restated three times (trigger list, source definitions, schema enum), which costs it a point, but nearly every sentence carries non-redundant operational detail.

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 and 10 optional parameters, the description carries the full burden and does: it describes returned field semantics (topics[], agency_component, release_number, terminated_date, url pointing at the consent-order PDF), the v1A teaser-vs-full-prose split, and action_id composition per source. An agent has everything needed to call and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the enum documentation: it explains that OCC bulletins are filtered out while OCC-only and interagency releases are included, that titles are mixed SEC enforcement/policy items requiring substring narrowing, and that agency_component is empty for most SEC items. That is substantive per-parameter context the schema alone 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?

Opens with a specific verb and resource — 'Returns SEC + DOJ + CFTC + OCC + FDIC + FTC + Federal Reserve + FinCEN enforcement-related actions' — and the tagline 'Eight regulators, one tool' makes the scope unmistakable against siblings like get_epa_enforcement or get_osha_enforcement. An agent can tell exactly what this tool aggregates 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?

Explicitly enumerates trigger scenarios ('recent SEC charges, DOJ indictments, CFTC derivatives/swaps enforcement, ... insider trading prosecutions, FCPA actions') and names the specific condition for cross-checking ('to add a negative event flag'). It also closes with cross-source guidance naming two sibling tools (get_insider_transactions, get_activist_stakes) and when to pair them.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable non-obvious behavior: refresh cadence (weekly, ~Saturday), publisher posture with no derived severity scores, source exclusion constraints, and the sort_by/filter incompatibility. It doesn't discuss pagination depth or result-size limits beyond the schema, which keeps it 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?

Front-loaded with the source identity and exclusions, followed by use-cases, record shape, and filter caveats in a logical order. It is long and information-dense, but nearly every clause earns its place; the record-shape enumeration is the bulkiest part and slightly exceeds what an agent needs upfront.

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 12-parameter read-only query tool with no output schema, the description covers source scope, exclusions, refresh timing, record semantics (including which fields join pre-flattened), date-filter semantics, sort restrictions, and cross-source complements. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds meaningful semantics beyond the schema: status_date is defined as the case's last status-change date present on every case, fed_penalty cannot be combined with since/until, and the settlement-lodging prevalence (~34%, mostly judicial) is surfaced. That is genuine added meaning over the structured fields.

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 (Returns) and resource (EPA federal civil enforcement cases from ICIS FE&C via ECHO bulk download), quantifies scope (~135K cases), and explicitly distinguishes this source from siblings by excluding criminal prosecutions and state-lead actions. An agent can immediately tell it apart from get_enforcement_actions and get_osha_enforcement.

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 trigger list (EPA fines, CAA/CWA/RCRA/Superfund enforcement, settlements, SEPs) plus explicit exclusions and cross-source pairing guidance (get_enforcement_actions, get_federal_contracts, get_material_events). This is close to ideal 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?

Annotations already cover the safety profile (readOnlyHint, destructiveHint, openWorldHint), and the description adds genuinely new behavioral context: full historical depth, the sponsor-name matching caveat (no ticker/CIK, subsidiaries file under own names), and the explicit 'pure-publisher posture: no derived approval odds' disclaimer. It omits return/pagination behavior, but that is minor given the annotation coverage.

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?

Purpose and scope are front-loaded, and virtually every sentence carries information. The source-feed block is verbose and heavily indented, pushing length well beyond what most callers need, but the density is justified by the 13-parameter surface and four enums.

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 13-parameter, zero-required, no-output-schema tool spanning three FDA feeds, the description covers source semantics, decision codes, matching behavior, historical ranges, and data provenance. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial interpretive meaning beyond the schema: decision_code semantics (AP vs TA tentative approvals blocked by patent), application_number prefixes denoting product class (NDA/ANDA/BLA), and review_priority as the 'high-signal filter for catalyst hunting.' This is far beyond what the schema fields state.

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?

Opens with a precise verb+resource ('Returns FDA approval / clearance events') and enumerates the three concrete feeds (Drugs@FDA actions, 510(k) clearances, PMA decisions). It explicitly distinguishes itself from a sibling by naming get_product_recalls as its 'BULLISH twin,' so an agent can route without opening schemas.

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 trigger list ('Use this when the user asks about: new drug approvals... priority-review approvals... device clearances by company or product code... PMA supplements') and even names cross-tool pairing targets (insider trades, 8-K filings, fundamentals). This is clear when-to-use guidance with an alternative named.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context beyond that: the default include_committees=true triggers a committee enrichment fetch, the cycles tracked (2022/2024/2026), and that active_only=true restricts to status='C'. It does not discuss pagination or rate limits, so a 4 rather than 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?

Front-loaded with purpose and usage triggers before the reference-code detail, and most sentences earn their place. However the office codes, party codes, and incumbent_challenge codes restate enums already present in the schema, adding length without 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?

For a 12-parameter, zero-required, no-output-schema tool, the description covers lookup strategy, filtering dimensions, default behaviors, and the FEC domain code systems an agent would otherwise have to guess. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description nonetheless adds meaning beyond the schema by explaining the LASTNAME, FIRSTNAME filing convention, the designation=P 'principal committee is the one you want for donations' heuristic, and committee_type semantics for following money. The office and party code lists largely duplicate the schema enums, which caps this below 5.

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

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

States a specific verb and resource (FEC-registered candidate profiles plus their committees) and clearly bounds scope: House, Senate, President. It also implicitly distinguishes itself from the sibling contribution/disbursement tools by naming itself the bridge to committee_id, so an agent can place it 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?

Gives explicit triggering questions ('who's running in race X', 'the campaign finance ID for a member', 'what PAC is sponsoring a candidate') and the workflow position ('bridge from a Congressional member name to their FEC committee_id before looking up contributions'). It also states the fastest lookup path (candidate_id) versus the name-based path.

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?

Far exceeds the annotation baseline (readOnly/openWorld only). It discloses a cached-rollup fallback with a source: live|cache flag, day-lag on rollup lists, the complete flag vs page-cap approximation, the small-cell withholding floor (<5 individuals → suppressed_small_cells), memo-subtotal exclusion defaults, and the $1,000 itemization floor. Consent-vs-cost warnings (contribution_count is contributions, not contributors) go well beyond structured fields.

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

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

Front-loaded with purpose before any details, and the numbered mode structure with ⚠ callouts and example queries is easy to scan. It is long, and the 'NO NATURAL PERSON IS NAMED' prohibition is restated at least three times across the text, which is padding even for a compliance-sensitive tool.

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

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

For a 17-parameter, three-mode, no-output-schema tool, the description is complete: it explains mode selection, required combinations, response envelope flags (source, complete, suppressed_small_cells), and what is structurally absent from output (no addresses, no per-record individual rows). An agent needs nothing further 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% so the baseline is 3, but the description adds real meaning the schema cannot: which parameters combine into each of the three modes, that contributor_employer is leaderboard-scope-only, and that min_amount is ignored in leaderboard mode. It does not restate every field, which is appropriate when the schema already carries it.

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

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

The opening sentence gives a specific verb, resource and scope: 'Returns FEC Schedule A contribution data — money flowing INTO federal committees — in AGGREGATED form.' It immediately distinguishes itself from siblings (get_fec_disbursements covers money out, get_fec_candidate_profile is a lookup) and the three-mode structure makes the output shape unambiguous.

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

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

Explicitly enumerates three modes with the exact parameters each requires, states what is not accepted (min_amount in leaderboard mode, contributor_employer as a per-record filter), and closes with five 'killer query patterns' that route the agent to the right mode. Alternatives and prerequisites are named, not inferred.

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/openWorld/non-destructive, yet the description adds substantial behavior the agent could not infer: per-record withholding of individual payees under 11 CFR 104.15, the $1,000+ cached-subset floor, publication lag by filer type (~20 vs ~50 days), and the memo double-counting default. These are exactly the traits that change how an agent should interpret empty results.

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

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

Front-loaded and clearly sectioned, but roughly 400 words with noticeable repetition — the memo/exclude_memos behavior and the organisation-only rule are each explained in both the description and the schema, and the org-code list is restated. Length is partly justified by 16 parameters and a complex domain, but it is not tight.

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 16-parameter, no-output-schema, high-complexity tool, the description covers the gaps an agent needs: what is withheld and why, ingestion floor, filing lag, filter execution model, and default behaviors. Nothing essential to correct invocation 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% (baseline 3), but the description adds meaning beyond the schema: the full purpose-category vocabulary, the server-side vs client-side filter split, and the guidance that candidate_id is sparse so spender_committee_id is preferred for a campaign's full picture. That materially changes how parameters are chosen.

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?

Opens with a specific verb+resource ('Returns FEC Schedule B disbursements') and immediately scopes the content (vendor payments, ad buys, transfers). It explicitly positions itself as 'the OUT-flow counterpart to get_fec_contributions (Schedule A, money IN)', which lets an agent separate the two siblings without reading 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?

Provides four named 'killer query patterns' with concrete parameter combinations for distinct intents (candidate spending, vendor lookup, ad-spend trends, committee transfers), plus a filter-combination note explaining which filters are server-side indexed vs client-side. Also states the one-equality-filter constraint, which is real 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?

Annotations already declare a safe read-only profile, but the description adds rich behavior beyond them: privacy withholding for natural-person filers, memo-row double-counting, F24/F5 filing sources, incomplete cycle filtering, and the split between server-side and client-side filters. This is exactly the context an agent needs to avoid misusing the 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 description is front-loaded with purpose and the critical support_oppose signal, then organized into source, filter behavior, and query patterns. It is dense and long with FEC legal/background detail, but most of it earns its place for a 17-parameter domain tool; some background could be trimmed without losing meaning.

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 17 optional parameters, no output schema, and read-only annotations, the description covers source, key behavioral caveats, filter combinations, and practical query recipes. It does not describe return format or pagination, but with no output schema and safety annotations present, that omission is minor.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining server-side indexing limits for equality filters and that other filters are applied client-side. Many simple parameters (limit, sort_by, sort_order, amount bounds) are left entirely to the schema, keeping this from a 5.

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

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

States a specific verb and resource (returns FEC Schedule E independent expenditures) and precisely defines the domain: money spent by super PACs uncoordinatedly for or against candidates. This distinguishes it from sibling FEC tools like contributions and disbursements without requiring schema inspection.

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 extensive usage context through 'killer query patterns' and filter-combination notes, including when to use support_oppose='O' for attack ads and how to scope cycles by date. However, it does not name alternative sibling tools as explicit substitutes or state clear exclusions, so it stops short of the highest bar.

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 only declare readOnly/openWorld/non-destructive; the description goes far beyond by disclosing that award_amount and total_outlays are nullable (with a ~75% null rate), that nulls are excluded from min_amount and sort last, that total_count is omitted under specific conditions with coverage_warning, and that outages fall back to a cached window where volume must not be inferred. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loads purpose, then usage, then the cross-source recipe, then the caveat block — good ordering and no filler sentences. It is long, and the numbered political-alpha recipe is more verbose than strictly needed, but each section still carries usable 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?

For an 11-parameter tool with no output schema, the description covers return semantics (total_count as the authoritative count, results as just a page, has_more) and the failure modes (coverage_warning, cache fallback). An agent has enough to answer volume questions correctly 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?

Schema coverage is 100% so parameters are already documented, but the description adds real meaning: recipient_name's parent/subsidiary expansion, the recipient_uei-as-parent edge case, and the interaction where null values are dropped from min_amount filtering. It reinforces rather than merely repeats the 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?

States a specific verb+resource ('Returns federal contract awards from USAspending.gov'), defines the record granularity (one prime contract award, modifications as separate records), and implicitly separates itself from siblings like get_federal_grants by naming the source and award types.

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 'Use this when the user asks about' list covering recipient, NAICS/PSC, and cross-reference scenarios, plus a concrete cross-source workflow naming the sibling get_congressional_trades and the 30-day timing heuristic. Nothing about when to reach for it is left to inference.

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

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

Annotations only declare readOnly/openWorld/non-destructive, but the description discloses far more: award_amount and total_outlays are nullable, nulls mean 'source omitted' rather than $0, nulls never satisfy min_amount and sort last, and total_count may be omitted with a coverage_warning under specific filter combinations. It also explains the live-vs-cache passthrough and the fallback posture on outage, none of which is derivable from the annotations.

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

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

Front-loads purpose, then behavior, then query patterns, then coverage semantics, so the agent can stop reading early. It is long, and details like the award-type code enumeration and source posture are helpful but not strictly load-bearing for invocation, which keeps it just short of 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?

With no output schema, the description fully carries return-value semantics: total_count as the authoritative count, results as only the requested page, has_more meaning, and coverage_warning behavior. Combined with the nullable-field guidance, an agent has everything needed to interpret and use the response correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning beyond the schema: null handling relative to min_amount/sort, and that live cfda_number matches the full assistance-listings array while the cached fallback matches only the primary listing. These are real behavioral additions rather than restatements.

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 ('Returns federal GRANTS and cooperative agreements from USAspending') and immediately distinguishes it from its closest sibling by naming get_federal_contracts and contrasting the recipient universe (universities, non-profits, agencies vs. contractors). An agent can route between the two 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 explicit query patterns (cfda_number='93.847' for NIH R01, awarding_agency + min_amount for infrastructure, recipient_uei for precision) and states exactly when to rely on total_count versus the results page. It also names the fallback condition (USAspending outage -> cached window) and warns not to infer volume there, which is genuine when-to-use 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?

Annotations already declare readOnlyHint/openWorldHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context: 'pure-publisher posture' with no risk scoring, comprehensive coverage ('every Federal Register publication appears here'), and stable GPO-assigned document numbers. It stops short of describing return format or pagination.

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

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

Front-loaded with the core definition, then organized into labeled blocks (use cases, source, document types, agency filtering). It is on the long side, but nearly every sentence conveys distinct operational value; only minor tightening is possible.

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 10 params, no required params, full schema coverage, and annotations covering safety, the description is nearly complete. It could say more about result shape/pagination since there is no output schema, but it does characterize the record ('returns the daily publication record as-is').

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the semantics of each document_type value (Rule = in effect, Proposed Rule = open for comment, etc.) and clarifying the exact-match (agency_slug) vs substring (agency_name) distinction for agency filtering.

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 ('Returns Federal Register documents') and immediately defines what that resource is ('daily-published collection of US executive branch regulatory + administrative actions'). It is distinguishable from siblings like get_government_publications and get_lobbying_filings.

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 explicit use cases (regulatory tracking, executive order monitoring, public-comment tracking, compliance forward-look) and cross-references a sibling ('cross-reference with get_lobbying_filings'). However, it never states when NOT to use this tool or how it differs from the nearest sibling get_government_publications.

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 only declare readOnly/openWorld/non-destructive; the description adds genuine behavioral context beyond those — the ~70K record volume, the one-record-per-(declaration, county) fan-out (critical, since a single disaster spans MANY rows), and the 'pure-publisher posture' stating no derived damage estimates or exposure scores. It does not mention pagination behavior or default result ordering beyond sort_order's schema note, so a 4 rather than 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?

Measured in paragraphs: purpose/scale first, then a when-to-use trigger list, then record shape, then filter guidance, then cross-source and posture. It is dense but every section earns its place. Slightly long, keeping it off 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?

For an 11-param, no-output-schema, read-only tool, the description is complete: it defines record granularity, all major filters, the assistance-flag semantics (public_assistance as the infrastructure-rebuild-money flag), and the cross-source workflow. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters thoroughly. The description reinforces the right filter idioms ('filter fema_declaration_string or disaster_number for all areas of one event; filter state + since for a state's recent disasters'), which adds small routing value over the schema, but nothing beyond it. Baseline 3 is correct.

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 (returns) and resource (federal disaster declarations from OpenFEMA), scopes it to every DR/EM/FM declaration since 1953, and states the record granularity. No sibling tool covers this data, so the purpose is unambiguous.

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

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

It gives an explicit trigger list ('hurricanes / floods / wildfires ... when the user asks about ...') and names cross-source follow-ups (get_federal_contracts, get_federal_grants, get_material_events). The agent knows exactly when to reach for it and what to do next.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint=false, yet the description adds substantial non-obvious context: the 'pure-publisher posture' (no predictions or scoring), the ~4-day posting lag, the fact that documents themselves are not in the record, and that the primary file must be fetched via source_url. That is exactly the extra-behavior detail the annotations cannot supply.

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

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

Three dense paragraphs but front-loaded with the return resource and trigger conditions before the docket-format reference material. Nearly every sentence carries operational value, though the record-shape inventory borders on schema duplication and could be tightened.

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 an 11-parameter, no-output-schema tool, the description compensates well: it describes the record shape (accession_number, category, class_types, libraries, authors/recipients), the join key (docket_number), and where the actual documents live. An agent has everything needed to query and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by decoding the docket-number grammar (prefix + year + sequence, with concrete examples per library), explaining that sub-dockets like 'RP26-930-000' resolve to the same proceeding, and clarifying the posted_date vs filed_date lag. The library concatenation quirk ('RulemakingElectric') is also surfaced as both schema and prose.

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 ('Returns FERC eLibrary document records'), enumerates the exact scope (Issuances vs Submittals across six libraries) and quantifies volume (~1,300 docs/week). This clearly separates it from adjacent siblings like get_federal_register_documents or get_enforcement_actions, which cover different sources.

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 explicit triggering conditions: 'Use this when the user asks about: a FERC docket or rate case, pipeline / utility / hydro regulatory activity, FERC orders affecting a company, or energy infrastructure proceedings.' No competing sibling is named for exclusion, but the tool's domain is narrow enough that this is clear context rather than an omission.

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, open-world, and non-destructive behavior, but the description adds substantial context beyond that: record-level granularity, v1A scope, what is included (registrant ↔ principal linkage) versus excluded (per-document filing detail and compensation figures), retention of terminated registrations, and the meaning of has_foreign_principal=false.

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 usage, and most sentences carry useful domain-specific guidance. It is more verbose than necessary for a tool definition, but the structure and density of information justify most of its length.

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

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

Given 11 parameters, no output schema, and annotations that cover only the safety profile, the description is highly complete. It explains scope, key filters, return granularity, exclusions, historical retention, and complementary tools so an agent can invoke it correctly 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?

Schema description coverage is 100%, so the schema already documents all 11 parameters and a baseline of 3 is appropriate. The description adds extra meaning for key filters—especially foreign_principal_country as the highest-signal filter with a concrete example, status behavior, and has_foreign_principal semantics—but does not add much beyond the schema for the remaining parameters.

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

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

The description states a specific verb and resource: returns FARA registrations of US persons/firms registered with DOJ as foreign agents. It clearly distinguishes itself from siblings by naming FARA as foreign-principal representation versus LDA as domestic lobbying, and it explains the record granularity (one registrant ↔ foreign-principal relationship per 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?

It gives explicit use cases (who is a registered foreign agent, which US firms work for a particular foreign government, recently registered agents, adding a foreign-influence flag) and cross-source pairing patterns with get_lobbying_filings, get_fec_contributions, and get_congressional_trades. It also states that default queries return both active and terminated registrations, and that status:'active' should be used for the current roster only.

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/openWorld/non-destructive, and the description layers substantial extra context beyond them: unit multiplicity (USD vs USD/shares), YTD-cumulative vs quarterly observations and the frame marker, deprecated concept-name migration, latest_only collapsing to one row per ticker×concept, and an explicit 'pure-publisher' posture (no derived ratios). This is exactly the behavioral detail an agent needs and could not get from the annotations.

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

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

Front-loaded with the core purpose, then organized into scope, cautions, and posture blocks that each carry distinct information. It is long and the 40-concept watchlist is verbose, but nearly every line earns its place; trimming is possible but not warranted enough to drop below a 4.

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 13 parameters, no output schema, and a specialized financial domain, the description supplies the scope (concept watchlist), the record grain, the data-interpretation hazards, and the deliberate non-computation boundary. An agent has everything required to call and interpret this 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?

Schema description coverage is 100%, so the per-parameter text already carries the basics. The description still adds meaning on top: it explains latest_only's per-ticker×concept collapse, lists the concept categories behind the category enum, and clarifies the frame/period semantics that govern how results should be interpreted.

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: 'Returns XBRL-tagged financial fundamentals from public-company 10-K and 10-Q filings, sourced from SEC EDGAR's company-facts API,' and clarifies the record grain ('one observation of one concept at one period end'). It never names distinguishing siblings such as get_annual_financial_disclosures or get_bank_financials, so an agent must infer the boundary rather than being told it.

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 trigger list ('Use this when the user asks about: revenue, profit, margins, cash position, debt...') that maps user intents to the tool, which is strong positive guidance. There is no 'when-not-to-use' clause and no named alternative for overlapping needs, so routing vs siblings is left implicit.

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

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

Annotations already mark this read-only, non-destructive and open-world, and the description layers substantial extra context on top: the 2024-06-01 coverage start, the ~4% unextracted subset, null-means-not-yet-backfilled semantics, the 'N/A' counterparty preservation quirk, and the min_notional-vs-value_usd ~100x divergence warning. These are exactly the operational caveats an agent cannot get from annotations or 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?

Dense and front-loaded, but the twenty-value asset_cat enumeration is reproduced almost verbatim from the schema, and the coverage/backfill caveats are restated more than once. The filter-combo block is long but largely earns its place; the asset_cat duplication does not.

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 26-parameter, no-required-args search tool with no output schema, the description covers absolutely everything an agent needs: what a row is, how it relates to the parent filing, coverage boundaries, null/empty-result interpretation, and the derivative/debt field families added in the 2026-08-09 extraction.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an extra point by explaining how parameters compose (filer_name matching a family vs filer_cik pinning one trust, min_notional vs min_value_usd for sizing, payoff_profile='Short' for short books) and by disclosing refusal/edge behavior. It stops short of syntax detail on the date-window pairs, which the schema already covers.

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

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

Opens with a specific verb and resource — 'Returns per-security holdings from SEC Form N-PORT primary documents' — and immediately fixes the grain ('one row per investment-or-security line'). It also differentiates from the sibling get_nport_filings by explaining that the parent filing carries fund metadata while the holding carries security-level detail.

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 enumerates the question shapes this tool answers (which funds hold X, portfolio composition, derivative exposure, repo, concentration, shorted-Y queries) and then gives a long list of concrete filter combinations. It also names the alternative route — read the parent filing via filing_id / primary_document_url for metadata — and states when an empty result means 'not extracted' rather than 'no positions'.

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

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

Beyond the readOnly/openWorld/destructive annotations, the description discloses two non-obvious behavioral traits: the GAOREPORTS collection is a stale historical archive (~16.5K reports, no recent updates) and v1A returns metadata only with the full body at package_link. Both would materially change how an agent answers if 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?

Front-loaded purpose sentence followed by clearly headed bullets, collections block, and pairing patterns — every section is scannable. It is however quite long (~350 words) and some collection prose is richer than strictly needed for selection.

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

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

With no output schema, the description carries the return-value burden and does so by stating that only metadata is returned and that content lives at package_link. Combined with full collection coverage, usage triggers, and identifier format, 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% so the baseline is 3, but the description adds genuine meaning: each `collection` enum value is given interpretive significance (CRPT as a real-time floor signal, PLAW as the 'what actually got done' record, CHRG as a precursor to enforcement), and the package_id naming convention is decoded with worked examples. The remaining date/sort/limit params are left to the 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?

States a specific verb+resource (returns recent congressional + oversight publications from GovInfo) and names the exact four collections it spans. An agent can distinguish it from get_bills, get_roll_call_votes, or get_federal_register_documents from the description alone.

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

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

Opens with an explicit 'Use this when the user asks about' block enumerating four triggering scenarios (committee reports, signed public laws, hearing transcripts, GAO oversight). It also routes to alternatives via named cross-source pairing patterns (get_congressional_trades, get_enforcement_actions, get_bills + get_roll_call_votes) with the condition that selects each.

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

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

Annotations cover only the safety profile (readOnly/openWorld/non-destructive), and the description adds substantial behavior beyond that: LCAs are pre-petition and signal intent not approval, Certified far exceeds visas issued, wage_unit varies across five units, case_status enum values, FY2024→present coverage at ~400-550K filings/quarter, and a pure-publisher no-normalization posture. This is exactly the context annotations cannot carry.

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

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

Dense but front-loaded: return fields first, then usage triggers, then interpretation caveats, matching, and coverage. Length is justified by the tool's complexity, though a few clauses (e.g. the two 'e.g.' examples) repeat schema content and could be trimmed.

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, 11 parameters, and a nuanced dataset, the description still supplies return-field inventory, interpretation caveats, coverage window, matching behavior, and wage-normalization warnings. Nothing an agent needs to call and read this 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 description coverage is 100%, so all 11 parameters are already documented; baseline is 3. The description restates matching semantics (employer_name substring over legal+DBA, soc_code precise filter, case_status values) that largely duplicate the schema rather than adding syntax or default details.

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 (returns H-1B Labor Condition Applications from DOL quarterly files) and enumerates the exact record contents (employer, job title, SOC code, offered vs prevailing wage, worksite, risk flags). No sibling covers H-1B/LCA data, so the agent can place it immediately 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?

Gives explicit when-to-use triggers: company hiring activity, wage levels for roles, tech-hiring trends by state/occupation, offered-vs-prevailing gaps, outsourcing-firm patterns. Strong context, but it names no alternative tool or when-not-to-use boundary (e.g. vs unified_search).

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

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

Annotations cover only the safety profile (readOnly/destructive/openWorld), but the description goes far beyond: ticker search surfaces retired-symbol rows, rows gain current_ticker, share classes are not merged, retired symbols return only their own rows, plus source (SEC bulk dataset insider_filings_v2), coverage (2006→present), and refresh cadence (quarterly). This is rich behavioral disclosure the annotations cannot supply.

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?

Information-dense with almost no filler, but it front-loads ticker/retired-symbol edge cases before stating the core purpose, which is buried mid-paragraph. A reader has to get past the caveats to learn what the tool returns; a short purpose lead would improve ordering.

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 and 12 optional parameters, the description compensates by enumerating the returned row fields (company_cik, company_name, ticker, document_type, filing_date, period_of_report, is_amendment, reporting_owners[], signature rows, per-table counts), the data provenance, and the join keys to siblings. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the per-parameter docs already carry the baseline. The description still adds value with concrete filter-combo recipes (ticker+document_type, company_cik+is_amendment, accession_number alone, ticker+reporting_owner_name) and clarifies that document_type uses raw SEC form codes including /A amendments. It stops short of full combinatorial guidance, but exceeds the 100%-coverage baseline.

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

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

States a specific verb+resource: 'Returns FILING-LEVEL records from SEC Form 3/4/5 filings — one row per filing (accession).' It explicitly positions itself as the filing INDEX and names the two siblings it is not (get_insider_transactions for trades, get_insider_holdings for positions). An agent can distinguish it from every neighbor without opening a 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?

Provides an explicit when-to-use list ('list an issuer's insider filings, find a specific accession, filter by form type... count filings over a period, or size a filing') and names the alternatives with the join key ('They join on accession_number'). This is textbook when/when-not/alternatives 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?

Annotations already declare readOnly/openWorld/non-destructive, but the description goes well beyond: it discloses that ticker search returns rows filed under retired symbols, that `current_ticker` is added for renamed issuers, that share classes are NOT merged, that retired symbols get reissued, that merge_co_reports defaults to true and merges co-reported positions, and that shares/value are 'following the reported transaction' rather than live. This is exactly the kind of non-obvious behavior 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?

Front-loaded with the most important disambiguation (the retired-symbol and companion-tool notes), and the filter-combo block is scannable. It is dense and somewhat long, with a mild redundancy in naming get_insider_transactions twice, but nearly every sentence carries 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?

For an 18-parameter, no-output-schema tool, the description is thorough: it describes the source dataset and cadence, the full row structure (filing envelope, position fields, derivative fields), merge behavior, and the position-vs-transaction caveat. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: concrete filter-combo examples with literal values, the note that shares/value reflect the position as of the filing (not real-time), and the ticker-vs-current_ticker distinction. It stops short of full coverage but meaningfully enriches the parameter semantics.

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 ('Returns per-security INSIDER POSITIONS from SEC Form 3/4/5 filings — one row per holding line reported by a corporate insider') and explicitly distinguishes itself from get_insider_transactions as the 'position (stock) companion' versus the buys/sells flow. An agent can route between the two siblings 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?

Explicitly enumerates when to use it: 'what a specific insider currently HOLDS, who the largest insider holders of a stock are, an insider's position across companies, or direct-vs-indirect ownership structure.' Names the alternative (get_insider_transactions) for the trade-flow case and supplies concrete filter combos for common queries.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description goes well beyond that, disclosing coverage boundaries, license-withheld fields, nullable-value traps, and recency auto-merge behaviour — but much of this is framed as historical corrections ('this text used to say... which was false'), which reads as an audit changelog rather than invocation-relevant behaviour. Substantive transparency is high, but the signal-to-noise is diluted.

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?

Purpose is front-loaded, but the body runs to many screen-lengths and is heavily padded with version-dated changelog entries, audit measurements and self-corrections ('measured 2026-09-04 by the KeyVex auditor...', 'this text used to say...'). For an agent selecting and calling a tool, the vast majority of this text does not change behaviour and crowds out the operative guidance.

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

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

For a 24-parameter, zero-required, no-output-schema tool spanning two backing datasets, the definition covers selection, filtering, null semantics, pagination and source-of-truth caveats. Nothing an agent needs in order to call it correctly is missing, even if it is delivered verbosely.

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

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

Schema description coverage is 100%, so the baseline is 3, and the schema already documents every filter thoroughly. The description earns above baseline by adding meaning the schema cannot: the P-is-not-open-market trap with named counterexamples, the interaction between transaction_type and include_non_open_market, and the min_value/include_unpriced coupling.

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 ('Returns executive insider transactions filed on SEC Form 4') and immediately narrows scope to open-market purchases and sales by officers, directors and 10%-owners. It further distinguishes itself from sibling insider tools by naming the row granularity ('one transaction line item from one filing') and the derivative/non-derivative split.

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 'Use this when the user asks about' enumeration covers the main intents, and the 'Useful filter combos' block names the exact parameter sets to run per intent. The data_source section states when to prefer 'legacy' versus the default 'bulk_v2', including the exclusion condition ('only when you specifically need the legacy doc shape').

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 only cover safety (readOnly, non-destructive, openWorld), so the description adds the operationally decisive facts: a reporting lag of up to 45 days, the fact that the latest visible quarter always trails real time, and that the data is a long-equity snapshot with no shorts/cash/options. It also explains position_change is computed against the same fund's prior quarter, which prevents misreading a field.

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

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

Front-loads the definition, then usage triggers, then caveats, then field semantics — a sensible order with no wasted preamble. Slightly long, and enumerating the position_change values duplicates the enum in the schema, which is the only real redundancy.

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

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

For an 11-parameter tool with no output schema and no required parameters, the description covers the domain, the temporal caveat, and the grain of each record well. Field-level return detail is thin — only position_change is characterized — so an agent still lacks a full picture of what columns come back, but nothing needed to invoke 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 description coverage is 100%, so the baseline is 3 and the schema already carries format details for cusip, quarter, cursor, and the enums. The description still adds real meaning beyond the schema by explaining what position_change values signify ('relative to the same fund's prior quarter') and why quarter choice is constrained by filing lag.

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 ('Returns 13F holdings — quarterly snapshots of equity positions held by institutional investment managers with $100M+ AUM') and defines the record grain as a (fund, security, quarter) tuple. The AUM threshold and 13F framing implicitly separate it from sibling datasets like get_fund_holdings (N-PORT mutual funds) and get_activist_stakes (13D/13G), so an agent can route without opening a 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 trigger list: 'which institutions hold a stock, a fund's portfolio, position changes quarter-over-quarter, or whale activity in a specific name.' It also bounds the domain by listing what 13F excludes (shorts, cash, options, non-US equities), which steers the agent away from wrong questions. No sibling tool is named as an alternative for overlapping cases, so it stops short of full when-not 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?

Annotations only cover the read-only safety profile; the description adds far more: IEX-only venue coverage with a thin-name staleness caveat and a concrete example, the fact that out-of-hours quotes are the prior session's final print, delisting row synthesis upstream, and the semantics of null (flat_session null = 'could not test', not false). This is exactly the behavioral context annotations cannot carry.

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

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

Purpose, paid-plan constraint and the sibling alternative are front-loaded in the first three sentences, which is the right ordering. It is long, but the length is largely earned by genuinely non-obvious caveats (stale as_of, flat_session null semantics, IEX-only volume); a few passages restate the same point in different words.

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

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

With no output schema, the description carries the full return-value burden and does so thoroughly: price, as_of, price_field, iex_session_volume, prev_close, flat_session, and the two not_found_reason values with their meaning. Nothing an agent needs to interpret the response 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% for the single ticker param, so the baseline is 3. The description adds value beyond the schema by stating there is no multi-ticker parameter by licence, which prevents an agent from attempting batching.

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 ('Returns the latest intraday price for ONE US-listed ticker') and pins the scope with 'a live passthrough to Tiingo's IEX feed, nothing cached.' It explicitly contrasts itself with the sibling get_daily_prices for historical data, so an agent can route correctly without opening either schema.

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

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

Names the exact question this answers ('what is X trading at now') and routes the alternative case ('For price HISTORY ... use get_daily_prices'). It also states a hard eligibility constraint (PAID PLANS ONLY) and the licence constraint of one ticker per call.

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

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

Annotations cover safety (readOnly, non-destructive, openWorld), and the description adds substantial context beyond them: it is a CURRENT-ROSTER monthly snapshot not an event history, a stale snapshot_month means deregistration, ERA AUM is null by construction, and a disciplinary FLAG is a disclosure not a verdict. This is exactly the kind of behavioral disclosure the structured fields cannot carry.

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

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

Long but front-loaded and information-dense, with the core purpose in the first sentence and caveats after. Some redundancy exists (firm_type registered/ERA AUM semantics are stated in both the schema description and the prose), which slightly dilutes conciseness.

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 an 11-param dataset tool with no output schema, the description is complete: it enumerates returned fields (AUM, employees, client counts, custody flags, Item 11 codes), explains the v1A subset and adviserinfo_url, and clarifies roster/publisher posture. An agent has everything needed to call and interpret results.

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

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

Schema coverage is 100% so baseline is 3, but the description adds real meaning: min_aum 'requires the default aum_total sort', firm_type drives whether Item 5F AUM is populated, and CIK is the join key to 13F/enforcement. It goes beyond the schema on the keys an agent must reason about jointly.

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: 'Returns SEC Form ADV registry records' and quantifies scope (~17K RIAs, ~6.5K ERAs). It distinguishes the two firm types and names the record granularity (one per CRD), so an agent can tell it apart from siblings like get_enforcement_actions.

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

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

Explicit when-to-use: 'Use this when the user asks: who advises/manages money, how big is an adviser, largest RIAs by state, advisers with disciplinary history, or to vet a firm before pairing with enforcement / holdings data.' It names the alternative sibling datasets (enforcement, holdings) and the conjunction condition.

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 annotations covering readOnly, openWorld, and destructive=false, the description adds substantial behavioral context: the income vs expenses split, the ~30%/70% population skew, client_is_government semantics, and the 5000-character truncation with filing_document_url for full prose. It also notes a future derived field, giving agents a clear picture of current limitations and expected data shape.

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 purpose and record structure, then moves to use cases and caveats in a logical order. It is long but mostly earns its length given the complex 12-parameter tool with no output schema, though the v1.1 roadmap note and some repetition could be trimmed.

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 carries the burden of explaining return values, which it does thoroughly: it describes the lobbying_activities array, three flattened summary arrays, income vs expenses fields, truncation, and the full-document fallback. Combined with the schema and annotations, an agent has enough information to invoke 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?

Schema description coverage is 100%, so the baseline is 3. The description adds some meaning for general_issue_codes OR semantics and sort_by=income, but those details are largely already present in the schema, and most other parameters are documented only in the 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 description states a specific verb and resource — returns Lobbying Disclosure Act (LDA) filings — and defines the record grain as one (registrant, client, quarter) tuple with income, issues, and entities. It clearly differentiates from related sibling tools like get_lobbyist_contributions by focusing on quarterly LD-2 filings rather than campaign contributions.

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 usage scenarios: who's paying lobbyists, issues a company is lobbying on, senators/agencies contacted, lobbying spend by industry, and cross-referencing against congressional trades or federal contracts. It does not name alternative tools or state when not to use this tool, so it falls short of the top score.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial extra context beyond annotations — coverage window (2008→present), volume (~40K filings/year), the fact that ~half are 'no contributions' certifications excluded by default, the record shape, and a 'pure-publisher posture' caveat that contributions_total_usd is arithmetic not a score. That is meaningful added behavior, but much of it duplicates schema-level filter semantics rather than revealing operational traits like rate limits or auth, so it lands above baseline without being exceptional.

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

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

Front-loaded with the core definition and the reverse-angle framing before dense detail. It is long and repeats some schema content (contribution_type values, the honoree example appears twice), but nearly every clause carries distinct information. Efficient enough given a 13-parameter tool with no output schema, with minor redundancy.

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

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

No output schema exists, so the description must carry return semantics — and it does: one record per filing, filer fields, filing_year/period, nested contribution_items[], flattened arrays, and contributions_total_usd. Combined with coverage window and the empty-certification caveat, an agent has everything needed to call and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds genuine conceptual meaning beyond the schema: honoree_name is framed as 'the political join' with an example, contribution_type values are glossed with semantic intent ('feca' = campaign money), and include_empty is explained in terms of the ~half of filings that are certifications. This lifts it above baseline, though the contribution_type enum list is largely a restatement of the 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?

States a specific verb+resource (LD-203 semiannual contribution reports) and immediately scopes what it contains: contributions by lobbyists/firms themselves, with the honoree concept called out. It explicitly distinguishes itself from the closest sibling ('the reverse angle of get_lobbying_filings: filings show who pays lobbyists; LD-203 shows where the lobbyists' own money goes').

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 routing: use get_lobbying_filings for client work, get_fec_contributions for the FEC view of the same FECA money, get_member_profile to resolve the honoree. It also states a default behavior (empty certifications excluded) and how to override it, which is directly actionable usage guidance.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), and the description layers on non-obvious behavior: OR-semantics and the 30-code Firestore cap, how 8-K/A amendments are stored as separate rows with is_amendment, that v1 leaves original_accession_number unpopulated, and that v1 does not extract the prose body so primary_document_url must be fetched. This is rich context beyond the structured fields.

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

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

Front-loaded with the definition before the usage triggers, and every block (item codes, amendment handling, v1 limitations) carries information. The item-code glossary is long but justified; there is minor redundancy with the schema's item_codes example text.

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 describing the record shape, the item_codes field, the amendment row model, and the primary_document_url escape hatch for prose. An agent has everything needed to query and to explain results to a user.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: a glossary mapping item codes to event meanings that is absent from the schema, plus the explicit 30-code cap and OR semantics that shape how item_codes should be constructed. It stops short of full syntax depth for the date/sort parameters, which the schema already handles.

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

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

States a specific resource (SEC Form 8-K current reports), defines it inline ('filed within 4 business days of any material event'), and explains the record granularity ('Each record is one filing, with item_codes declaring WHAT kind of event(s)'). An agent can distinguish this from sibling filing tools like get_insider_filings or get_proxy_filings purely from the text.

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 enumerates the trigger questions ('recent CEO/CFO departures or appointments, M&A announcements, earnings releases...') and gives concrete item_code recipes for each use case (['5.02'], ['1.01','2.01'], ['2.02']). It also warns against a specific misuse — searching only 9.01 returns the firehose.

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?