Compound Interesting — market intelligence

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

Annotations already declare readOnlyHint=true, so the description does not need to repeat safety. It adds useful content context (records contain consensus, dimensions, provenance, risk flags) but does not disclose behavior like data freshness, latency, or how missing tickers are handled. No contradiction 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?

Two concise sentences that front-load the core value ('Everything the platform knows about one ticker in a single record') and end with a clear usage directive. No filler or redundancy.

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

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

For a simple one-parameter read tool without an output schema, the description adequately explains the record's composition and offers guidance on when to use it. It could be slightly more complete by specifying return type or error behavior, but the current content is largely sufficient given its simplicity.

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%--the single parameter 'ticker' is described with an example (AAPL). The description does not add further parameter 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 uses a specific verb ('get') and clearly identifies the resource ('composite signal for a ticker'). It enumerates what the record contains (cross-signal consensus, contributing dimensions, provenance, risk flags) and differentiates from siblings like get_consensus by framing it as the comprehensive 'everything' endpoint.

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 'Start here for any question about a specific company,' signaling a clear use case. While it does not explicitly mention when to use sibling tools instead, the 'start here' instruction implies a first-stop role and provides enough context for 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?

With readOnlyHint=true already provided by annotations, the description adds context by explaining what 'consensus' means (agreement among insiders, Congress, institutions, the model) and that a per-dimension breakdown is included. It does not introduce contradictions and provides meaningful behavioral context beyond the annotation.

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 front-loads the core purpose and uses no wasted words. It clearly communicates the tool's function and output in an efficient manner.

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 low-complexity tool with one required parameter, a read-only annotation, and no output schema, the description adequately conveys what the tool does and what it returns. It could specify exact response fields, but the high-level 'verdict and per-dimension breakdown' is sufficient for an agent to understand the tool's behavior.

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

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

The input schema fully describes the only parameter (ticker symbol, e.g., AAPL) with 100% coverage. The description adds no additional parameter-specific semantics, so the baseline score of 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's purpose: checking whether independent actors (insiders, Congress, institutions, the model) agree on a single ticker, and it mentions the per-dimension breakdown. This distinguishes it from siblings like rank_consensus (which likely ranks across tickers) and get_signal (which likely returns a single signal).

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 a single ticker through 'on one ticker,' but it does not explicitly state when to use this tool versus alternatives like rank_consensus or get_signal, nor does it provide exclusions or when-not-to-use guidance.

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

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

The readOnlyHint annotation already signals safety, but the description adds unique behavioral context: no API key required and output is always the demo ticker regardless of input. This goes beyond what annotations provide, though it doesn't detail rate limits or return format.

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 concise sentences, each earning its place: purpose, behavior, and alternative. Information is front-loaded with the most important facts first, zero fluff.

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 parameters and no output schema, the description fully covers what the agent needs to know: what it returns (demo ticker), why (inspect data shape), auth constraints (no key), and how it differs from the real tool. No 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?

With zero parameters, the baseline is 4. The description adds value by explaining that input is irrelevant ('regardless of input'), which preempts any attempt to pass a ticker. Given the empty schema, this semantic clarification is helpful.

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 defines the tool as a fixed demo ticker for inspecting data shape, with the specific goal of pre-signup exploration. It explicitly distinguishes from get_composite for real tickers, satisfying the 'specific verb+resource+scope' criterion.

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 when to use (before signing up) and when not (for real tickers), and names the alternative tool get_composite. This provides clear decision 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 include readOnlyHint=true, so the read-only nature is already known. The description adds valuable behavioral context: the distinction between 'not listed' and flat/zero, and the rarity of coverage. This goes beyond the annotation and clarifies interpretation of results.

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

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

Three sentences, each earning its place: the first states the core function, the second provides coverage context, and the third clarifies an important interpretation caveat. No redundancy or filler.

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

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

For a simple, one-parameter read operation with no output schema, the description covers the essential elements: what data is returned, the limited universe, and the non-zero meaning of 'not listed.' It could mention the exact output fields (e.g., funding rate value, open interest amount) but is otherwise 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 schema provides 100% coverage for 'ticker' with a basic example. The description enriches this by clarifying that only a small subset of tickers is valid for this venue, which is essential for interpreting 'not listed' responses. This adds meaning beyond the schema's simple type 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 specifies the resource: funding and open interest for a single ticker on the perpetual venue. It distinguishes from list_equity_perp by emphasizing 'single name,' though it lacks an explicit verb like 'retrieves' or 'returns.'

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 strong contextual guidance by warning that most tickers are not listed (51 of ~5,400) and that a 'not listed' answer means no coverage, not zero positioning. This helps set expectations, though it does not explicitly name alternative tools or when to prefer them.

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

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

