ko-mcp

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

No annotations provided, so the description must bear the burden. It mentions what the output includes (trades, types, amounts, dates) but omits behavioral details like pagination, rate limits, or data freshness. The pagination parameters (page, limit) are not mentioned in the description.

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, clear and front-loaded. No unnecessary words; every sentence adds value.

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 no output schema and no annotations, the description is minimally complete. It states the tool returns trades with details but lacks information about pagination, error handling, or full scope of output. For a 3-parameter tool, more context would be beneficial.

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 33% (only `member` described). The description adds little beyond schema: it repeats 'specific U.S. Congress member' but doesn't clarify `page` or `limit`. The `member` parameter description within schema is helpful, but the main description doesn't elaborate further.

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 gets 'detailed trading history of a specific U.S. Congress member,' which is a specific verb and resource. It distinguishes from siblings like `get_congress_trades` (which likely covers all members) by focusing on a specific member.

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 does not explicitly guide when to use this tool versus alternatives. It implies usage when you have a specific member slug, but lacks explicit 'when to use' or 'when not to use' statements.

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?

Without annotations, the description fully explains the return format (markdown table with specific columns: member name, chamber, ticker, buy/sell type, transaction date, disclosure date, dollar amount range, owner). It discloses the behavior of filtering and sorting. However, it does not address potential limitations like data freshness, rate limits, or authentication, which would have pushed it to 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?

The description is concise at approximately 100 words, with no redundancy. It is front-loaded with the core purpose, then details the output format, example queries, filter/sort options, and a pointer to the sibling tool. Every sentence serves a clear 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?

Given 8 parameters, no output schema, and no annotations, the description covers all essential aspects: input, output format, usage context, and alternative tool. It provides enough information for an agent to correctly invoke the tool and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explicitly listing the filterable fields (chamber, party, state, ticker, member name) and sort options (volume, trades, recent) in a coherent sentence, complementing the schema descriptions. Example queries further clarify parameter usage.

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 verb 'Search' and the resource 'individual stock trades disclosed by U.S. Congress members (House and Senate) under the STOCK Act.' It also differentiates from the sibling tool get_congress_member by specifying that this tool is for searching trades, while the sibling is for one member's complete history.

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

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

