HillSignal

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

With readOnlyHint already declaring the safety profile, the description goes well beyond annotations by disclosing the degraded-result path: when verified figures are unavailable it says so, returns no total, and instead lists the largest matching awards with lifetime values explicitly labelled. That is exactly the non-obvious behavior an agent needs to avoid fabricating a total. It does not describe the fields returned for the successful path, which limits it from 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?

Three tight sentences with no filler, and the core scope ('verified totals ... in the dates asked') is front-loaded. The closing imperative is unusual for a description but earns its place as a guardrail against a common LLM misreport.

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 9-parameter aggregation tool with no output schema, the description covers the critical trust/fallback semantics but omits the shape of a successful response (what a 'total' row contains beyond the amount) and the default behavior when no date bounds are supplied. Enough to call it correctly, not enough to fully anticipate its output.

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 nine parameters, including group_by's allowed values and date formats, are already documented. The description reinforces that grouping is by recipient or agency but adds no syntax, default, or interaction detail (e.g. what happens when since/until are omitted) beyond the schema. Baseline 3 applies.

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

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

The description states a specific operation on a specific resource: verified aggregate totals of obligated money within a date range, grouped per recipient or agency. The grouping dimensions are echoed by the title. It stops short of naming the sibling it is not (search_awards), so an agent must infer that distinction rather than being told.

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?

Usage context is implied ('in the dates asked', period-scoped totals) and there is a strong negative instruction about never presenting lifetime values as period totals. However, there is no explicit routing guidance such as 'use search_awards for individual awards' or 'use money_trail for indirect spending', leaving the agent to infer its place among 28 siblings.

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

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

Annotations only declare readOnlyHint, so the description carries the real behavioral load and does so well: it discloses that limit caps the FILINGS read rather than the trades returned, exposes filings_matching and the truncated flag, and warns that returned_trades must never be quoted as a total. This is exactly the non-obvious context annotations cannot provide.

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

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

Two front-loaded sentences with no filler; the resource and filtering come first, then the truncation caveat, and every clause carries information an agent needs.

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 supplies the return shape (one row per transaction with amount range and filing PDF) plus the truncation semantics, which is everything needed to call and interpret the tool correctly.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds genuine meaning beyond the schema: it redefines limit as a cap on filings read rather than rows returned, which directly corrects the schema's 'Max rows, 1-25' wording.

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?

Names a concrete resource (stock trades disclosed by members of Congress via House/Senate Periodic Transaction Reports) and the dimensions it can be sliced by. An agent can tell it apart from insider_trades conceptually, though the sibling is never named explicitly.

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

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

Listing the filter dimensions (member, ticker, transaction type, date) implies the use cases, but there is no explicit 'use this instead of X' routing and no exclusions, even though insider_trades and get_politician sit in the sibling set.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true; the description is consistent with them and adds a meaningful behavioral guarantee: the tool reports row counts and latest row dates, so it gives freshness and coverage signals in one call. No contradiction.

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

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

Two sentences, front-loaded with the concrete substance (row counts, latest dated row, coverage) and then a crisp call-condition sentence. No filler; every clause 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?

With zero parameters and no output schema, the description supplies exactly what an agent needs to decide whether this tool answers a completeness question: what it returns, for which datasets, and when to call it. It does not need to restate annotations.

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?

Zero parameters, so there is nothing to disambiguate and no way to mis-invoke. The description clarifies what the output will cover (every dataset, entity-resolution coverage), which matters more than parameter docs here.

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 title 'What HillSignal has' and description 'Row counts and the latest dated row for every dataset behind these tools, plus entity-resolution coverage' make the purpose concrete: this is an introspective coverage-reporting tool. It distinguishes itself from siblings that answer domain questions because it reports on dataset completeness rather than the underlying data itself.

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

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

The description explicitly gives call conditions: 'Call it when an answer depends on how complete the data is, or before saying something does not exist.' This is exactly the kind of when-to-use guidance that beats the baseline; it also implicitly marks when not to call it (when you need the underlying content itself).

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?

readOnlyHint=true already covers the safety profile, so the bar is lower, yet the description adds real context beyond the annotations: results carry an unverified AI ticker field that agents must not treat as evidence. That is exactly the kind of caveat annotations cannot express, though nothing is said about result size, ordering, or recency defaults.

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?

Two tight sentences: the resource scope first, the critical data caveat second, with zero filler. Every clause carries information an agent would otherwise have to guess.

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

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

With no output schema, the description carries the burden of describing returns, and it does name the key fields (sectors, tickers) and warns about ticker reliability. It still leaves the record shape and what a single row contains largely implicit.

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 four parameters (limit, query, since, sector) are already documented with formats and defaults. The description only indirectly echoes the sector filter via 'affected sectors' and adds no syntax or semantics beyond the schema, so baseline 3 applies.

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

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

