trades

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

Annotations mark it as readOnlyHint and idempotentHint, which the description aligns with. The description adds that it returns aggregated statistics, not raw data. No further behavioral details (e.g., performance) are needed given 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?

Two succinct sentences. First sentence lists what is returned; second provides usage context and example. No extraneous words.

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

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

With no output schema, the description sufficiently covers return contents. It also ties into the sibling context by referring to search_trades. Minor gap: does not clarify if the stats are counts or monetary values.

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 50%, but the description adds meaning by naming all six parameters (branch, role, since, until, type, ticker) and relating them to a known search filter set. The example clarifies how to use role, branch, and since together.

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 it provides 'Summary stats over the filtered set' and enumerates specific aggregations (totals, branch split, top tickers, etc.). This distinguishes it from sibling tools like search_trades which return individual 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?

Explicitly instructs to use this before paginating search_trades when only ranked counts are needed. Provides an example filter combination (branch=congress + role=Senate + since=YYYY-MM-DD).

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, idempotentHint, and openWorldHint. The description adds minimal behavioral context beyond stating 'All disclosed trades,' which implies comprehensive results. No contradictions, but limited added value.

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 concise sentence that efficiently communicates the tool's purpose with no wasted words. It is front-loaded and 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?

Given the tool's simplicity (2 params, no output schema), the description covers the core purpose but omits details like the optional limit parameter and return format. Minimal but adequate for a straightforward tool.

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

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

Schema description coverage is 0%, so the description must compensate. It implicitly clarifies the 'name' parameter as the person's name, but does not describe the 'limit' parameter or any format details. Adds some meaning but insufficient.

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 returns all disclosed trades for a named person, specifying both the resource (trades) and the scope (named member of Congress or executive-branch official). It distinguishes from siblings like search_trades which is more general.

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 indicates when to use the tool: when you have a specific person's name and want all their trades. It does not explicitly mention when not to use it or alternative tools, 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not contradict them. However, it adds minimal behavioral context beyond stating the purpose, such as no mention of pagination, sorting, or output format. With annotations covering safety, a score of 3 is appropriate for the limited added value.

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, concise sentence with no extraneous information. Every word adds value, and it is front-loaded with the core action, earning a top score for efficiency.

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

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

Despite low complexity (2 params, no output schema), the description fails to specify return values (e.g., list of officials, trade details). Without output schema, the description should compensate but does not, leaving the agent without crucial information 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 0%, meaning the description carries full burden. It clarifies that 'ticker' is the stock symbol, but provides no meaning for the optional 'limit' parameter (e.g., max number of results). This leaves ambiguity for the agent.

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 explicitly states the tool returns officials who have disclosed trades for a given ticker. It uses a specific verb ('disclosed trades') and resource ('officials'), clearly distinguishing it from sibling tools like get_person_trades (trades by person) and list_recent_trades (recent trades).

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 provided on when to use this tool versus alternatives. Context signals list sibling tools (e.g., search_trades, get_person_trades), but the description lacks any comparison or exclusion criteria, leaving the agent to infer appropriateness.

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

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

The description adds context beyond annotations by explaining the conflict logic (company sector overlaps official's committee or agency). This clarifies the filtering mechanism. No contradiction with readOnlyHint or idempotentHint.

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

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

The description is concise with two sentences: first states purpose, second lists filters. No filler text. Front-loaded with core functionality.

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?

While it explains the conflict criterion and mentions filters, it lacks details on return format, pagination, response structure, or how filters interact. Adequate for a read-only list tool but missing behavioral expectations.

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?

With only 20% schema description coverage (only branch has details), the description lists four parameter names (branch, role, since, until) but omits 'limit' and lacks any semantic detail beyond the names. This does not compensate for the schema gaps.

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?

Clearly states the tool lists trades flagged as potential conflicts due to sector overlaps. The description is specific and differentiates from siblings like list_recent_trades or search_trades by focusing on conflict status. However, it could be slightly more explicit about the verb (e.g., 'list').

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

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

No guidance on when to use this tool versus alternatives like search_trades or list_recent_trades. The description only mentions accepted filters but does not indicate context, prerequisites, or 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?

The description adds ordering behavior ('newest first') and filtering capabilities beyond the annotations. Annotations already declare readOnlyHint=true and idempotentHint=true, so the description provides complementary behavioral context without 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, no wasted words. Front-loaded with the core purpose ('most recently disclosed trades — newest first'). Every sentence adds value by defining scope and filter compatibility.

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 list tool with optional filters and no output schema, the description is sufficiently complete. It explains the ordering, filter reusability, and relationship to a sibling tool. A marginal improvement could explicitly mention that limit is optional, but the schema covers that.

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

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

Schema description coverage is 83% (5 of 6 parameters have descriptions). The tool description only mentions the filter parameters collectively without adding new meaning. Baseline score of 3 is appropriate as the schema already 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?

The description clearly states the tool returns the most recently disclosed trades in newest-first order. It distinguishes from the sibling search_trades by noting it accepts the same filters but is focused on recent trades.

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 notes that the tool accepts the same filters as search_trades, implying an agent can use it to scope to a chamber or window in one call. However, it does not explicitly state when to use this tool over alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds only the ordering detail 'Returns newest first.' No other behavioral traits (e.g., pagination behavior, rate limits, effect of filters) are disclosed beyond what annotations provide. This is adequate given the annotations.

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

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

The description is a single concise sentence that efficiently enumerates key filters and ordering. No wasted words, and it is front-loaded with the verb and resource.

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 absence of an output schema, the description does not explain what fields are returned in the results (e.g., trade date, amount, asset type). It only states 'Returns newest first', leaving the agent to guess the response structure. For a tool with 11 parameters and no output schema, this is insufficient.

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

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

All 11 parameters have descriptions in the input schema (100% coverage), so the description adds minimal new information. It merely re-lists some parameter categories without enhancing meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches disclosed trades with specific filters (person, ticker, branch, role, buy/sell, conflict, etc.) and returns results newest first. The verb 'search' and list of filters make the purpose clear, but it does not explicitly differentiate from sibling tools like get_person_trades or list_recent_trades.

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 lists many filters but provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where one of the sibling tools (e.g., get_ticker_activity, list_conflicts) would be preferable, nor does it specify prerequisites or exclusions.

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