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. The description adds that the tool returns a structured list with context snippets, and specifies coverage (US, Japan, Hong Kong, China A-shares). 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?

The description is well-structured with a bolded usage note, but some redundancy (e.g., repetition of market instructions in both the description and the schema). Still, it is efficient and front-loaded with key info.

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 adequately explains return value (structured list with context snippets). It covers parameters, usage, coverage, and provides an example. The tool is straightforward and the description is 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 is 100%. The description adds meaningful context beyond the schema: explains that 'query' is a natural-language description and 'market' accepts a single value or list, with guidance on omission and that order doesn't set priority.

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, specifies the verb (search/discovery) and resource (companies), and lists searchable attributes (industry, business model, etc.). It also distinguishes from sibling tool 'run_sql' for numerical screening.

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

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

Explicitly states when to use (qualitative discovery) and when not to use (numerical screening, use run_sql instead). Provides detailed instructions for the market filter, including accepted values and behavior when omitted.

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 indicate readOnlyHint=true and destructiveHint=false, so the description's addition of coverage limitations and conversion mode details adds value without contradiction. The tool is fully transparent about its behavior and constraints.

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?

Four sentences with no waste: first states purpose, second gives coverage warning, third and fourth explain dual usage modes. Front-loaded with key purpose and action.

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 covers the tool's functionality and limitations. With no output schema, it could briefly mention the expected output format (e.g., period dates), but the dual-mode explanation is sufficient for an agent to use it 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 100%, so parameters are already well-documented. The description adds value by explaining which parameters are used for forward vs reverse conversion, and the yyyy_mm pattern. This slightly exceeds the baseline of 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 tool converts between fiscal year/quarter and calendar months for a ticker, specifically for filtering period_end columns. It distinguishes itself from sibling tools by focusing on this unique conversion 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?

Explicitly says when to use ('before filtering period_end columns') and provides coverage warnings (primarily US, sparse JP/HK, no China A-shares). It also explains the forward and reverse directions with required parameters, guiding 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's addition of 'Look up column definitions' adds minor behavioral context. It does not elaborate on access restrictions, rate limits, or error behavior, which is acceptable given the annotation coverage.

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: the first gives a usage guideline, the second states the output. No wasted words, front-loaded with key information. Highly efficient.

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

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

Given the simple tool (one enum param, annotations present, no output schema), the description covers purpose, usage context, and output. It does not mention error handling or the sibling 'list_tables' for discovering available tables, but this is minor for a straightforward lookup 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 0%, but the single parameter 'table_name' is self-explanatory through its enum list. The description adds context by mentioning 'data table', but it does not detail parameter format or constraints beyond what the schema provides. Adequate but not exceptional.

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 looks up column definitions (name, type, description) for a data table, with a specific verb and resource. It also distinguishes from the sibling 'run_sql' by recommending use before executing SQL when unsure of columns.

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 guides when to use: 'Use BEFORE run_sql when you're unsure which columns a table has.' This provides clear context and links to a sibling tool. However, it does not mention when not to use or other 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?

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?

Beyond the readOnlyHint=true and destructiveHint=false annotations, the description discloses key behavioral constraints: SELECT-only (no CTEs), period columns as TEXT requiring string comparison, mandatory ticker filtering for structured tables, and coverage limitations across markets. It also warns that empty results may be due to schema variation, telling agents to call get_table_schema first. This adds substantial context beyond the 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?

Despite its length, the description is tightly structured and front-loaded: purpose first, then hard rules, then coverage, then table domains. Every sentence conveys necessary information—no filler. The strategic organization makes the volume of details easily scannable and actionable.

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 accepts arbitrary SQL over a large schema, the description is remarkably complete. It covers syntax restrictions, data types, ticker conventions, market coverage, table partitioning by domain, and explicitly defers schema details to get_table_schema and list_tables. Without an output schema, it still clarifies that results are structured rows, which is sufficient for an agent to understand expected behavior.

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

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

