trades

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description complements this by detailing the output (totals, splits, top tickers, etc.) without contradicting. No hidden destructive or mutating behavior is implied.

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, two sentences long, with no wasted words. The first sentence states the purpose and outputs, the second provides usage guidance. Information density is high and scannable.

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, the description lists all key statistics returned. It also clarifies that it accepts the same filter set as search_trades, providing enough context for an agent to decide when to use it. With read-only and idempotent annotations, no further behavioral notes are needed.

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 description explains that parameters branch, role, since, until, type, and ticker serve as filters, and provides usage context (e.g., 'pass branch=congress + role=Senate'). While the schema already covers 50% of parameters with descriptions, the description adds meaning by grouping them and showing their role as filters, slightly beyond schema alone.

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 metrics like totals, branch split, most-active officials, etc. It distinguishes itself from sibling tools like search_trades by being an aggregation tool rather than a paginated 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?

Explicitly advises to 'Use this BEFORE paginating search_trades when you only need ranked counts.' Also gives concrete filtering examples (e.g., branch=congress + role=Senate) and notes that it accepts the same filters as search, making when and how to use it very 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 agent knows it's safe. The description adds minimal value by stating 'all disclosed trades' but fails to disclose pagination behavior, data source (STOCK Act), potential volume, or response format. No contradictions with 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 extremely concise (one sentence), but at the cost of completeness. It is front-loaded with the core purpose but wastes no words. However, for a 2-parameter tool with no output schema, this brevity is insufficient, making it more underspecified than concise. A score of 3 reflects adequate conciseness but poor content density.

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

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

The tool has no output schema, 2 parameters (1 required), and 0% schema coverage. The description provides only a basic purpose, omitting how to use the 'limit' parameter, what the output contains, error scenarios, data recency, or relationship to sibling tools. This is severely incomplete for effective agent invocation.

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

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

Schema coverage is 0%, meaning no parameter descriptions in the schema. The description does not mention the 'name' or 'limit' parameters. While 'named member' implies the 'name' parameter, it provides no format guidance, and the 'limit' parameter is entirely undocumented. This fails to add meaning 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 clearly states the tool returns 'All disclosed trades for a named member of Congress or executive-branch official.' This distinguishes it from sibling tools like 'search_trades' (which might search by other criteria) and 'get_ticker_activity' (by ticker). The verb 'get' and resource 'trades' with the specific scope of a person is precise.

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 no guidance on when to use this tool versus alternatives. It does not state prerequisites, conditions for use, or exclusions (e.g., 'use get_ticker_activity for stock-specific queries'). The agent must infer usage solely from the purpose.

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's mention of 'disclosed trades' aligns. No additional behavioral traits (e.g., pagination, ordering) are disclosed beyond what annotations 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?

Single sentence with no waste, front-loaded with the core function. However, it is too brief and omits parameter 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?

With no output schema and only two parameters, the description is minimal. It does not cover result format, ordering, pagination, or error behavior, leaving gaps for a simple query 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 has 0% description coverage, and the description only mentions 'given ticker' implicitly via 'ticker'. It does not explain the 'limit' parameter at all, failing to add meaning 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?

Description clearly states the tool returns officials who have disclosed trades for a given ticker. It specifies the resource (ticker) and the verb (get), but does not explicitly differentiate from sibling tools like 'get_person_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?

Usage is implied: to find which officials traded a specific ticker. No explicit guidance on when to use this over siblings like 'search_trades' or 'list_recent_trades', and no exclusions 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?

Annotations already indicate read-only and idempotent. The description adds the context of conflict detection criteria (sector overlaps), but omits details like pagination or authentication requirements.

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 sentences with no redundant text; front-loaded with the core purpose and followed by filter options.

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?

Adequately describes the core purpose and filterable fields, but lacks details on output format, handling of missing parameters, or default limit behavior.

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

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

Only the 'branch' parameter has a schema description. The description mentions branch/role/since/until filters but does not explain role, since, until, or limit, leaving significant gaps given low schema 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 clearly states the tool lists trades flagged as potential conflicts due to sector overlaps, with a verb and resource. It distinguishes from siblings like list_recent_trades but does not explicitly state how it differs from search_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 implies usage for viewing conflict-flagged trades with filters, but does not provide explicit when-to-use or when-not-to-use guidance relative to sibling tools like search_trades.

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?

Adds ordering info ('newest first') and filter compatibility beyond annotations. No contradictions. Annotations already cover read-only and idempotent behavior.

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 main purpose. Highly efficient.

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

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

No output schema, but description covers core functionality. Could mention default limit or return format, but adequate for a simple filtered list 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 covers 83% of parameters. Description adds value by referencing search_trades for filter consistency, but does not provide additional meaning beyond schema.

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

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

Description clearly states 'most recently disclosed trades — newest first,' specifying verb, resource, and ordering. Distinguishes from sibling search_trades by noting it accepts the same filters.

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

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

Provides guidance on when to use (for recent trades with filtering) and notes filter compatibility with search_trades, though does not explicitly state when not to use.

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 indicate readOnlyHint=true, idempotentHint=true, so the description's main behavioral addition is 'returns newest first'. This ordering info is useful but limited; no mention of pagination behavior or rate limits. The description does not contradict 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?

A single, well-structured sentence succinctly lists the searchable dimensions and the default ordering. No filler or redundancy; every word 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?

The tool has 11 parameters and no output schema. The description explains the search dimensions and ordering but does not describe the response format (e.g., each result includes trade date, amount range, etc.). Pagination is implied by limit/offset parameters but not acknowledged. Given schema richness, the description is adequate but not fully 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 coverage is 100% with detailed property descriptions (including case-insensitivity, default limit, etc.). The tool description merely lists parameter categories without adding new semantic details, so it adds minimal value 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 clearly states it searches disclosed trades by multiple criteria (person, ticker, branch, role, buy/sell, conflict flag, min amount, date range) and returns newest first. The tool name 'search' and the parameter list differentiate it from sibling tools like get_person_trades or list_recent_trades, though it does not explicitly contrast them.

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

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

The description enumerates the searchable filters but does not provide guidance on when to use this tool versus siblings (e.g., get_person_trades for a specific person). The default ordering and pagination (limit, offset) are implied but not stated as usage recommendations.

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