Annotations only provide readOnlyHint=true, so the description carries the burden for extra behavioral context. It discloses that paid keys are required, that the tool is slower because it computes on demand, and that results include the filing each document came from. This adds meaningful behavior beyond the annotation without contradicting it.

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 succinct yet informative: two sentences present the core purpose, followed by usage guidance and constraints. There is no wasted wording or repetition of schema fields, making it easy to scan.

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 (one parameter, readOnly annotation, no output schema), the description provides sufficient context: what is returned, use case, auth requirement, and performance characteristic. It could go further by describing output structure in more detail, but it adequately covers the essentials.

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 already documents 'ticker' with an example (e.g., AAPL), and schema coverage is 100%. The description does not add additional parameter-level details but ties ticker to 'a ticker's signals,' which is mild context. This meets the baseline for schema-covered parameters.

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

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

The description clearly identifies the tool as returning the primary source documents behind a ticker's signals, listing specific document types (Form 4s, congressional disclosures, institutional holdings, macro series). This distinguishes it from sibling tools like get_signal or get_consensus by emphasizing the underlying evidence, though the verb is implicit rather than explicitly stated ('retrieves').

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 clear use case: 'Use this to cite a claim rather than assert it.' It also notes constraints: paid keys only and slower than other tools due to on-demand computation, implying alternatives for speed or without paid access. However, it does not explicitly name specific sibling tools to use instead.

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

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

Annotations declare readOnlyHint=true, and the description adds valuable behavioral context beyond that: it details the exact statistical outputs, clarifies the 5-year sampling window, and warns that values are fractional (0.0821 means 8.21%). This helps the agent interpret results correctly without contradicting the read-only hint.

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

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

The description is three sentences long and every sentence earns its place: listing the outputs, stating the use case, and explaining the fractional notation. No extraneous words or repetition of the name/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?

For a simple read-only tool with one parameter and no output schema, the description is complete: it enumerates the returned metrics, states the historical window, and explains the value format. It provides enough context for an agent to know what to expect and when to use it, without needing an output schema.

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% for the single ticker parameter, which already explains it clearly. The description does not add further parameter semantics, but it doesn't need to. Baseline 3 is appropriate since the schema fully covers the parameter.

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

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

The description clearly states what the tool does: provides the historical distribution of 5-day and 1-month returns for a ticker over the last 5 years, including mean, standard deviation, percentiles, histogram, and worst drawdowns. It also explicitly frames its purpose ('whether a move is unusual FOR THIS NAME'), distinguishing it from generic market analysis tools like get_composite or get_signal.

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 usage context: 'Use it to say whether a move is unusual FOR THIS NAME rather than in the abstract.' This implies the tool is for ticker-specific historical comparison, but it doesn't explicitly mention when not to use it or name alternative sibling tools. The guidance is sufficient for most intended scenarios.

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, covering safety. The description adds a useful interpretive nuance ('not a recommendation') but does not disclose any further behavioral traits such as return format or potential limitations. Reasonable for a simple read-only tool.

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

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

The description is two concise sentences, front-loaded with the core purpose and immediately clarifying the nature of the rating. No fluff, every phrase serves a purpose.

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 tool with one parameter and no output schema, the description covers the essential return value (rating + reasoning) and adds the non-recommendation context. It could specify the return structure more precisely, but is largely complete for this complexity level.

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 only parameter, ticker, is fully described in the input schema with an example (AAPL). The description adds no additional meaning beyond the schema, so baseline score of 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?

Clearly states it returns the platform's own buy/hold/sell rating for a ticker, including the reasoning. Distinct from likely siblings like get_consensus by explicitly saying it's the platform's own judgement.

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 clear context that this is the platform's proprietary rating, not a recommendation to readers, which helps select it over consensus or recommendation tools. However, it does not explicitly name alternative tools or state 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?

