Server Quality Checklist

Tool Scores

• get_company_filingsA
  3.8/5.0
  Behavior4/5

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

  Annotations already declare this as read-only, idempotent, and non-destructive, lowering the burden. The description adds useful context by specifying the return metadata (form type, filing date, document links) and the optional form-type filter, going beyond what annotations provide.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the main verb and resource, with no filler or redundant details. Every word adds value.

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

  Completeness4/5

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

  The description covers the essential return information (metadata, form type, filing date, document links) since there is no output schema. It lacks pagination or limit details, but for a simple listing tool with only two parameters and strong annotations, it is sufficiently complete.

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

  Parameters3/5

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

  Schema coverage is 100% with both parameters clearly described in the schema. The description adds minimal new meaning beyond the schema—it repeats 'by CIK number' and provides additional form type examples (DEF 14A), but this does not significantly enhance the schema's existing parameter documentation.

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

  Purpose4/5

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

  The description clearly states the action ('Get recent SEC filings'), the resource (filings by CIK number), and the return scope (metadata including form type, filing date, document links). It is specific enough to distinguish from financial metric or company overview tools, though it does not explicitly differentiate from the sibling 'search_filings'.

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

  Usage Guidelines3/5

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

  The description gives clear context for use (by CIK number, optionally filtered by form type) but offers no explicit guidance on when to use this tool versus alternatives like 'search_filings'. No exclusions or when-not-to-use scenarios are mentioned.

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

• screen_stocksA
  3.9/5.0
  Behavior4/5

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

  Annotations already establish the tool as read-only, idempotent, non-destructive, and open-world. The description adds valuable behavioral context beyond those annotations: performance characteristics (fast vs. slow), the requirement for per-company API calls on deep filters, and coverage of 10,000+ companies. This helps the agent anticipate cost and latency.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with purpose, then performance guidance, then industry enumeration. Every sentence adds useful information with no filler, making it easy for an agent to parse quickly.

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

  Completeness4/5

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

  For a 5-parameter read-only screening tool with no output schema, the description covers the core purpose, filter options, performance trade-offs, and valid industry values. It does not explain how multiple filters combine or what happens when no filters are provided, but the schema's limit default mitigates that gap. Overall, it is solid but not exhaustive.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds meaning by mapping parameters to performance categories: exchange/nameContains are fast, industry/minHealthScore are slow and require API calls. It also lists acceptable industry values, though those are already in the schema, adding some redundancy.

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

  Purpose4/5

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

  The description opens with a specific verb and resource: 'Discover SEC-registered companies by exchange, industry, name, or financial health score.' This clearly states what the tool does. However, the sibling tool 'search_companies' likely overlaps in purpose, and the description does not explicitly distinguish screen_stocks from it, so it stops short of a 5.

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

  Usage Guidelines3/5

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

  The description gives clear within-tool usage guidance by separating 'Fast filters' from 'Deep filters' and warning that deep filters are slower due to per-company API calls. This implies when to prefer certain filters but does not say when to choose this tool over alternatives like search_companies, so guidance is implied rather than explicit.

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

• get_corporate_eventsA
  4/5.0
  Behavior4/5

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

  Annotations already declare read-only and idempotent behavior. The description adds valuable context about the return structure (SEC item number, human-readable label, category, significance level) and event coverage, going beyond what annotations provide.

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

  Conciseness5/5

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

  The description is two concise sentences: the first states purpose and coverage, the second lists output fields. It is front-loaded with the main verb and resource, with no unnecessary words.

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

  Completeness4/5

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

  There is no output schema, but the description explains what each event includes (SEC item number, label, category, significance). It also lists many event types. The term 'recent' is vague, but the limit parameter and example coverage make the tool understandable for a typical use case.

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

  Parameters3/5

  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 schema fully documents cik, limit, and significance, including the meaning of each significance level. The description adds no extra parameter details beyond the schema.

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

  Purpose5/5

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

  The description clearly states it retrieves recent 8-K corporate events for a company, with a specific verb and resource. It lists concrete event types (M&A, earnings, leadership changes, etc.), which differentiates it from sibling tools that fetch filings or financial data.

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

  Usage Guidelines3/5

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

  The description implies usage for getting corporate events but does not explicitly state when to use this tool versus alternatives like get_company_filings or search_filings. No exclusions or alternative guidance is provided.

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