The description names a specific resource set (executive orders, proclamations, memoranda) plus the attached metadata (affected sectors), which is far more precise than the bare name. It does not, however, distinguish itself from the overlapping siblings federal_register and federal_register_document, so an agent must infer where the boundary lies.

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 second sentence gives strong guidance on how to interpret results (tickers are ai_suggested_tickers_unverified, never proof of company exposure), which is effectively a usage rule for the output. There is no guidance on when to pick this over federal_register or federal_register_document, and no stated exclusions.

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 readOnlyHint=true, and the description adds real context beyond that: returned passages carry citation coordinates (FR page, CFR section/paragraph) and a text-class label, documents carry status and legal effect derived from their own dates, and a coverage signal indicates what has full text. It does not describe ordering or how results are ranked, but the safety profile is already covered by 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?

Four sentences, front-loaded with what is searched and immediately followed by what comes back. Each sentence carries distinct information (scope, citation payload, status/coverage, grounding rule), with only mild density in the citation sentence.

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 8 optional parameters, no output schema, and only a readOnly annotation, the description does the heavy lifting well by describing the shape of returned passages and document metadata. It stops short of explaining result ordering, pagination beyond the 'limit' parameter, or what the coverage signal contains.

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 genuinely enriches two parameters: it explains the meaning of 'parts' by naming the text classes (rule text, proposed text, presidential text, agency explanation) and explains that 'status' reflects legal effect computed from document dates. It adds nothing about date or agency filter behavior, 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?

States a specific verb (search) over a specific resource (Federal Register documents and the passages of their full text), and enumerates the document classes covered. This clearly separates it from the sibling federal_register_document, which by name retrieves a single document rather than searching across documents and passages.

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

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

The description gives clear context for when to reach for this tool: keyword search across documents and their text, with the 'parts' dimension for narrowing to operative vs. explanatory text. It adds a strong usage constraint ('Say what a document requires, authorizes or prohibits only from the passages returned'), but never names an alternative sibling or an explicit when-not 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?

readOnlyHint already covers the safety profile, and the description adds real behavioral context beyond it: the four passage-selection modes, that citations are resolved from exact title/FR citation/document number found in the text, and that RIN matching is exact. It does not discuss truncation or default result sizing, which the schema only gestures at via the offset parameter.

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?

A single front-loaded sentence that packs in scope, payload, and matching semantics with no filler. It is somewhat run-on with the nested parentheticals, but every clause carries information an agent needs.

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 six-parameter tool with no output schema, the description covers what comes back (status, passages, inbound/outbound citations, same-RIN documents) thoroughly enough to plan a call. The remaining gap is pagination behavior, which is only hinted at through the offset parameter's description.

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 does add some meaning by tying 'all, one part, one section, or those matching a query' to the parts/section/query trio and explaining that citation matching is exact, but it adds no syntax or format detail beyond the schema's own field descriptions.

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

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

The description names a specific resource and access mode ('One Federal Register document by number') and enumerates the payload: status and legal effect, full-text passages, citation graph, and same-RIN documents. It implicitly contrasts with the list/search sibling federal_register by emphasizing 'one ... by number', but never names that sibling, so sibling differentiation is left to inference.

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?

Usage is only implied: an agent can infer this is the tool for a known document number, and the alternative (searching the Federal Register) is suggested by the sibling name rather than the text. There is no explicit when-to-use/when-not statement or prerequisite 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=true, so the safety profile is covered; the description adds genuinely non-obvious behavior: newest-first ordering, an ambiguity fallback that returns a list to choose from, and the guarantee that registrations are never merged. It does not say what happens when neither selector is supplied.

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 tight sentences: return shape first, then how to query, then the ambiguity edge case. No filler and the most decision-relevant information is front-loaded.

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 correctly enumerates the returned fields (date, type, foreign principal, document link) and the ordering. The gap is that all three parameters are optional, yet the description never says what happens if neither registration nor firm is passed.

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: registration is 'the registration number other tools return' (chaining guidance) and firm is 'matched exactly', a matching-semantics detail the schema only hints at with an example. limit is left entirely 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?

Specific verb+resource+scope: 'every document a FARA registrant has filed with the Justice Department, newest first', plus the exact fields returned. It also implicitly separates itself from the sibling foreign_agents by operating on one registrant's filing history rather than on agents themselves.

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

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

Explicitly states the two invocation modes ('pass registration ... or firm') and the disambiguation behavior when a firm name maps to several registrations. It lacks an explicit 'use this instead of foreign_agents when...' routing sentence, which keeps it 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?

The description goes well beyond the readOnlyHint annotation, disclosing nuanced behaviors: 'Rates are never mixed or converted', reported_receipts is 'a floor rather than earnings', values are 'null where no figure could be proved', and the lobbying subset is 'context, never a claim about those clients'. These are exactly the kind of non-obvious behavioral traits an agent needs.

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

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