Beyond the readOnlyHint annotation, the description discloses meaningful behavior: data is sourced from available published filings, results include coverage metadata and unknown-value counts, scope is through today in the current UTC month, and result counts are capped by key type. These details materially set expectations without contradicting the annotation.

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 earning its place: the core aggregation scope, the data caveats, and the entitlement caps. No filler or redundant restatement of the schema.

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 aggregator with only two parameters and no required output shape, this is complete: purpose, time window, data caveats, output metadata, and limits are all covered. An agent can select and call it correctly without missing critical context.

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 `kind` and `month` fully, including accepted values and the current-month-only restriction. The description adds no parameter-specific semantics beyond what the schema already states, so the 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 uses a specific verb-resource combination: 'Rank ticker activity aggregated from available published filings by transaction date' for the current UTC month. This clearly distinguishes it from trade-list siblings like list_insider_trades and list_congress_trades, which would provide individual filings rather than a monthly aggregate ranking.

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: use this for current-month aggregated ticker rankings from insider or congressional filings, and it warns 'this is not total market activity' and states key limits. It does not explicitly name alternative tools or state when not to use it, 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 declare readOnlyHint=true, so the safety profile is covered. The description adds value by explaining the conceptual meaning of each signal option, which aids the agent in interpreting the result. It does not describe the return format, but given the read-only nature and simple parameter, 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 three concise sentences that front-load the purpose, then list the parameter meanings, and end with usage guidance. No wasted words or redundancy.

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

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

For a tool with a single parameter and no output schema, the description covers the purpose, parameter semantics, and usage context. It stops short of stating the return format (e.g., numeric value, JSON), but given the simplicity, this is a minor omission.

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 schema provides only an enum list with zero description coverage. The description fully compensates by explaining each enum value: 'macro' is the market-regime read, 'energy' the macro energy balance, and 'crypto' crypto positioning and funding. This is exactly the semantic enrichment needed.

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's role as a 'whole-market gauge' and differentiates it from per-company tools. It enumerates the three specific signal types ('macro', 'energy', 'crypto') with their meanings, making the purpose 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 explicitly tells when to use the tool: 'Use these for the backdrop a single name is trading against.' It also contrasts with per-company tools, implying that for individual equity signals, one would use a different tool. This provides clear context though it does not name specific sibling alternatives.

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 ordering (newest first), linking to disclosures, and the crucial interpretive stance that committee overlap is reported as oversight, not accusation. This adds significant context for the agent's appropriate use of results.

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

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

Two sentences, front-loaded with the core purpose. The second sentence adds valuable context about disclosure links and the non-accusatory framing without wasted 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?

For a simple read-only list tool with no output schema, the description adequately covers key aspects: scope, ordering, and linkage. It does not detail return fields or pagination behavior, but the schema already includes cursor logic, so completeness is strong.

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 covers all four parameters with full descriptions (limit, since, cursor, ticker), so schema coverage is 100%. The description does not add parameter-specific detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states it lists disclosed House and Senate trades, newest first, and distinguishes from sibling list_insider_trades by specifying Congress-specific scope. The verb 'Disclosed' combined with the resource makes the action 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 provides clear context for when to use the tool (listing congressional trades) but does not explicitly mention alternatives or when not to use it. Since the context is self-evident and differentiates adequately, it earns a 4.

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 adds critical behavioral context: the mark price is a venue mark, not the stock price, and high positive funding indicates crowded, squeeze-fragile positioning. This is valuable non-obvious information that significantly enhances understanding.

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

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

Three dense, purposeful sentences. The first defines the tool, the second specifies when to use it, and the third explains how to interpret the data. Zero fluff or redundancy.

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

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

For a simple tool with one parameter, high schema coverage, and a readOnly annotation, the description is remarkably complete. It covers purpose, usage timing, interpretation, and a critical caveat about the mark price. No output schema is needed to understand the returned data.

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 schema already describes the 'limit' parameter (100% coverage), so baseline is 3. The description adds meaning by revealing the universe size (~51 names) and that results are ranked by notional, which informs how limit should be interpreted and used.

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 funding rate and open interest for ~51 US single-name perpetuals, ranked by notional. This specific verb+resource+scope distinguishes it from sibling tools like get_equity_perp, and the added 'ONLY source here that moves outside US market hours' context further differentiates its purpose.

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 states when to use it ('what to check overnight and at weekends') and even explains it is the 'ONLY source' for that use case. It does not explicitly name alternatives or state when not to use it, but the guidance is clear and practical.

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 covers safety, and the description adds behavioral context beyond that: 'newest first' and 'each linked to the filing it came from' communicate sort order and output linkage, providing useful details not captured in 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, front-loaded sentence with no filler. It conveys all essential information efficiently 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?