• get_financial_summaryA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, etc. The description goes beyond these by adding meaningful behavioral context: values are deduplicated, drawn from the most recent annual filing, and include computed ratios. This provides useful data-source and processing transparency without contradicting annotations.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose, then a concrete list of returned fields and data quality notes. Every sentence contributes value, with no fluff or repetition.

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

  Completeness4/5

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

  Given no output schema, the description enumerates raw values and computed ratios, and specifies data source and deduplication behavior. It is reasonably complete, but could have mentioned units (e.g., USD) or filing date specifics; still, it covers the essential context for understanding the tool's output.

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

  Parameters3/5

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

  Schema coverage is 100% (only 'cik' is described as 'Company CIK number'). The description adds no extra detail about the parameter, such as format or examples. Since the schema fully documents the parameter, the baseline score of 3 applies without additional compensation.

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

  Purpose5/5

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

  The description uses the specific verb 'Get' with the resource 'financial summary' and explicitly states it includes computed ratios. It clearly distinguishes from sibling tools like get_financial_metric (likely a single metric) and analyze_financials (deeper analysis) by positioning itself as a comprehensive snapshot.

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

  Usage Guidelines3/5

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

  The description implies use for a broad financial overview but does not explicitly mention when to use this tool over siblings or provide exclusionary guidance. There is no comparison to get_financial_metric or analyze_financials, leaving usage context implicit rather than stated.

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

• search_filingsA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context about pagination ('use offset to fetch subsequent pages') and optional filtering by form type/date range, going beyond annotation data 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.

  Conciseness5/5

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

  The description is three sentences, front-loaded with the core purpose, and every sentence earns its place. No filler or redundant information; it efficiently covers scope, filters, and pagination.

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

  Completeness4/5

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

  For a search tool with no output schema, the description covers the main functionality, filters, and pagination. It does not describe the return format or fields, which would be helpful, but the overall picture is reasonably complete given the schema covers parameters and annotations cover safety.

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

  Parameters3/5

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

  Schema description coverage is 100%, with all six parameters documented in the schema. The description reinforces the pagination behavior (offset) but does not add significant new meaning beyond the schema, so the baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool performs full-text search across all SEC EDGAR filings, with a specific verb ('search') and resource. It distinguishes itself from siblings like get_company_filings (company-specific) and search_companies (company search) by emphasizing 'all SEC EDGAR filings.'

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

  Usage Guidelines3/5

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

  The description implies use for broad keyword search across all filings and mentions optional filters, but it does not explicitly state when to use this tool versus alternatives or name sibling tools. Usage context is clear but exclusions/alternatives are left to inference.

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

• get_stock_quoteA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context beyond the annotations by stating the data source (Finnhub), the live (non-cached) nature, and the FINNHUB_API_KEY prerequisite, which helps the agent anticipate runtime needs and freshness.

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

  Conciseness5/5

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

  The description is three concise, front-loaded sentences: purpose, return fields, and key behavioral context. Every sentence earns its place with no waste or redundancy.

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

  Completeness5/5

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

  For a simple one-parameter tool with strong annotations and no output schema, the description is highly complete. It covers the purpose, return fields, data source, freshness, and a required environment variable, leaving no critical gaps for an agent to select and invoke the tool.

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

  Parameters3/5

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

  The schema already provides 100% coverage for the 'symbol' parameter with a clear description and examples. The tool description does not add additional semantic meaning beyond what the schema provides, 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.

  Purpose5/5

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

  The description clearly states the action ('Get') and the specific resource ('real-time stock price quote'), and enumerates the exact data fields returned. It distinguishes itself from sibling tools like get_financial_metric or get_company_overview by focusing on the quote context and live data.

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

  Usage Guidelines3/5

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

  The description implies usage for real-time quotes by emphasizing 'live (not cached)' and listing price fields, but it does not explicitly state when to use this tool versus alternatives like get_financial_metric or get_company_overview. No exclusions or alternative tools are mentioned.

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