The description is information-dense but delivered as one long, unbroken paragraph. It is front-loaded with purpose, and every sentence contributes, but readability suffers from a lack of structure (bullets or separation of query modes vs. response semantics) and a high word count.

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 explaining response shapes. It thoroughly documents the country roster fields (registered_agents, former_agents, money, foreign_principal_owned_by), the lobbying subset split (DIRECT vs SHARED_FIRM), and the top= contracts mode. Nothing needed to invoke the 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 real meaning for several parameters: top= selects the biggest contracts, country= returns roster structure, bill= maps to lobbying foreign principals, and rate= clarifies that rates are never mixed or converted. This adds value beyond the schema's property descriptions.

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

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

The description opens with a specific, concrete purpose: identifying who is paid to represent foreign governments and how much, from the FARA register. It clearly differentiates the tool from siblings like lobbying by grounding it in FARA contracts, and its multiple named modes (top=, country=, bill=) make its scope unmistakable.

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

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

The description provides explicit parameter-driven usage guidance: 'Pass top="contracts"', 'Pass country= to LIST THAT COUNTRY'S AGENTS BY NAME', 'Pass bill= for the foreign interests that lobbied a bill, or nothing for the country leaderboard'. It does not compare with sibling tools, but the tool's unique domain and clear conditional instructions give sufficient usage direction.

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

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

Annotations only declare readOnlyHint=true, so the description must carry the rest — and it does add real substance: the no-default-minimum behavior and the meaning of a null offering_amount. These are non-obvious data traits an agent would otherwise misread as a zero-value raise. It stops short of describing return shape or ordering, but the safety profile is already covered.

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 sentences, each load-bearing: the first establishes scope, the second the default/threshold behavior, the third the null-amount gotcha. The most decision-relevant constraint (no minimum applied) is front-loaded after the scope line.

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 no required parameters, the description does the necessary work of flagging the null offering_amount semantic — the main trap for a consumer. It leaves minor gaps (result ordering, whether limit caps silently) but nothing that would cause a mis-call.

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 meaning the schema lacks: min_amount defaults to no filter rather than some implicit threshold, and it explains the offering_amount null convention. This goes beyond restating schema text, though it doesn't quantify units or tie the null note directly to a named 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 D private placements) and the filterable dimensions (issuer name, resolved ticker, date, minimum amount), which is enough to distinguish it from every sibling, none of which cover Form D raises. The retrieval verb is implied rather than stated, keeping it just below a 5.

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

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

The description clarifies the default filter posture ('No minimum size is applied: pass min_amount to impose one'), which is genuine usage guidance for this parameter. It does not, however, state when to reach for this tool versus adjacent datasets (e.g. insider_trades, institutional_holders), so the guidance is implied rather than explicit.

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

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

The annotations already declare readOnlyHint=true, so safety is covered. The description adds useful behavioral details: the lookup is for a single company in the federal record and name resolution is exact. It does not mention not-found behavior, rate limits, or auth, but with read-only coverage this is acceptable.

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

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

The description is two sentences with no filler. The data categories are front-loaded, and the lookup methods follow immediately. Every clause adds information that helps an agent select and 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 read-only company profile lookup, the description covers the essential context: scope (one company in the federal record), return contents, and available identifiers. It doesn't specify an output schema or edge cases like missing parameters, but the enumerated data categories and exact-match note are sufficient for initial tool selection.

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 lists the same three parameters (ticker, entity_id, name) and adds no semantics beyond the schema, except reinforcing the exact-match behavior for name, which is already in the schema description.

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

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

The description clearly identifies a single-company lookup tool: 'One company in the federal record' and enumerates the data categories returned (contracts, PACs, patents, private raises, board seats, insider trades, connections graph). It also states the lookup keys (ticker, entity_id, name), making the tool's purpose unambiguous.

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

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

The description gives clear invocation guidance: 'Look up by ticker, entity_id, or a name (resolved exactly).' It implies this tool is for retrieving one company's full profile and does not need exclusions or alternatives because no sibling tools are in context. It lacks an explicit when-not-to-use statement, but the context is clear.

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

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

With only readOnlyHint provided, the description carries the burden and does so by enumerating the returned analysis categories and adding genuine caveats: matched_by explains the matching strength, lobbying dollar totals are filing totals across every issue, and 10b5-1 sales are called out. It omits auth, rate limits, and failure behavior, so it is strong but not exhaustive.

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

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

The core identity is front-loaded, but the body is one sprawling sentence that strings together a dozen return categories, making it dense to parse. Most of that enumeration is defensible given there is no output schema, yet the run-on structure hurts readability and could be broken into grouped clauses.

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 sensibly shoulders the burden of describing what comes back, and it covers the major data families plus interpretation notes (matched_by, filing-total caveat, the summarisation instruction). Only edge behavior (missing/invalid id, error cases) is left unaddressed.

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 id param, so the baseline is 3; the description goes slightly further by stating the accepted id forms (HillSignal url/id or SAM.gov notice id) and the upstream tool that produces them, which reduces ambiguity about what to pass.

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 ('One SAM.gov notice as HillSignal analyses it') and makes the single-notice scope explicit, which cleanly separates it from the list-oriented sibling search_opportunities. An agent can tell what it fetches and how it differs from the search 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?