The sole parameter 'sql' is described in the schema as 'PostgreSQL SELECT query', but the description greatly expands this by providing hard syntax rules, examples of valid ticker formats, and domain-specific table guidance. This goes far beyond the schema's minimal description, offering essential semantic context for writing correct queries.

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 opening line clearly states the tool executes PostgreSQL SELECT queries over specific financial/market/alt-data tables and returns structured rows. This specific verb+resource combination distinguishes it from sibling tools like news_search or sec_report_search, which handle unstructured or document data.

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 detailed usage context: hard rules for query construction, required filters for certain tables, and explicit pointers to sibling tools (get_table_schema, list_tables) for schema exploration and discovery of specialized tables. This effectively guides when to use run_sql vs. when to use alternatives for schema discovery.

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, so safety is clear. The description adds detailed behavioral context: returns a summary with period coverage and per-type counts, plus a table of up to 50 filings with specific columns. It explains the default filtering logic for filing_types, which goes well beyond 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 well-structured: first sentence states purpose and usage guidance, then enumerates return structure, finally explains parameter behavior. Every sentence adds value with no redundancy or filler.

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

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

For a read-only list tool with 2 parameters and no output schema, the description covers return format, parameter behavior, and inter-tool guidance. It provides all necessary information for correct invocation, including edge cases for filing_types.

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%, but the description adds significant meaning: it explains the default behavior of filing_types (omit for main reports, pass [] for all, pass allowlist to override), and how to obtain valid values from a prior unfiltered call. This enriches the schema significantly.

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

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

The description clearly states the tool's purpose: 'List indexed SEC filings for a given ticker with a summary header.' It distinguishes itself from the sibling sec_report_search by specifying its use for discovery before content 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 explicitly says when to use this tool ('discover which SEC filings exist for a ticker before searching content') and when to use the alternative ('For the actual content use sec_report_search instead'). It also explains how to use the filing_types parameter with three distinct options.

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

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

Annotations declare read-only and non-destructive. Description adds that it's semantic search returning matching passages, covers specific markets and filing types, and explains scope limitations. 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 front-loaded usage scenario. Every sentence adds value, no redundancy. Efficiently covers purpose, parameters, coverage, and alternatives without excess.

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?

Despite no output schema, description explains return type (matching passages). Covers all parameters, usage context, market coverage, limitations (e.g., no institutional filings), and provides guidance for common search targets.

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?

Description adds significant meaning beyond schema: query phrasing advice, ticker format details per market, exhaustive filing type lists with codes, period format clarification, and top_k context. Compensates for 67% schema coverage.

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

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

The description clearly states the tool performs semantic search over company-filed reports for narrative content. It distinguishes from sibling tools like run_sql (financial numbers) and insider_and_institution_activities (institutional filings).

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

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

Explicitly states when to use (narrative content from filings) and when not to (consolidated financial numbers, institutional filings), and provides alternatives using run_sql and other 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 indicate readOnlyHint=true and destructiveHint=false. The description additionally explains ranking logic (prefix-hit first, name length) and market suffix conventions, which are beyond annotation scope.

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: two short paragraphs. The first sentence front-loads the purpose, then provides usage context, then parameter details. 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?

Despite no output schema, the description fully explains the return value: up to 5 matches, ranking method, and market suffix formats. All input parameters are covered with examples and behavior. No gaps.

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

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

Schema description coverage is 100%, yet the description adds valuable examples for the query parameter (e.g., 'Apple', 'AAPL') and explains the market parameter's effect when omitted. This meaningfully extends schema information.

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 states the tool resolves a company name, brand, or ticker substring to canonical ticker(s). It clearly indicates the verb and resource, and distinguishes this from sibling tools by advising to use it first before ticker-keyed 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?

Explicitly says 'Use this FIRST when the user mentions a company by name/brand/nickname before running any ticker-keyed tool.' This provides clear when-to-use context and implies when not to use (when ticker is already known).

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