• analyze_financialsA
  4.2/5.0
  Behavior4/5

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

  The annotations already reveal read-only and non-destructive behavior, so the description adds value by explaining the interpretative nature of the tool—computing ratios, scores, and trend detection. This goes beyond the safety profile provided by annotations, enhancing the agent's understanding of what to expect.

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

  Conciseness5/5

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

  The description is two sentences long, packed with specific, relevant details and a clear differentiator. Every phrase adds value, and the structure is front-loaded with the most important information, making it efficient and easy to parse.

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

  Completeness4/5

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

  Since there is no output schema, the description carries the burden of explaining return values, and it does so by listing concrete metrics and the composite health grade. It does not detail the exact structure or mention potential raw data inclusion, but for a single-parameter read-only tool, this is largely sufficient.

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

  Parameters3/5

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

  The input schema fully documents the single parameter (cik) with 100% coverage, so the description does not need to add parameter details. The description does not elaborate on cik beyond the schema, 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.

  Purpose5/5

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

  The description clearly states the tool's purpose with a specific verb ('analyze') and resource ('company financials'), while listing concrete outputs such as profit margins, ROE, ROA, growth metrics, and a health grade. This distinguishes it from sibling tools like get_financial_metric, which likely return single raw metrics.

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

  Usage Guidelines4/5

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

  The description implies that this tool is for comprehensive, interpreted analysis rather than raw data, as stated by 'This goes beyond raw data — it interprets the numbers.' However, it does not explicitly name alternative tools or state exclusions, providing clear context but not full when/when-not guidance.

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

• get_economic_dataA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds context by stating that it returns 'recent data points with dates and values,' offering a behavioral trait (response shape) not covered by annotations. 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.

  Conciseness5/5

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

  Three concise sentences: the first states purpose, the second describes return content, and the third provides valuable examples. Every sentence earns its place with no redundancy or filler.

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

  Completeness4/5

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

  Given full schema coverage, strong annotations, and no output schema, the description provides enough context by mentioning date/value pairs and common series. It does not define 'recent' when startDate/endDate are omitted, but the overall tool is straightforward and the description is adequate for a data retrieval tool.

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

  Parameters4/5

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

  Schema coverage is 100% since every parameter has a description. The description enhances this by listing common series IDs (GDP, CPIAUCSL, UNRATE, etc.) and their meanings, which helps the agent select appropriate values for seriesId.

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

  Purpose5/5

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

  The description specifies 'Get time series observations for a FRED economic data series,' which clearly names the verb and resource. It distinguishes itself from siblings like get_stock_quote and search_economic_data by focusing on FRED series and listing specific examples.

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

  Usage Guidelines3/5

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

  The description implies usage when a FRED series ID is needed and even provides common series IDs, but it does not explicitly state when to use this tool versus search_economic_data or other alternatives. There is no explicit when-not guidance, so it remains implied rather than direct.

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

• get_insider_transactionsA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds valuable context beyond annotations: the specific return fields, explanation of transaction codes (P, S, M, A, G, F), and the requirement for the FINNHUB_API_KEY environment variable. 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.

  Conciseness5/5

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

  The description is four sentences, front-loaded with purpose, followed by return fields, code explanations, and a prerequisite. Every sentence adds value with no redundancy or fluff.

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

  Completeness4/5

  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, no output schema), the description adequately covers return fields and essential context like the API key requirement. It could mention the temporal scope of 'recent' more precisely, but overall it is complete enough for safe invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, as the only parameter 'symbol' has a clear description. The tool's description does not add extra meaning about the parameter beyond what the schema already provides, 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.

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb and resource: 'Get recent insider trading activity for a company.' It also enumerates the return fields (insider names, share counts, dates, prices, codes), making it distinct from sibling tools like get_company_filings or get_stock_quote.

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

  Usage Guidelines4/5

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

  The description implies usage for recent insider transactions via 'recent insider trading activity,' but it does not explicitly contrast with alternatives or state when not to use it. Clear context is provided, but no exclusions or sibling references are made.

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

• search_companiesA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnly=true, openWorld=true, idempotent=true, and destructive=false. The description adds value by disclosing the return content (company names, tickers, CIK numbers) and the purpose of CIK, complementing the annotation coverage without contradiction.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the action verb, and every sentence contributes meaningful information. There is no fluff or unnecessary repetition.

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

  Completeness4/5

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

  Given the low complexity (one parameter), no output schema, and rich annotations, the description adequately explains what the tool does and what it returns. It also gives context on using the CIK for downstream lookups, which helps the agent understand the tool's role in a workflow.

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

  Parameters3/5

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

  The schema description covers 100% of parameters, with 'query' described as 'Company name or ticker symbol to search for'. The description essentially restates this, providing no additional semantic detail 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.

  Purpose5/5

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

  The description clearly states the tool's purpose: searching for SEC-registered companies by name or ticker. It specifies the return values (company names, tickers, CIK numbers) and distinguishes it from sibling tools like search_filings which search filings rather than companies.

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

  Usage Guidelines4/5

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

  The description provides contextual guidance by stating to use the CIK for subsequent filing and financial data lookups, implying this tool is for company identification. It does not explicitly name alternatives or when not to use it, but the context is clear enough for selection.

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