Tells the agent exactly where the required id comes from ('Pass id from search_opportunities (hillsignal_url or its id) or a SAM.gov notice id'), which encodes the intended workflow. It stops short of explicit when-not-to-use guidance or stating when a search-then-get sequence is preferred over alternatives, so it is clear context rather than full routing rules.

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

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

The readOnlyHint annotation already signals a safe read operation, so the bar for additional behavioral disclosure is lower. The description adds useful behavior details: it resolves tickers in financial disclosures, includes recent stock trades, and returns candidate options for ambiguous names. However, it doesn't mention what happens if no match is found, rate limits, or whether the returned profile includes all listed sections at once.

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

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

The description is two sentences, front-loaded with the primary purpose and key data categories, then the lookup mechanics and ambiguity behavior. Every clause earns its place, and there is no fluff or repetition of the schema or title.

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

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

Given the tool has no output schema and only two parameters, the description covers the main data contents and lookup behavior well. It could mention what happens on no match or how to disambiguate (e.g., additional fields returned), but for a read-only profile lookup with a simple interface, the description is reasonably complete.

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

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

Schema description coverage is 100% — both 'name' and 'bioguide_id' are described in the schema. The description adds the relationship between the two parameters: they are alternative lookup keys, and ambiguous names yield candidates. But the schema already covers the syntax and examples, so the description only adds marginal semantic value beyond the structured data.

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 purpose: retrieving a member of Congress profile with committees, board seats, stock trades, and PAC contributors. It clearly distinguishes the lookup methods (name or bioguide_id) and mentions that ambiguous names return candidates, which sets expectations beyond a simple profile fetch.

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

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

The description implies when to use this tool: when you need a member's committees, financial disclosures, recent trades, or top PAC contributors. It doesn't explicitly name alternatives or state when not to use it, but the specificity of the data fields and the sibling tool context (award_totals, search_calls, etc.) make the use case fairly clear.

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

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

Annotations already provide readOnlyHint=true, covering the safety profile. The description adds useful behavioral context about what the tool returns, especially valuable because there is no output schema: a dated chronology with beats linked to source records, significance, watch-outs, and evidence. It does not discuss auth or rate limits, but those are less critical for a simple read-only lookup.

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?

A single front-loaded sentence uses a colon to organize five distinct output components with no filler or repetition. Every phrase carries informational weight, making it easy for an agent to quickly understand what the tool provides.

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-only tool with one parameter and no output schema, the description adequately communicates the main return components and single-theme scope. It could have explicitly referenced list_themes as the source of theme_id, but that relationship is already documented in the input schema, so the overall definition is sufficiently complete.

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

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

The input schema covers theme_id fully, including the note that it comes from list_themes and may optionally include the hs:theme: prefix. The description itself adds no parameter-level meaning, so it does not exceed the baseline set by the schema's 100% parameter coverage.

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

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

The description names the resource ('one theme'), implies the retrieval operation through 'in full', and specifies the returned contents: setup, dated chronology with source-record links, importance, watch-items, and evidence. It clearly suggests the distinction from list_themes by emphasizing a single theme, though it does not name a sibling or use an explicit verb.

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

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

The description implies use when needing a complete chronology for one theme rather than a list of themes or other entity-specific details. However, it never explicitly states when to choose this tool over list_themes or other siblings, nor does it give any 'not for' guidance.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds modest context by naming SEC Form 4 as the data source and listing filter dimensions, but it does not disclose defaults, pagination, or what the returned rows contain.

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 a single compact sentence that front-loads the core resource and then lists the relevant filters. There is no filler or redundant wording.

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 simple read-only lookup with no required parameters and full schema coverage, the description covers the main query keys and filter options. It does not state what happens when no ticker or insider is provided or describe the return schema, but the missing details are not critical for invoking 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 all six parameters are already documented. The description roughly restates ticker, insider, type, min_value, and since but adds no deeper semantics beyond the schema; limit is not mentioned.

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

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

The description clearly identifies SEC Form 4 insider transactions as the resource and specifies lookup keys (ticker, insider name) and filters. It differentiates from siblings only implicitly through 'Form 4' and 'insider,' rather than explicitly naming alternatives.

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

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

The description implies a direct query/filter use case, which is helpful, but it does not explain when to prefer this tool over related siblings like congressional_trades, form_d_raises, or institutional_holders. No exclusions or alternative routing are provided.

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

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

Beyond the readOnlyHint annotation, the description discloses that only filings ingested by HillSignal are included, that results are the largest holders sorted by position, and that each institution is represented by its latest position. This adds meaningful behavioral context about data scope and deduplication.

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?

Single sentence with no filler, front-loaded with the core resource, and every phrase adds scope or behavior.

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

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