For a simple list tool with comprehensive schema and annotations, the description is complete enough. It explains the core functionality and key output details, though it doesn't elaborate on return structure or pagination, which are already covered by the schema via cursor 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 description coverage is 100%, so the schema already documents all parameters. The description does not add any parameter-specific semantics beyond what the schema provides, meeting the baseline despite no extra info.

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 corporate insider buys and sells from SEC filings, sorted newest first, with links to filings. This specific verb+resource distinguishes it from siblings like list_congress_trades and other list 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 clear context for when to use the tool: when you need insider trades from SEC filings. It implicitly distinguishes from congress trades and other list tools, though it doesn't explicitly name alternatives 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?

Given the readOnlyHint annotation, the safety profile is already known. The description adds meaningful behavioral context: results are sorted newest first, and net figures may include hedges, warning against misinterpreting them as directional views. This goes beyond the annotation without contradicting it.

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 delivers the core purpose and a critical caveat. Every word earns its place, and it is front-loaded with the most essential 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?

The description covers the essential purpose and the key interpretation caveat. While there is no output schema and the return fields are not described, the schema already documents cursor pagination, and the title plus description provide a solid mental model for a list tool. Minor gaps remain regarding response structure, but the overall context 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?

The input schema provides 100% coverage for all four parameters (limit, since, cursor, ticker) with clear descriptions. The tool description does not add any additional parameter-specific meaning, so the baseline of 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 clearly identifies the tool's function: displaying how large holders are positioned, with a specific ordering ('newest first'). The title 'Institutional and derivative positioning' reinforces the resource type. It is easily distinguishable from sibling tools like list_insider_trades or list_congress_trades, which cover different actor types.

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

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

The description provides the context of what the tool shows and adds an important interpretive caveat about net figures, but it does not explicitly state when to use this over alternatives or exclude any use cases. Usage is implied rather than explicitly guided.

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 context about 'independent actors agree most strongly' (the ranking logic), but doesn't mention operational details like default ordering, pagination, or what happens when filters are omitted. This is adequate but not rich.

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: the first states what the tool does, the second gives usage guidance. No redundant words 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 ranking tool with 4 optional, well-described parameters and no output schema, the description gives enough purpose and usage context. It could mention how filters interact with ranking, but the presence of schema descriptions and the readOnly annotation keeps it complete enough for 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% – every parameter has a description (limit, direction, min_signals, min_agreement). The tool description adds no additional parameter meaning beyond the schema, so the baseline of 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 it returns 'names where independent actors agree most strongly, ranked' – a specific verb+resource (ranked list of consensus names). It distinguishes from siblings by contrasting with 'to check one you already have in mind', making its screening purpose explicit.

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 says 'Use this to find candidates rather than to check one you already have in mind' – giving clear when-to-use direction and an implicit when-not-to-use. It doesn't name alternative tools, but the contrast is strong enough to guide 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?

The readOnlyHint=true annotation already covers the safety profile, so the description only needs to add behavioral context. It adds that the tool is a bulk discovery tool returning scores, but does not disclose filtering behavior details beyond the schema. This is adequate but not rich.

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 purposeful sentences with no filler. The core action is front-loaded, the use case is clear, and the sibling alternative is given in one short 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?

For a 9-optional-parameter filter tool with full schema coverage, the description provides enough context to choose and invoke the tool. It could mention what the returned rows look like, but the description's 'matching tickers with their scores' plus the schema's param descriptions largely cover agent needs.

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 fully documents all 9 parameters. The description does not add parameter-level meaning beyond mentioning 'scores', so it stays at the baseline rather than enhancing understanding.

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

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

States a specific verb ('Filter') and resource ('the whole equity universe'), and specifies the output: matching tickers with their scores. It also distinguishes itself from the sibling rank_consensus tool, making selection unambiguous.

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

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

Explicitly frames the tool as the bulk discovery tool for questions of the form 'which companies have X', and names the alternative rank_consensus for ranking by cross-signal agreement. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds the scoping constraint ('the platform covers'), which is useful, but does not mention output format, pagination, or edge cases. It meets the baseline but does not go beyond.

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 core purpose, and no wasted words. Every sentence contributes value, and the structure is ideal for quick parsing by an AI agent.

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 one-parameter, read-only lookup tool with no output schema, the description provides enough context: what it does, its scope, and when to use it. No critical information is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents the 'query' parameter. The description restates the same meaning without adding new semantic detail, so the baseline of 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 has a specific verb ('resolve'), a clear resource ('tickers'), and a defined scope ('the platform covers'). It clearly distinguishes itself from sibling tools by being the only search/resolution tool in the 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 states when to use this tool: 'Use this first when the user names a company rather than a symbol.' This provides clear context for tool selection, even though alternatives are not named.

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