• search_economic_dataA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare read-only, idempotent, non-destructive behavior. The description adds context about the breadth of FRED (800,000+ series from 100+ sources) and discloses the return format (series IDs), which is especially useful given the lack of an output schema.

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

  Conciseness5/5

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

  The description is concise, consisting of three sentences that are front-loaded with the core action. It includes essential context (database scope, examples, return usage) without any extraneous content.

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

  Completeness4/5

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

  For a simple single-parameter search tool with rich annotations, the description covers the purpose, database, and return value, forming a complete picture. It could mention pagination or result limits, but these are not critical for understanding how to use the tool.

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

  Parameters3/5

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

  The input schema has 100% coverage for the single 'query' parameter, including example terms. The description does not add any additional parameter-level details beyond what the schema already provides, so the baseline score of 3 applies.

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

  Purpose5/5

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

  The description clearly states that the tool searches the FRED database for economic data series, using the specific verb 'search' and resource 'FRED database'. It distinguishes from siblings like search_companies by explicitly targeting economic data and mentions returning series IDs for use with get_economic_data.

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

  Usage Guidelines4/5

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

  The description provides clear context by specifying the FRED database and indicating the workflow of using returned series IDs with get_economic_data. It doesn't explicitly name alternatives or exclusions, but the focus on economic data makes the intended use self-evident.

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

• get_company_overviewA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds a critical auth requirement (FINNHUB_API_KEY environment variable). It also communicates the output structure (profile, market metrics, peer companies) without contradicting annotations.

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

  Conciseness5/5

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

  Three focused sentences: purpose, return fields, and context/auth. Every sentence carries unique information, no redundancy or fluff.

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

  Completeness5/5

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

  For a single-parameter read tool with comprehensive annotations, the description fully covers purpose, output, and auth requirements. It clearly explains what data to expect and where it fits among sibling tools.

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

  Parameters3/5

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

  Schema fully documents the single 'symbol' parameter with examples, achieving 100% coverage. The description does not add any parameter-specific semantics beyond what the schema already provides, so baseline 3 applies.

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

  Purpose5/5

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

  Description opens with 'Get a comprehensive company overview' and enumerates specific data points (market cap, PE ratio, beta, 52-week range, EPS, dividend yield, peer tickers). It also distinguishes itself as the 'market overlay' versus SEC fundamental data, setting it apart from sibling tools.

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

  Usage Guidelines4/5

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

  Provides clear context by positioning the tool as the 'market overlay' complementing SEC fundamental data, implying it should be used for market metrics rather than filings. 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.

• get_financial_metricA
  4.3/5.0
  Behavior4/5

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

  Beyond the annotations (read-only, idempotent), the description discloses important behaviors: automatic alias resolution, deduplication, and one-value-per-period output. This adds value beyond the structured hints.

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

  Conciseness4/5

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

  The description is front-loaded with the core purpose and then gives relevant details. The list of available concepts is long but directly useful for parameter selection. No redundant or filler sentences.

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

  Completeness4/5

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

  Given there is no output schema, the description describes the return shape (one-per-period values, trend analysis) but could be more explicit about the exact format. Still, the combination of annotations, schema, and description covers the essential usage context sufficiently.

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

  Parameters4/5

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

  The input schema already covers all parameters (100% coverage), so the baseline is 3. The description enriches this by listing the available friendly names and explaining that raw XBRL tags are accepted, which goes beyond the schema's generic placeholder text.

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

  Purpose5/5

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

  The description clearly states the tool fetches historical values of a financial metric for a company, explicitly mentioning deduplication and alias resolution. This distinguishes it from siblings like get_financial_summary or analyze_financials, which have different scopes.

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

  Usage Guidelines4/5

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

  The description implies the tool is used when you need a single metric's historical time series with clean, deduplicated data. It does not explicitly compare with alternative tools, but the purpose is clear enough to infer appropriate usage.

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

