Drillr — The financial MCP for AI agents

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds valuable behavioral context by explaining the return format (structured list with context snippets), market coverage, and the market parameter behavior (omit or [] for all, order no priority). It doesn't mention pagination or error conditions, but that's acceptable given the read-only nature and no 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.

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

The description is well-structured and front-loaded with the primary use and alternative. Each sentence serves a purpose: differentiating from run_sql, describing the knowledge base, coverage, parameter behavior, example, and a final constraint. It avoids fluff and is easy to scan.

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

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

Given the tool's moderate complexity (2 parameters, no output schema), the description covers all essential aspects: purpose, usage, parameter details, return type, and alternatives. It explains the return format sufficiently for an agent to understand what to expect, and the market filtering is thoroughly documented.

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%, providing baseline of 3. The description adds extra meaning by giving a natural-language example, specifying lowercase market values, and clarifying that list order doesn't set priority—details that go beyond the schema's own description. This enhances the agent's understanding of how to construct valid inputs.

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 is for qualitative company discovery, naming the resource (company knowledge base) and its scope (industry, business model, supply chain, competitors, management). It explicitly differentiates from sibling tool run_sql for numerical screening, making the purpose 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?

Provides explicit when-to-use (qualitative discovery) and when-not-to-use (numerical screening → use run_sql on company_snapshot). Also states the tool is ONLY for finding a list of companies by description, clearly separating it from other 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?

Annotations already provide readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by clarifying the output content (column definitions with name, type, description) and its role as a prerequisite to run_sql. No contradiction with annotations.

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

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

Two short, front-loaded sentences with no filler. The usage recommendation comes first, followed by a precise statement of what the tool returns.

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

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

For a simple read-only schema lookup with one parameter and a complete enum of tables, the description adequately covers return fields and timing. It could mention error or edge-case behavior, but those are not essential given the tool's simplicity.

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

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

Schema description coverage is 0%, so the description needed to compensate, but it only vaguely refers to 'a data table.' The enum in the schema lists the valid table names, but the description adds little meaning beyond what the parameter name already implies.

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

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

The description uses a specific verb ('Look up') with a clear resource ('column definitions') and even states what is returned ('name, type, description'). The 'Use BEFORE run_sql' clause helps distinguish this tool from the primary query sibling.

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 explicitly says when to use the tool ('BEFORE run_sql' when unsure which columns a table has) and names run_sql as the alternative. It does not fully discuss when not to use it or contrast it with list_tables, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds batching limit (up to 5 categories), behavior when omitted or 'all', and what is returned (name, purpose, column names). No contradiction.

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

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

Well-structured with purpose first, then details, usage guidance, and categories. Slightly long but every sentence serves a purpose. Could be slightly more concise but effective.

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

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

No output schema, but description covers what is returned (name, purpose, column names) and directs to get_table_schema for types. Includes batching and categories. Complete for a listing tool.

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

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

Schema coverage is 100% with enum list and description. Description reinforces the categories list and adds batching instructions and behavior when omitted. Adds value beyond schema, so slightly above baseline 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?

Clearly states 'List alternative-data tables under the given categories' with specific verb and resource. Distinguishes from siblings like get_table_schema and run_sql by explaining what each returns and when to use them.

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

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

Explicitly says 'Use this BEFORE run_sql when you want to explore alt-data' and mentions get_table_schema for more details. Provides clear when-to-use and alternatives.

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

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

Beyond annotations (readOnlyHint=true), the description details the output format (Markdown with Stories, Events, Claims tables), explains how stories are truncated, and describes columns like sources and time spans. It fully discloses behavioral traits without contradiction.

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

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

The description is well-structured with a front-loaded purpose, followed by filter details, output explanation, and parameter constraints. It is slightly verbose but every sentence adds useful information; could be more terse without losing clarity.

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 complexity (8 parameters, no output schema), the description is complete: covers input requirements, market coverage, ticker formats, output structure, and edge cases (e.g., dropped stories). It adequately compensates for the lack of an output schema.

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

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

With 100% schema coverage, the baseline is 3, but the description adds extra value by explaining ticker exchange suffixes, OR behavior for multiple tickers, and restrictions on search_type=claims. This goes beyond the schema 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 the tool is for news, events, and statements about companies/themes/markets. It is specific about the resource (news) and the action (search), but does not explicitly differentiate from sibling tools like company_search or ticker_lookup, though the context implies a distinct purpose.

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

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

The description provides clear usage context, including required parameter combinations (e.g., at least one of query/theme/ticker/since/until) and when search_type=claims is invalid with theme. However, it does not explicitly state when not to use this tool or recommend 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?

The description discloses key behaviors beyond the annotations: SELECT-only restriction, no CTE support, period column type constraints (TEXT, not date, with specific comparison syntax), and ticker filtering requirements. It aligns with readOnlyHint=true and destructiveHint=false, and adds the nuance that empty results may not be findings without schema verification.

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 long but well-structured with clear sections: hard rules, coverage, tables by domain. It front-loads the most critical constraints (hard rules) before listing tables. Each section earns its place; the table listing is verbose but necessary for a query tool with heterogeneous tables. Slightly excessive length for a description, but effective organization prevents wasted space.

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 is thorough for a tool with one parameter and no output schema: it explains coverage (US, Japan, HK, China, Korea), table categories, and query constraints. It references sibling tools (get_table_schema, list_tables) to fill gaps. However, it lacks details on return format (e.g., row limits, pagination, error handling for invalid SQL), which would be useful for a raw SQL 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?