Explicit guidance is provided on when to use this tool (for questions about member trades, filtering by various criteria) and when to use the alternative (get_congress_member for one member's full profile). The description lists filter and sort options, giving clear context for appropriate usage.

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

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

No annotations exist, so the description must reveal behavior. It mentions the data source (latest 13F filings) and returns, but omits details like data freshness lag, update frequency, or error handling. Some transparency exists but not complete.

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 pack purpose, scope, and output with no redundancy. Front-loaded and 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?

Given no output schema, the description covers return fields (total USD, QoQ change, per-ETF breakdown) adequately. Missing some details like data availability conditions, but sufficient for a simple 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?

Input schema has zero parameters, so schema coverage is 100%. Baseline 4 applies as the description does not need to add parameter details; it appropriately focuses on the tool's output.

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 provides a market-wide summary of institutional exposure to US spot crypto ETFs from SEC 13F filings, listing specific ETFs and data returned. This distinguishes it from siblings like get_crypto_holder which focus on individual holders.

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 institutional crypto ETF exposure but does not explicitly state when to use this versus alternatives. No when-not or exclusion guidance is 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns data from the 'latest filed quarter' and includes specific metrics. However, it does not mention any side effects, data freshness, caching behavior, or permissions. For a read-only tool, this is adequate but not exceptional.

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

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

The description is two concise sentences. The key purpose and output are front-loaded, and every sentence provides necessary information without 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?

The description explains what the tool returns (per-ETF positions with shares, USD, QoQ change, action, and rank) and includes the time frame ('latest filed quarter'). It also instructs on finding the input. For a tool with one parameter and no output schema, this is sufficient; however, missing output schema means the agent relies entirely on the description, which is clear but could mention potential limitations like data scope or update frequency.

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 has 100% coverage with a description of the 'institution' parameter (CIK or name). The tool description repeats the same information and adds only a suggestion to use get_crypto_holders to find the CIK. No additional semantic value is added beyond the schema, so a 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 verb 'Get' and specifies the resource as 'one institution's spot crypto-ETF holdings (Bitcoin ETF complex)'. It lists the data returned (per-ETF positions, rank) and references the sibling 'get_crypto_holders' implicitly by mentioning CIK numbers. However, it does not explicitly distinguish from 'get_crypto_exposure' or state when to use this tool over 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 provides guidance on how to obtain the required input ('Use a CIK number (find it with get_crypto_holders or the search tool)'), giving clear context for usage. It does not explicitly state when not to use this tool or list exclusions, but the context is sufficient for correct invocation.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the data comes from the latest quarter of SEC 13F filings (implying quarterly data), and that results are ranked by total USD held. It does not describe pagination behavior or rate limits, but the schema covers pagination parameters. The description is honest about its read-only nature and data freshness.

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 fluff. The verb and resource are front-loaded. Every word earns its place. It is appropriately concise for the complexity of 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?

The description covers the tool's purpose, data source, ranking, and optional filtering. It lacks explanation of the return format (fields like institution name, holdings, etc.) since there is no output schema. However, for a list tool with parameter schema coverage, it is fairly complete. It could mention the specific ETF complex (Bitcoin ETF) more explicitly.

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 all three parameters described. The description reinforces the product filter with an example ('IBIT'), but does not add significant meaning beyond the schema. For page and limit, it adds no new information. Baseline 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 verb 'List', the resource 'institutional investors holding US spot crypto ETFs', the ranking criterion 'total USD held', and the data source 'latest quarter of SEC 13F filings'. It distinguishes itself from siblings like get_crypto_holder (singular) and get_crypto_exposure by specifying it's a ranked list of all holders.

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 mentions optional filtering by product, implying when to use specific parameters. However, it does not explicitly state when to use this tool versus other sibling tools (e.g., get_crypto_holder for a single holder). It provides clear context but lacks explicit exclusions or 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?

No annotations are provided, so the description carries full responsibility. It does not disclose any behavioral traits such as data freshness, rate limits, or authentication requirements. It only names the data source (BLS) which is insufficient.

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 that conveys the main purpose and lists example indicators. No superfluous 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?

Given only 2 simple parameters and no output schema, the description is mostly complete. It could hint at the output format (e.g., historical data vs latest) but is adequate for most agents.

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 both parameters are already described in the schema. The description's 'Filter by category' adds minimal new meaning beyond the schema. 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 retrieves U.S. economic indicators from BLS and lists specific data points (CPI, PPI, etc.). It distinguishes this tool from siblings like get_fed_rates or stock-oriented 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 implies usage via 'Filter by category' and listing categories, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. The context is clear enough given sibling tool names.

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

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

No annotations are provided, so the description carries the full burden. It discloses the output format (markdown table), data coverage (up to 10 years daily history, newest first), and that it returns multiple rate series. It does not mention update frequency or data source, but for a read-only tool this is acceptable. Slightly more detail on behavior (e.g., intraday vs end-of-day) would justify 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?

The description is concise—three sentences that front-load the purpose and immediately follow with usage guidance and alternatives. Every sentence adds value without repetition or 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?

Given the tool has only one parameter and no output schema, the description fully explains what data is returned (list of specific rates), format (markdown table), ordering (newest first), and time range (up to 10 years). It also includes example questions. Nothing essential 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% with a description for the single parameter 'days' (default 30, min 1, max 3650). The description does not add extra meaning 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 identifies the tool as returning a markdown table of U.S. policy and money-market interest rates (Fed Funds, SOFR, Prime, Treasury yields). It specifies the verb 'Get', the resource 'daily rates', and distinguishes from the sibling 'get_treasury_yields' which covers the full Treasury curve.

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 when-to-use guidance (monetary-policy questions, inversion analysis) and when-not-to-use (for full Treasury curve, use get_treasury_yields instead). This directly helps an agent decide between 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?

No annotations are provided, so the description carries the burden. It discloses that the index is daily and that values above 0 indicate above-average stress, but doesn't mention rate limits, data freshness, or other behavioral traits. Basic but not comprehensive.

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, front-loaded with the key purpose, and no wasted words. Efficient and to the point.

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 optional parameter and no output schema, the description explains the index and its interpretation. It could mention the return format (single value or series), but overall it's fairly 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 for the single parameter 'days' is 100%, and the tool description adds no extra meaning beyond the schema. 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?

Description clearly states it retrieves the OFR Financial Stress Index, a daily indicator, and explains the meaning of values above 0. This is specific and distinct from sibling tools like 'get_economic_indicators' or 'get_fed_rates'.

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 assessing market stress but provides no explicit guidance on when to use this vs. alternatives, nor any exclusions. Context is clear but lacks comparative advice.

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 no annotations, the description carries full burden. It mentions that filings are 'filed before selling' and signal 'upcoming insider sales,' providing basic behavioral context. However, it does not disclose rate limits, authentication requirements, or what the response contains (e.g., full text or summary). The description is adequate but not fully 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 two sentences long, no redundant words, and front-loads the core purpose. Every sentence adds value: first sentence defines the tool, second sentence contrasts with Form 4 and explains usage context.

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 no output schema, the description could mention what the returned notices include (e.g., filing details, dates, amounts). However, it sufficiently explains the purpose and differentiation. It is mostly complete for a retrieval tool, but a brief note on response structure would enhance completeness.

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 baseline is 3. The description adds contextual meaning by framing parameters as filters for 'notices of proposed sale' and 'pre-trade intent,' but it does not add details beyond the schema's parameter descriptions. It meets the baseline but does not exceed.

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 gets SEC Form 144 filings, specifying the resource (Form 144) and the verb (Get). It distinguishes from sibling tools like 'get_insider_trades' (Form 4) by noting that Form 144 is pre-trade intent, while Form 4 is post-trade. The purpose is specific and 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 explains that Form 144 signals upcoming insider sales and complements Form 4, giving clear context on when to use this tool. However, it does not explicitly state when not to use it or list alternative tools for similar data, though it implies differentiation from 'get_insider_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?

With no annotations provided, the description carries the full burden; it adds interpretive context (e.g., high FTD may indicate naked short selling) but does not disclose behavioral traits like return format, pagination, or error handling. The schema covers parameters, but the description lacks operational details.

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 with two sentences: the first states the core purpose, and the second adds relevant interpretation. No unnecessary words; 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?

The tool has only two parameters and no output schema; the description is adequate for a simple data retrieval tool but lacks information about the output structure (e.g., time series, field explanations). For completeness, it could describe what the returned data 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 description coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the significance of FTD data (naked short selling, settlement issues), which is not in the schema. This contextual richness justifies a slight above-baseline score.

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 retrieves SEC Failures-to-Deliver (FTD) data for a stock, using the specific verb 'Get' and naming the resource. It distinguishes itself from sibling tools like get_stock_price or get_insider_trades by focusing on a niche data type.

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 this tool is used when FTD data is needed, but it does not explicitly mention when not to use it or provide alternatives. The context from sibling tools suggests a clear domain, but explicit exclusion or comparison is missing.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It fails to mention rate limits, data freshness, pagination behavior, or any side effects. As a read-only tool, it does not describe potential size limits or return structure beyond the schema.

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

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

Two sentences with clear, front-loaded purpose. No superfluous text; every sentence adds value. Appropriate length for the tool's simplicity.

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 should hint at return fields (e.g., dates, transaction types, volumes). It omits any mention of the data structure or output format. For a moderately complex tool (3 parameters, financial data), this leaves the agent uncertain about what to expect.

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 three parameters are documented in the schema (100% coverage), so the description adds minimal extra meaning. It mentions executive roles (CEO, CFO) but does not tie them to the `executive_cik` parameter or clarify the `limit` parameter's impact on results. 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 retrieves insider trades (SEC Form 4) for a company, naming specific insider types (CEO, CFO, directors) and the signal value. It effectively distinguishes from siblings like `get_congress_trades` (different domain) and `list_insider_traders` (lists insiders, not 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 when insider trade data is needed but lacks explicit guidance on when to use this tool versus alternatives such as `list_insider_traders` (which lists insiders) or `get_congress_trades` (congressional trades). No when-not-to-use or prerequisite conditions are stated.

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

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

No annotations provided, so description carries full burden. It discloses the quarterly SEC filing source and that returns are 'top positions' with quarter-over-quarter changes. However, it does not mention pagination behavior (page/limit parameters) or error handling for unrecognized institutions. Adds some behavioral context but not comprehensive.

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 redundancy. First sentence states purpose and source, second sentence details output. Front-loaded with essential information, 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?

For a tool with 3 parameters (1 required), no output schema, and no annotations, the description provides a solid overview. It explains the source, output, and institution resolution. It could mention pagination or the quarterly nature of data, but overall is sufficiently complete for effective use.

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 100% of parameters with descriptions. The description adds value by explaining the institution parameter accepts CIK, slug, or name (with automatic resolution), which the schema only mentions CIK and name. Also summarizes output fields (share counts, values, changes) providing context 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?

The description clearly states the verb (get), resource (stock holdings of an institutional investor), and source (SEC 13F filing). It distinguishes from siblings like get_stock_holders (holder of a specific stock) and list_institutions (list of institutions) by focusing on holdings of a given institution.

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 specifies the data source (latest SEC 13F filing) and return content (top positions, share counts, values, changes). It implicitly suggests use for institutional holdings data, but does not explicitly exclude cases or mention alternatives. Adequate but lacking 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?

No annotations are provided, so the description carries full burden. It discloses that the tool returns historical trend data over quarters, which indicates it is a read-only query. However, it does not mention any behavioral aspects like data source, update frequency, rate limits, or error handling. The description is adequate but not comprehensive.

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. The first sentence states purpose and scope, the second lists output content and use case. No filler words, every phrase adds value.

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 adequately explains what the tool does and what it returns, given the complexity of many sibling tools and no output schema. It covers the trend dimension over quarters. It could mention data source or update frequency, but for a data retrieval tool this is 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%, with both parameters already well-described in the schema (ticker symbol, quarters with default and bounds). The description adds 'over multiple quarters' which is redundant. It does not add new meaning beyond what the schema provides for the 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 specifies the verb 'Get' and resource 'institutional buying/selling activity trend for a stock over multiple quarters'. It explicitly states the output content (buying vs selling, net share changes, value flows) and distinguishes from siblings like get_institution_holdings by focusing on activity trend rather than snapshot.

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 a clear use case: 'useful for detecting accumulation or distribution patterns'. While it implies when to use (for trend analysis), it does not explicitly contrast with alternatives or state when not to use. However, the purpose alone offers sufficient guidance among the 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?

No annotations are provided, so the description carries the full burden. It identifies the data source (SEC filings) and indicates it's a read operation, but it does not disclose potential error conditions, authentication needs, rate limits, or behavior for invalid tickers. The listing of metrics is helpful but not comprehensive for 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?

The description is a single, well-structured sentence that places the purpose and key details upfront. Every part adds value without 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?

The description covers the type of data returned and the source. However, since there is no output schema, a brief note on the return format (e.g., array of periods) would improve completeness. Otherwise, it is adequate for a simple data retrieval tool with few parameters.

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 context by mentioning the financial statement items and the SEC source, which are not in the parameter descriptions. This enhances understanding beyond the 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 the tool retrieves quarterly or annual financial statements with a specific list of metrics (revenue, net income, EPS, etc.) from SEC filings. This verb+resource combination is distinct from siblings like get_stock_price or get_stock_profile.

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 (when you need financial statement data), but there is no explicit guidance on when to use this tool versus alternatives, nor any mention of prerequisites or limitations.

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

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

No annotations are provided, so the description carries the full burden. It states the tool is a read operation (shows data) but does not disclose any behavioral traits like idempotency, authentication needs, rate limits, pagination behavior, or whether it returns only top N holders. This is adequate but lacks depth.

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-loads the purpose, and contains no unnecessary words. It efficiently conveys the 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?

For a tool without an output schema, the description gives a reasonable expectation of the response content (institutional holders with changes). However, it does not specify the response structure (e.g., list, fields like holder name, shares, change percentage). This is slightly incomplete but still informative.

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% and the descriptions for page, limit, and ticker in the schema are clear and self-contained. The tool description does not add additional semantic information beyond the schema (e.g., example values or formatting). 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 clearly states the tool retrieves top institutional holders from SEC 13F filings, specifying the data source and what it includes (hedge funds, mutual funds, pension funds with quarter-over-quarter changes). This distinguishes it from sibling tools like get_crypto_holders or get_institution_holdings.

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 (to get institutional holders) but does not explicitly state when not to use it or compare to alternatives. No exclusions or alternative tool mentions are given.

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

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

No annotations are provided, so the description carries the full burden. It discloses two modes (summary and full series) and ties the series parameter to returning 'full daily price series', but does not detail what the summary contains or any other behavioral traits like rate limits or data range.

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: first states purpose, second explains the two modes. No clutter, front-loaded with key 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?

With no output schema, the description doesn't explain the return format of the summary or series. However, given the low complexity and clear parameter descriptions, it covers the essential usage. A slight gap remains for output details.

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%, but the description adds meaning by explaining that 'series' controls summary vs. full series and that 'limit' and 'period' apply when series=true. This goes beyond the schema's 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 clearly states 'Get historical daily stock prices (OHLC)' with a specific verb and resource. It distinguishes between summary and full series modes, and no sibling tool overlaps this functionality.

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 explains when to use the default vs. series=true ('for backtesting / charting'). It does not explicitly mention when not to use this tool or alternatives, but sibling tools cover different domains, making context sufficient.

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

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

No annotations provided, so description carries burden. It lists output contents but does not disclose data freshness, latency, side effects, or any behavioral traits beyond the implied read-only nature.

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, front-loaded with purpose, no extraneous words. Every part is informative 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?

No output schema exists, so description should ideally clarify return structure or potential variability. It lists many fields but doesn't indicate if the response is an object or if some fields may be absent. Adequate but not 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% for the single parameter 'ticker', with a clear description and examples. The tool description does not add additional meaning beyond what the schema already provides.

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 verb 'Get' and resource 'company's profile', listing specific data points (sector, market cap, etc.). Among siblings like get_stock_price and get_stock_financials, this distinguishes itself as a comprehensive profile tool.

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?

Implied usage for a broad overview, but no explicit guidance on when to use versus alternatives like get_stock_price or get_stock_financials. No when-not-to-use or additional context 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool returns daily yields for specific maturities, but does not mention the data source, freshness, or any rate limits. The behavior is mostly transparent for a straightforward data retrieval 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 with no extraneous information. It front-loads the core purpose and follows with a contextual usage hint, making it easy to parse quickly.

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 retrieval tool with one parameter and no output schema, the description is mostly complete. It explains the data and purpose, though it could briefly mention the return format (e.g., array of objects with date and yields).

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 with a clear description for the single 'days' parameter. The tool description adds no additional semantic information about the parameter beyond what the schema already states.

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 retrieves U.S. Treasury yield curve data, specifying the yield maturities (1-month to 30-year) and the use case (understanding interest rate environment and yield curve shape). It distinguishes itself from sibling tools like get_fed_rates (Fed funds) and get_economic_indicators (broad indicators) by focusing specifically on the yield curve.

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 interest rate analysis, but does not explicitly guide when to use this tool versus alternatives such as get_fed_rates or get_economic_indicators. No 'when not to use' or trade-offs are mentioned.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'recently traded' without defining recency, and does not mention pagination, rate limits, response format, or any restrictions. This leaves significant gaps for an agent invoking the tool.

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

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

The description is brief, consisting of two sentences that are front-loaded with the core purpose. Every sentence adds value, and there is no redundant or verbose language.

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 lack of output schema and annotations, the description should comprehensively explain what the tool returns, but it does not. It omits details like the fields in the response, how 'recently' is defined, and any pagination or sorting behavior. This leaves an agent uncertain about the tool's full capabilities.

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 two of four parameters (role and search) with descriptions. The tool description adds only a minor clarification for role, stating 'CEO only or all executives', but fails to provide any additional meaning for the 'page' and 'limit' parameters, which lack schema descriptions. The description does not compensate for the 50% schema coverage gap.

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 executives/insiders who recently traded company stock, with a filter by role. This verb-resource combination is specific enough, though it does not explicitly distinguish from the sibling tool 'get_insider_trades', which likely provides individual trade details.

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 mentions filtering by role and notes the tool is useful for finding notable insider activity, providing some context. However, it does not offer explicit guidance on when to use this tool versus alternatives like 'get_insider_trades' or 'list_institutions', nor does it 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?

No annotations provided, so the description must cover behavioral traits. It mentions 'top' but does not define criteria. It omits details on ordering, return fields, rate limits, or pagination behavior beyond what the schema provides.

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 of 15 words, front-loaded with the key purpose. No redundant 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?

Low complexity (3 params, no enums, no output schema). The description is partially complete but lacks definition of 'top institutions', output format, and ordering. It could provide more context given no 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%, so the baseline is 3. The description mentions 'search by name and pagination' which aligns with the params but adds no additional 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 verb 'List', the resource 'top institutional investors', and the source 'SEC 13F database'. It distinguishes itself from sibling tools like get_institution_holdings and list_insider_traders by focusing on listing institutions.

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 explicit guidance on when to use this tool vs alternatives. The description does not mention exclusions, prerequisites, 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. While 'search' implies a read-only operation, the description does not explicitly state that it is non-destructive, nor does it mention authentication requirements, rate limits, or return format. A score of 3 is appropriate as it conveys basic behavior but lacks explicit safety guarantees.

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 only two sentences, with no redundant information. The first sentence clearly states the action and scope, and the second provides immediate usage guidance. Every word is purposeful, earning a perfect score.

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 with full schema descriptions) and its role as a search tool to support other tools, the description adequately covers its purpose, usage, and scope. No output schema exists, but the description implies the tool returns identifiers, which is sufficient for its context. The guidance completes the picture.

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 both parameters having clear descriptions in the schema. The tool description adds context about the overall purpose but does not provide additional meaning beyond what the schema already states for the parameters. According to the rubric, with high schema coverage, the baseline is 3.

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 verb 'search' and the resources (institutions, stocks, insider traders) in the ko.io SEC database. It explains the tool's purpose: to find CIK numbers, tickers, or slugs for use with other tools, effectively distinguishing it from sibling tools that require specific identifiers.

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 this tool ('Use this first when you have a name but need the CIK number, ticker, or slug'), implying that it is the starting point before using other tools that require those identifiers. This provides clear context on when to choose this tool over 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?