• compare_companiesA
  4.4/5.0
  Behavior5/5

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

  Beyond the annotations (readOnly, idempotent, etc.), the description discloses significant behavioral traits: normalization of metrics, deduplication of data, reliance on annual filings, and the generation of per-category winners. These details help the agent anticipate output characteristics and data provenance, exceeding the annotation-only baseline.

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

  Conciseness5/5

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

  The description is four short sentences, each adding value: core purpose, metrics compared, output behavior, and data source. It is front-loaded with the main verb and resource, and every sentence earns its place without redundancy.

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

  Completeness4/5

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

  Given the simple parameter schema, helpful annotations, and absence of an output schema, the description adequately conveys the tool's purpose, the metrics involved, and data characteristics. However, it does not specify the returned data structure or format, which would be valuable for an agent expecting to parse the response. Thus, it is complete enough but not fully comprehensive.

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

  Parameters3/5

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

  The schema already fully describes the single parameter 'ciks' with min/max constraints and a clear description. The tool description adds no new meaning beyond echoing the 2-5 company range, so the score remains at the baseline of 3 for high schema coverage.

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

  Purpose5/5

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

  The description clearly states a specific verb ('compares') and resource ('companies'), with a defined scope of 2-5 companies and enumerated metric categories. It distinguishes itself from sibling tools like get_financial_metric by emphasizing multi-company side-by-side comparison and winner identification.

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

  Usage Guidelines4/5

  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 this tool (comparing multiple companies with normalized financial metrics) and implies exclusions via 'annual filings' and deduplication. However, it does not explicitly name alternatives or state when-not-to-use cases, so it falls 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.

• get_company_facts_summaryA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and side effects. The description adds behavioral context by stating it returns a compact index with specific fields and explicitly says 'NOT the full time series,' which is a crucial limitation beyond the annotations. It could mention pagination or rate limits, but what it discloses is valuable and goes beyond the structured fields.

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

  Conciseness5/5

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

  The description is just two sentences, front-loaded with the core function, then the return contents, a key clarification, and usage direction. Every sentence earns its place with no redundancy or clutter. It is highly scannable and efficient.

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

  Completeness5/5

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

  For a simple discovery tool with two well-documented parameters and rich annotations, the description is complete. It explains what the tool returns, what it does NOT return, and how to proceed for more detail. The absence of an output schema is compensated by a clear description of the return shape. No critical information is missing.

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

  Parameters3/5

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

  Schema coverage is 100%, as both 'cik' and 'limit' have descriptions. The description does not add new meaning to the parameters beyond what the schema already provides. The 'compact index' phrase implies the limit parameter, but the schema already explains 'Max concepts to return.' Thus the baseline of 3 applies.

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

  Purpose5/5

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

  The description uses a specific verb ('Get') with a clear resource ('compact index of all available XBRL financial data for a company'). It explicitly states the output scope (concept names, latest values, data point counts) and distinguishes itself from sibling get_financial_metric by noting it is NOT the full time series. This fully clarifies the tool's purpose.

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

  Usage Guidelines5/5

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

  The description provides explicit usage guidance: 'Use this to discover what data is available, then use get_financial_metric for details.' This names a specific alternative and spells out the intended workflow, which is exactly the kind of when-to-use-versus-alternative signal expected.

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

• get_market_newsA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare the operation as read-only and non-destructive. The description adds important behavioral context by disclosing the FINNHUB_API_KEY environment variable requirement and explaining the default vs symbol-based behavior, which goes beyond what annotations provide.

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

  Conciseness5/5

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

  The description is three concise sentences: what it does, the two modes, and the API key requirement. No wasted words, and the most important information is front-loaded.

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

  Completeness5/5

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

  For a simple, read-only news tool, the description covers the essential aspects: purpose, parameter usage, categories, and authentication requirement. No output schema exists, but 'headlines' sufficiently sets expectations for return type. Annotations provide safety context, making this complete.

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

  Parameters4/5

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

  Schema coverage is 100% with both parameters described, so baseline is 3. The description adds extra value by clarifying that category is only relevant when symbol is omitted and explicitly mapping categories to general news, reinforcing the parameter semantics.

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

  Purpose5/5

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

  The description clearly states the tool retrieves latest financial news headlines, distinguishing between general market news and company-specific news via symbol. It is specific and distinct from sibling tools which focus on filings, metrics, or other non-news data.

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

  Usage Guidelines4/5

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

  The description provides clear context on when to use the default general news mode versus providing a symbol for company-specific news, and lists valid categories. It does not explicitly compare to sibling tools, but the tool's niche is well-defined and no alternatives for news exist among siblings.

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