The input schema covers the 'sql' parameter 100% with a description 'PostgreSQL SELECT query'. The description adds value by providing example query patterns (ticker IN ('AAPL','MSFT'), ticker NOT LIKE '%-%' for screening) and table-specific usage notes, which are not in the schema. However, since the schema already adequately describes the parameter, the baseline is 3, with the description's examples lifting it to 4.

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 specifies 'PostgreSQL SELECT over financial / market / alt-data tables — returns structured rows', giving a clear verb (SELECT), resource (PostgreSQL tables), and scope (financial/market/alt-data). It distinguishes itself from sibling tools like get_table_schema, list_tables, and search tools by explicitly focusing on direct SQL querying over the database tables.

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

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

Provides explicit when-to-use guidance: it tells the agent to call get_table_schema before treating empty results as findings, lists tables by domain, and specifies hard rules for query construction (e.g., no CTEs, period columns as TEXT, filter by ticker). This clearly signals when to use this tool versus alternatives like list_tables or get_table_schema.

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

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

The description discloses return structure (summary + up to 50 filings with fields), the default filtering behavior, and what types are included/excluded. This goes well beyond the annotations (readOnlyHint true, destructiveHint false) and provides meaningful context about operational behavior and output limits.

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 well-structured: purpose first, then return format, then filter semantics. It is slightly lengthy, but every sentence carries necessary information—no fluff or redundancy. The clear bullet-like layout of returned fields and filter options improves scannability.

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 there is no output schema, the description fully compensates by listing the exact fields returned and the summary content. It covers purpose, usage, output, and filter semantics, making it complete for an agent to select and invoke the tool correctly in most cases.

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 significant semantics beyond the schema: it explains the default filing_types behavior, how to override with [], and the explicit allowlist option. It also specifies ticker examples in the schema, and the description reinforces the role of the ticker parameter in context.

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

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

The description clearly states the tool's function: 'List indexed SEC filings for a given ticker with a summary header.' It uses a specific verb ('List') and identifies the resource (SEC filings for a ticker), and explicitly distinguishes it from the sibling tool sec_report_search ('For the actual content use sec_report_search instead').

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 explicit guidance on when to use this tool ('before searching content') and names the alternative for content search. It also explains the filing_types filter behavior with clear options (omit, [], explicit allowlist), which is practical usage guidance beyond simple when-to-use.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: coverage of markets, that it returns matching passages, language limitations (Korea filings in Korean), and recommended query phrasing. No contradictions with annotations.

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

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

The description is long but densely packed with essential information, structured into clear sections (Coverage, Parameters, Scope, Section targets). Every sentence adds value, and the front-loading of use cases ensures the agent quickly understands when to invoke it.

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 complexity (6 parameters, multiple jurisdictions, no output schema), the description is remarkably complete. It covers all parameters, market-specific ticker formats, filing type mappings, and section navigation tips. An agent has everything needed to select and call the tool correctly.

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

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

Schema description coverage is only 67%, but the description elaborates on every parameter, including detailed filing type codes for each market, query formatting examples, and default behavior for top_k. This goes far beyond the schema's terse 'Search query' and 'Stock ticker' 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 it performs "Semantic search over the full text of company-filed reports; returns matching passages." It uses a specific verb (search) and resource (company filings), and explicitly contrasts itself with run_sql for financial numbers, distinguishing it from siblings.

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 given: "Use when you need narrative content from company filings... For consolidated financial numbers use run_sql on financial_statements instead." It also specifies negative scope (not institutional filings) and provides per-market filing type guidance, making it clear when to use this tool vs 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?

The description adds significant behavioral details beyond the annotations: ranking logic ('prefix-hit first, then name length'), result limit ('up to 5 matches'), and market suffix formatting (e.g., Japan `.T`, Hong Kong 00700.HK). This goes beyond the readOnlyHint/destructiveHint annotations to explain real output 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?

The description is well-structured: a one-sentence purpose, a concise input breakdown, and an output explanation. Every sentence adds necessary information—no filler, no repetition of schema details. It is front-loaded with the most important instruction ('Use this FIRST') and remains compact.

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 is a simple lookup with no output schema, the description covers all essential aspects: what it accepts, what it returns, ranking behavior, and output format. It even explains market suffixes which is crucial for interpreting results. The description is complete for an agent to use the tool correctly.

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

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

The schema already documents both parameters fully (100% coverage), including examples and market enum. The description adds value with concrete examples (e.g., 'Apple', '苹果', 'OpenAI') and clarifies that the market parameter can be omitted for global search. Since the schema carries most of the semantic weight, the description's extra examples and emphasis on the search scope earn a 4, not a 5.

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

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

The description uses a specific verb 'Resolve' with a clear resource ('company name, brand, or ticker substring to canonical ticker(s)'). It distinguishes itself from siblings by stating it is the first step before ticker-keyed tools, and it defines the scope of the query (company name/brand/nickname), making its purpose 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 explicitly states when to use the tool: 'Use this FIRST when the user mentions a company by name/brand/nickname before running any ticker-keyed tool.' This also implies when not to use it (when you already have a canonical ticker), and names the alternative category (ticker-keyed tools). This is clear, actionable guidance.

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