For a simple read-only list tool with two well-documented parameters, the description states the source, ordering principle, and deduplication behavior. No critical invocation information appears 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?

Input schema already documents both parameters at 100% coverage, so baseline is 3. The description adds context about 'largest' and 'latest position' but does not add parameter-level detail 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?

The description identifies the resource ('largest institutional holders of a ticker') and the filing source (13F-HR), making the tool's purpose recognizable. It lacks an explicit action verb such as 'list' or 'get,' and it does not explicitly contrast with sibling tools, but the noun phrase is specific enough.

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

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

The description implies when to use the tool — when a user wants institutional ownership from 13F filings — but it does not provide explicit guidance or alternatives. It does not say when to prefer insider_trades, congressional_trades, or other sibling tools.

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

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

The readOnlyHint annotation already covers safety, and the description adds useful context about cross-source scope and provenance. It does not describe pagination, sorting details, or response shape, but for a read-only feed the added context is adequate.

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?

Two concise, front-loaded sentences cover the tool's scope, provenance, and optional filters with no filler. Every sentence contributes useful 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 read-only tool with four optional, fully documented parameters and no required inputs, the description plus schema is mostly complete. It could be stronger with explicit return-format context, but the absence of an output schema makes this a minor gap.

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 four parameters. The description only restates the filter options at a high level without adding meaning beyond the schema property names.

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

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

The description clearly identifies the tool as returning the newest events across all sources, listing example categories and mentioning optional filters. It is distinguishable from source-specific siblings like congressional_trades or executive_orders, though it does not explicitly name an alternative.

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?

Usage is implied: the phrase 'newest events across every source' suggests this is the broad firehose tool, and the optional filters hint at narrowing results. However, there is no explicit guidance about when to prefer a specialized sibling tool or when not to use this one.

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

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

The readOnlyHint annotation already declares the operation safe, and the description adds useful behavioral context: the themes are currently funded, come from multiple source types, and each result includes a permanent page and verdict. However, it does not disclose whether the list is paginated, ordered, or limited in any way, which is relevant for a list operation.

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 a single dense sentence with no filler; every clause contributes meaning about scope, source types, or result attributes. It loses one point because it is phrased as a noun phrase rather than a clear action statement, which slightly reduces immediate readability.

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

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

For a zero-parameter tool with no output schema, this description provides the core semantics an agent needs: the domain (government themes), currency ('currently funding'), sources, and what each result contains (permanent page and verdict). It would be more complete if it mentioned whether all themes are returned at once or if pagination/limits apply, but the current level is adequate for 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?

The tool has zero parameters, so schema coverage is trivially 100%. The description's scope statement ('currently funding') reinforces that this is an unfiltered, global list. No parameter-level documentation is needed, so a baseline of 4 is appropriate.

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

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

The description clearly identifies the resource: government themes currently being funded, across bills, contracts, solicitations, and filings, and notes each theme has a permanent page and a verdict. It lacks an explicit imperative like 'Lists', but the tool name plus description makes the operation unambiguous. It does not explicitly contrast with get_theme, though the plural framing implies a list operation.

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?

No guidance is given on when to use this tool versus siblings such as get_theme, search_bills, or search_opportunities. An agent must infer that list_themes is the broad overview tool and that get_theme is for a specific theme. The absence of any when-to-use or when-not-to-use guidance leaves a clear gap.

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, so the tool's read-only nature is covered. The description adds the 'Senate LDA' scope and the intent-layer framing, which are useful conceptual details, but it doesn't disclose other behavioral traits such as rate limits, authentication requirements, or pagination behavior beyond the limit parameter. With annotations covering safety, a 3 is appropriate.

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 informative and front-loaded: the first sentence states the core purpose and data fields, then the bill= option, then the conceptual contrast, then concrete examples. Each sentence earns its place, though it's a bit longer than strictly necessary. It's well-structured for an agent scanning for key details.

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

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

Given the tool has 5 optional parameters, no output schema, and no nested objects, the description provides a solid overview of what the tool returns (the various data points) and how to query it. It covers the main parameters and gives examples. It doesn't specify the return structure or clarify whether parameters can be combined, but for a data-lookup tool this is adequate.

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 each parameter (bill, limit, ticker, company, since_year) already has a clear description. The tool description adds example usage ('what is Coinbase lobbying on', 'who lobbied HR1234') that helps infer how parameters combine, but it doesn't add significant semantic detail beyond the schema. 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 clearly identifies the tool as Senate LDA lobbying disclosures and enumerates the exact data it returns (spending, firms, issues, agencies, bills, former government posts). It distinguishes itself from related tools by positioning lobbying as the 'intent layer' vs. super PAC money as the 'FOR' layer, making its purpose unambiguous.

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

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

The description gives a specific usage hint ('Or pass bill= for everyone who lobbied a given bill') and contrasts with super PAC tools ('This is the intent layer...'). It provides example queries like 'what is Coinbase lobbying on' to illustrate use cases, though it doesn't explicitly list when NOT to use it beyond the conceptual contrast.

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

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