With no annotations, the description carries full burden. It discloses key behaviors: returns a link, optionally an excerpt, never the whole file. It does not detail error handling or prerequisites but sufficiently explains the core 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?

Three sentences, no wasted words, front-loaded with purpose. Each sentence adds necessary 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?

Given the tool's simplicity and no output schema, the description is fairly complete. It explains the return type (link) and behavior. Minor omissions like error handling or excerpt truncation details prevent a perfect score.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the 'file' parameter comes from sec_get_filing_index and that omitting it gets the primary document. It also clarifies the 'include_excerpt' parameter behavior.

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 'Get a source document from a SEC filing' and specifies it returns a link and optionally an excerpt. It differentiates from sibling tools like sec_get_filing_index and sec_list_filings by noting that it never returns the whole file.

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 provides clear context on what to expect (link, optional excerpt) and instructs users to open the link for full content. However, it does not explicitly name alternative sibling tools or state when not to use this tool.

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

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

No annotations are provided, and the description does not disclose behavioral traits such as authentication requirements, rate limits, or error handling. It only describes the action without deeper context.

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, with two sentences that convey the purpose and a usage tip. No unnecessary 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 tool with no output schema, the description does not specify the return format (e.g., list of file names with metadata). It references the sibling tool but lacks completeness on expected 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 coverage is 100% with adequate descriptions for both parameters. The description adds no extra semantic 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 clearly states the tool enumerates every file in a single SEC filing and distinguishes it from the sibling tool sec_get_filing_document by indicating the next step.

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 usage context (enumerate files, then pass to sec_get_filing_document) but does not explicitly state when not to use or list 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool lists recent filings first and returns accession numbers, implying a read-only operation. It does not discuss permissions, rate limits, or error conditions, but for a list tool, the key behaviors are clear.

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-loading the main purpose and ordering. The second sentence provides prerequisite and downstream usage. Every word serves a purpose, making it highly concise.

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 5 parameters and no output schema, the description explains what is returned (accession numbers) and how to use them, including ordering. It does not mention pagination or default limit, but overall it provides sufficient context for an agent to use the tool effectively.

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 parameters are well-documented in the schema. The description adds context about ordering and output usage, but does not provide additional detail for specific parameters beyond what the schema offers. 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 explicitly states the tool lists SEC filings from EDGAR in reverse chronological order and outputs accession numbers. It clearly differentiates from sibling tools like sec_get_filing_index and sec_get_filing_document by focusing on listing vs. retrieval.

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 advises to provide a CIK and suggests using search or get_stock_profile to find it. It also explains that returned accession numbers are used for sec_get_filing_index and sec_get_filing_document, guiding the agent on workflow. However, it does not explicitly state when not to use this tool.

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