The description goes well beyond the readOnlyHint annotation by disclosing identity resolution behavior, employer-spelling folding, FEC name handling, ambiguous-name behavior, and the exact components of the returned trail. This gives the agent important expectations about edge cases and return semantics that annotations alone cannot provide.

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

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

The description is dense but every sentence contributes: it defines the question being answered, outlines the return structure, and resolves the most likely input ambiguities. The most important scoping information is front-loaded in the first sentence.

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?

Even without an output schema, the description enumerates the main return categories, explains how names are resolved, and mentions the employer narrowing mechanism. For a tool of this complexity, this is sufficient for an agent to select it and invoke 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 already solid. The description adds valuable semantic detail for the name parameter, explaining that names can be written naturally, that FEC form is handled, and that ambiguous names expose matched_as and can be narrowed with employer. This meaningfully augments the schema text.

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 resource and action: following one donor's money from initial giving through intermediate entities to recipient committees and their spending. It also distinguishes itself from siblings by focusing on a donor-centric trail rather than aggregate totals or politician-centric lookups. Example questions like 'how much did Elon Musk give to Trump' make the intended use immediately recognizable.

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

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

The description clearly conveys when to use the tool via concrete question patterns and by defining the scope as 'a person or organization.' It does not explicitly name sibling tools or state when not to use it, but the context is strong enough that an agent can infer the appropriate selection.

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

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

Annotations provide readOnlyHint=true, and the description adds meaningful behavioral context beyond that: the data source (FEC Schedule E), the scope (independent spending to support or oppose), and that it returns totals. It does not mention pagination, response shape, or rate limits, but for a read-only data lookup with strong source disclosure, this is solid.

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 compact and front-loaded: the first sentence defines the tool precisely, the second provides illustrative queries, and the final tip is short and useful. Every sentence earns its place with no redundant wording.

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

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

Given the tool's simplicity, three well-documented parameters, and no output schema, the description covers the essential context: what counts as outside money, what is returned, and example natural-language queries. It omits details like whether support and opposition totals are shown separately, but the phrase 'support or oppose' and the limit parameter's 'per side' description cover the main 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 description coverage is 100%, so the baseline is 3; the description adds a modest reminder that candidate names go in as written, which complements the schema examples. It does not add substantive meaning to the cycle or limit parameters beyond their existing schema descriptions, so no higher score is warranted.

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

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

The description states a specific action with a clear resource: it lists every super PAC and other filer spending independently to support or oppose a candidate, with totals from FEC Schedule E. It is unambiguously per-candidate and independent-spending oriented, which distinguishes it from sibling tools like pac_totals or super_pacs. The example queries reinforce what the tool answers.

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

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

The description provides clear context through example questions such as 'who is backing Trump' and 'which groups are attacking this senator', implying when to use the tool. It does not explicitly name alternative tools or state when not to use it, so it stops short of a 5. The note 'Candidate names go in as written' also gives practical input 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 readOnlyHint, so the description adds useful behavioral context: lookup can be by public-company ticker or partial committee name, and results include the candidates funded. It does not cover edge cases like both filters combined or default limit, but the read-only safety is already annotated.

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 sentences front-load the core function, then give illustrative queries and routing to alternatives. No redundant filler; 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?

For a tool with no output schema and no required parameters, the description covers purpose, lookup modes, result content, and alternatives. It is slightly incomplete about whether at least one filter is required and how ticker and committee_name interact if both are supplied, but overall an agent has enough to invoke it sensibly.

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?

Input schema descriptions cover all three parameters (limit, ticker, committee_name), so baseline is 3. The description reinforces the ticker/committee_name lookup roles with examples but adds no meaning beyond the schema and does not clarify parameter interaction.

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

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

The description names the exact resource: corporate and trade-association PACs linked to a public company or found by committee name, with the candidates they fund. It uses concrete example questions to make the lookup intent unmistakable and explicitly distinguishes itself from super_pacs and money_trail.

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

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

It states when to use it: for corporate/trade-association PACs by ticker or committee name. It also gives a clear exclusion and alternative: for super PACs and mega-donors, use super_pacs and money_trail instead. This is explicit 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?

The readOnlyHint annotation already signals a safe read operation, so the description doesn't need to re-establish that. It adds useful behavioral context: contributions are FEC Schedule A based, conduits like ActBlue and WinRed are separated out, and mode changes the interpretation from contributor totals to committee-reported disbursements. No contradiction with annotations exists.

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

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

Three sentences carry all the essential information: scope, data source, mode behavior, and routing to super_pacs. There is no filler, no repetition of schema details, and the most decision-relevant facts are front-loaded.

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-only tool with no required parameters and a fully self-documented schema, the description covers everything an agent needs to invoke it correctly: ranking basis, election-cycle dimension, conduit handling, mode switch, and the boundary with super_pacs. The return shape is sufficiently implied by 'ranked by total dollars,' and no output schema exists to add further detail.

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 explaining what mode=disbursers actually does and by framing cycle as an election-cycle filter. limit and query are already well described in the schema, so they don't need additional explanation.

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

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

The description clearly identifies what the tool does: it lists PAC contributors to tracked candidates ranked by total dollars from FEC Schedule A. It also explicitly differentiates the tool from super_pacs, so an agent can distinguish it from the most similar sibling without opening the schema.

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

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

It gives explicit usage direction: use for 'which PACs donate the most to Congress' questions, and use super_pacs instead for super PAC questions. It also explains when mode=disbursers should be selected, making the routing guidance 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?

With readOnlyHint=true already covering safety, the description adds useful behavioral context: results are newest first, the total count comes from total_on_file, and the dataset is explicitly a USPTO strategic-area sample rather than every patent. It does not detail rate limits or authentication, but the sample caveat is important.

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 resource and returned fields, then moves to invocation guidance and a caveat. It is somewhat dense but every sentence contributes useful 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?

There is no output schema, so the description carries the burden of explaining return values, and it does: patent number, owner as filed, grant date, abstract, USPTO link, total count, and newest-first ordering. It also discloses the key dataset limitation.

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 schema already documents all four parameters, including limit defaults and ranges. The description adds exact-match semantics for assignee and mentions offset paging, but does not add much 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?

The description states a specific resource and scope: patents HillSignal holds for a company, including the returned fields and ordering. It is clearly distinguishable from the sibling tools, none of which cover patent records.

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 concrete invocation guidance: pass ticker or assignee, use total_on_file for count questions, and use offset paging to list results. It does not name alternatives, but no sibling tool is a comparable patent lookup.

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 readOnlyHint and idempotentHint, which are a safety profile, not behavior. The description adds substantial behavior beyond that: the normalization strategy, the underlying data sources (SEC legal names, aliases, Exhibit 21 subsidiary map), and the return contract (method + confidence, or the miss reason). The 'never guesses' guarantee is a meaningful behavioral disclosure about failure modes.

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 sentences with zero waste: purpose is front-loaded, the entity-type enumeration justifies itself by scoping valid inputs, and 'Never guesses.' is a compact behavioral qualifier. 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?

For a single-parameter tool with no output schema, the description covers the input domain, the matching strategy, and the return values (method and confidence, or the reason for a miss). Paired with the read-only/idempotent annotations, 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% ('Organization name as written'), so the baseline is 3. The description adds material meaning to the `name` parameter by enumerating what kinds of organization names are valid inputs and clarifying that the name will be matched via exact normalized comparison.

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 ('Map'/'Resolve') and resource (organization name → public-company ticker), with an enumerated scope of accepted entity types (contract recipient, subsidiary, PAC sponsor, Form D issuer). The exact-match and 'never guesses' qualifiers distinguish it from the sibling search/PAC tools even though no sibling is named explicitly.

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

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

The usage context is implied by the exact-normalized-match behavior and the 'never guesses' guarantee, which signals this is not the tool for fuzzy resolution. However, it never names a sibling alternative or states explicit when-to-use/when-not-to-use conditions; an agent must infer when to prefer this tool over the other lookup/search tools.

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

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

Beyond the readOnlyHint annotation, the description discloses pagination mechanics (offset, up to 50 per call), return shape (total_matching), sort behavior, and, critically, that each amount is lifetime value rather than obligated-in-range. That data-interpretation trap is exactly the kind of thing an agent cannot infer from schema or annotations.

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

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

Three sentences, each doing distinct work: capabilities first, then return and paging behavior, then the amount-semantics warning placed where it will be read. No filler or restated boilerplate.

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 10-parameter tool with no output schema, the description covers return shape (total_matching, page rows), paging limits, and the meaning of the amount field. It does not describe the individual fields of each award record, leaving that to be discovered at runtime.

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 every parameter is already documented with format and examples. The description mostly restates the filter facets and the date/amount sort options, adding only the interpretive caveat about what award amounts mean.

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 ("Search federal contract awards") plus the source and scope ("USAspending, $10M+") and enumerates the filterable dimensions. An agent can tell this is an award-level search distinct from aggregate tools like award_totals.

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?

Usage is clearly implied by the search-by-facets framing, and the closing warning against summing amounts steers the agent toward an aggregate tool for period totals. It never names a specific alternative or an explicit when-not-to-use, 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?

Annotations already provide readOnlyHint=true, and the description does not contradict that. It adds the useful context that results include analysed sector and ticker exposure, but it does not disclose pagination, result formatting, or any other behavioral details beyond what the annotation already 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?

A single sentence that leads with the core scope and then lists the available filters. Every word earns its place, with no redundant filler or repetition of schema details.

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-only, all-optional search tool, the description plus the fully-covered input schema gives an agent enough to select and invoke it: the search scope, the key filters, and the nature of the results. It is slightly incomplete on alternative routing and no output schema, but those are secondary 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. The description restates the main filter dimensions (bill number, ticker, sector, date, event type) but adds no extra semantic detail beyond what the parameter descriptions already provide.

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

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

The description clearly states the tool does full-text search over bills, contract awards, and other government events, with analysed sector and ticker exposure. This gives a specific verb and resource, though it does not explicitly differentiate itself from search_awards or latest_events among the siblings.

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

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

The intended use is implied: an agent should use this when searching bills, contract awards, or government events by text and filters. However, there is no explicit guidance about when to use search_awards, search_opportunities, or latest_events instead, nor any exclusions.

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, so the safety profile is covered. The description adds real value beyond that by disclosing what each result carries (hillsignal_url and ui_link) and their intended use. It stops short of mentioning pagination or rate behavior, but for a read-only search that is a minor gap.

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, then filter options, then return-value guidance and the sibling pointer. Dense but every sentence carries information. Slightly long, but no filler sentences.

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 naming the key return fields (hillsignal_url, ui_link) and their purpose. Combined with the sibling routing, an agent has everything needed to select and invoke 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 all six parameters are already documented in the schema. The description only restates the filterable dimensions (keyword, NAICS, agency, notice type, date) without adding format or constraint details. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Search) and resource (SAM.gov notices), and enumerates exactly which notice types it covers (Sources Sought, Pre-solicitations, solicitations, combined synopses). It also distinguishes itself from the sibling get_opportunity, which handles single-notice analysis.

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 routes the agent: use this for searching/filtering, and call get_opportunity with a hillsignal_url for full analysis of one notice. It even specifies how to present results (give hillsignal_url to the user, ui_link as the SAM.gov source).

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, so the description is not required to restate safety. It adds meaningful behavioral detail: the data source is FEC committee totals, different parameters switch the output mode, committee profiles include donors, candidate spending, and vendors, and public companies are resolved to tickers. It does not disclose pagination or exact response shape, but the main behaviors are transparent.

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

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

The description is longer than average, but the tool has multiple distinct modes and ten parameters, so the detail is largely justified. It is front-loaded with the primary ranking purpose, then systematically covers each mode, and ends with concrete question examples. A few phrases are redundant with later examples, giving it a 4 rather than 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 carries the burden of describing return behavior, and it does so at a useful level: committee lists, committee profiles with donors/candidates/vendors, shared vendor lists, and public company rankings. It does not specify exact response fields, potential mode conflicts, or edge cases like invalid committee ids, but for an agent selecting and invoking the tool it is largely sufficient.

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 essential interaction semantics that the schema alone does not convey: query/committee_id trigger a committee profile, shared_vendors switches to vendor sharing, public_companies switches to ticker-ranked companies, and ticker/min_committees are only meaningful within those modes. This goes well beyond individual parameter descriptions.

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

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

The description names a specific resource (super PACs) and a set of specific verbs/behaviors: ranking committees by money raised/spent/on hand, returning a committee profile with donors and expenditures, listing shared vendors, and ranking public companies by political contributions. It clearly distinguishes the tool's multi-modal scope from generic political money tools.

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

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

The description provides strong usage context through conditionals: 'With query or committee_id', 'With shared_vendors', and 'With public_companies', and it gives representative natural-language questions to match against. However, it does not explicitly name sibling alternatives like outside_money or pac_lookup, nor state when this tool should not be used.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, which signal safety and repeatability. The description 'No description available.' does not contradict these annotations. However, the description adds zero behavioral context beyond the annotations. With annotations covering the safety profile, no contradiction exists, and a baseline 3 is appropriate since the description neither helps nor hurts behavioral transparency.

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

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

An empty description is under-specification, not conciseness. There is no information to evaluate for front-loading or sentence economy. A single title line plus 'No description available' does not constitute a structured definition. This is not concise; it is absent.

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

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

The description is completely inadequate. Even with a 0-parameter schema and read-only annotations, the tool name 'track_record' plus title 'HillSignal forward track record' suggest a dataset, but no explanation of what 'forward calls' means, what data is returned, or how it relates to sibling tools. An agent cannot correctly invoke or interpret this tool's results. Completeness is essentially zero.

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

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

The input schema has 0 parameters, so there is nothing to document. Baseline 4 applies for tools with no parameters. The description says 'No description available,' which is irrelevant here since no parameter semantics are needed. The schema itself fully defines the calling contract with an empty object.

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 is empty for this tool. The title 'HillSignal forward track record' identifies a resource-specific metric, but no description exists. The description says 'No description available.' This is a tautology that restates the title without any verb or resource-specific action. An agent cannot determine what this tool does from the description alone, especially alongside 14 sibling tools covering similar political finance data types. Purpose clarity fails completely.

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

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

There is zero guidance on when to use this tool vs. siblings. No context about whether this is a read-only lookup, a summary statistic, or a queryable dataset. With 14 sibling tools covering PACs, politicians, insider trades, and other data, an agent has no way to route to this tool correctly. No usage guidance whatsoever.

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