Drillr — The financial MCP for AI agents

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

Annotations already mark this as read-only and non-destructive, so the description adds value by stating the result ordering (update_date descending) and the empty-array behavior on no matches. It also details the fields returned, giving agents a clear picture of the output.

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 front-loaded with the main action and filter options, but it is long and lists all output fields, which could be trimmed if an output schema were present. It is still organized and each sentence earns its place, though it is not highly concise.

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

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

For a tool with six parameters and no output schema, the description covers the filters, output structure, and ordering. It also explains the default browse mode and empty results. It is complete enough for an agent to call it correctly, though pagination behavior is left to the schema.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds minor usage hints like the date format for 'since' and partial matching semantics, but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a clear verb and resource: 'Search concrete enterprise AI applications disclosed in US company earnings calls.' It specifies the domain and distinguishes it from sibling search tools by focusing on AI adoption data. The list of output fields further clarifies what the tool returns.

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

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

The description states the intended use cases: 'identify where and how a company applies AI, assess deployment maturity, scope, and disclosed value, and inspect the supporting evidence.' It also gives a default behavior for no filters: 'Use no filters to browse the most recently updated observations.' It does not name alternatives, but the context is clear.

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 mark it read-only and non-destructive; the description adds meaningful behavior: returns a structured list with context snippets, accepts natural-language queries, covers exactly five markets, and clarifies that list order carries no priority. This complements the annotations without contradicting them.

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?

Information is front-loaded with the most important usage distinction first, and each paragraph has a clear role. Some redundancy exists between the first and second paragraphs' lists of qualitative dimensions, but the structure is still easy to scan and not bloated.

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

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

With no output schema, the description compensates by specifying the return shape as a structured list with context snippets. It covers input format, market enumeration, coverage, and scope, which is sufficient for a two-parameter discovery tool; only minor output-field detail is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds a concrete query example and expands the meaning of the market filter with coverage context and the 'omit or [] for all five' rule. Most market details repeat the schema, but the example and qualitative framing provide extra value.

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 opens with a specific verb and resource: qualitative company discovery across named dimensions, and closes with a constraint that it is ONLY for finding a list of companies by description. It also distinguishes itself from run_sql's numerical screening, making the tool's identity unambiguous even without an explicit title.

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 states when to use the tool (qualitative discovery) and when not to (numerical screening), naming run_sql on company_snapshot as the alternative. The final line 'ONLY for finding a LIST of companies by description' provides a hard boundary.

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 safety profile is clear. The description adds valuable behavioral context beyond annotations: it explains the default behavior of the 'filing_types' filter (omit for main reports only, excludes ad-hoc), and describes the exact return structure (summary + table up to 50 filings). It also mentions the need to pass [] for all indexed types or an allowlist. It doesn't mention pagination limits beyond 50, but that is explicit in the return. Strong supplemental context.

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

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

The description is well-structured: it starts with the primary purpose, then the alternative, then the behavior, and ends with filter details. It is dense but every sentence earns its place. The formatting with line breaks for returns and filter details improves readability. It is concise given the complexity it covers.

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 params, no output schema), the description is complete for effective invocation. It doesn't need to explain return values because it explicitly lists the summary fields and table columns. It covers the nuanced filing_types behavior thoroughly, which is the main source of confusion. Annotations cover mutability. No gaps that would prevent correct use.

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

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

Schema description coverage is 100%, so baseline 3. However, the description adds significant meaning beyond the schema: it explains the default behavior of filing_types in detail (what types are included/excluded) and instructs to pass [] for all indexed types or an explicit allowlist. It also clarifies the purpose of the return values (summary + table). This goes beyond the schema's straightforward parameter descriptions, enriching the agent's understanding of how to use the filter.

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 is very specific about its purpose: discovering which SEC filings exist for a ticker before searching content. It clearly states the resource (SEC filings for a ticker) and the action (list). Sibling differentiation is excellent: it explicitly contrasts with 'filing_search' for content, and other siblings like 'list_tables' or 'run_sql' are clearly different. The summary header and return table are described.

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

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

The description provides explicit guidance on when to use this tool: 'to discover which SEC filings exist... before searching content'. It also explicitly states when to use the alternative: 'For the actual content use filing_search instead.' This is a clear when/when-not with named alternative. No further exclusions needed.

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 covered. The description adds valuable behavioral context beyond that: it reveals the call returns both Facts and Passages in one response, and that an empty Facts section should prompt reading Passages – a fallback behavior that is not obvious from annotations or schema. It also mentions interval-overlap matching for period parameters, which is a useful behavioral nuance.

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

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

The description is three sentences with zero fluff. The core purpose is front-loaded, followed by the most important usage tip (ticker required), then the fallback behavior, then period semantics. Every sentence earns its place, and the structure makes it easy to scan.

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

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

For an 8-parameter tool with no output schema, the description covers the essential facts: what it returns, how to handle an empty Facts section, and how to use period parameters. It does not explain every parameter, but the schema handles that. The main missing piece is guidance on tool selection (when to use this vs. filing_list), which is partially covered under usage_guidelines. Overall, it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters with detailed descriptions. The description adds meaning beyond that by explaining that period_start/period_end match by interval overlap and that fiscal_period sets granularity – details not present in the schema. It also reinforces that ticker is required, which is already in the schema but is a critical constraint. This goes beyond the 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?

The description opens with 'Search one company's SEC filings' – a specific verb, resource, and scope. It then names the two output sections (Facts and Passages), which differentiates it from sibling tools like filing_list (likely listing filings) and news_search. An agent can tell this is the tool for searching a single company's financial filings without opening the schema.

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

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

The description gives operational guidance: 'ticker is REQUIRED' and 'Pass an explicit period window for the most recent figure.' It also instructs to read Passages when Facts is empty. However, it does not explicitly state when to use this tool versus alternatives like filing_list or company_search. It implies this is for searching filings but never names a sibling or a condition that would route the agent elsewhere.

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 cover read-only and non-destructive behavior. The description adds useful context by clarifying that the output is metadata (column definitions) rather than table data, and that a usage note with required filters, ticker format, and market coverage may be included where one exists.

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

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

The description is a single, front-loaded sentence that states the core return value first and the optional usage-note detail second. There is no filler, redundancy, or repeated schema information.

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

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

For a simple one-parameter, read-only metadata tool with no output schema, the description explains the return value sufficiently: column names, types, descriptions, and optional usage notes. The enum schema covers valid inputs, so nothing critical is missing for correct invocation.

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 single parameter table_name is self-explanatory and the enum exhaustively enumerates valid table names, so the agent can invoke the tool correctly despite 0% schema description coverage. However, the description itself adds little semantic detail about the parameter beyond referring to 'a data table'.

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 that the tool returns column definitions (name, type, description) for a data table, plus an optional usage note. It names a specific resource and output, and the behavior is distinct from siblings like list_tables or run_sql.

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

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

The description implies it is the tool for inspecting table metadata, but it never explicitly states when to use it instead of alternatives like list_tables or run_sql. The usage context is inferable from context but not made explicit.

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 non-destructive, so the description doesn't need to emphasize safety. It adds value by disclosing the response format, ordering, and no-match message. However, it doesn't mention any rate limits or potential performance implications, which could be relevant given the pagination limit of 10. Overall, it adds context beyond annotations but not exhaustive.

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-organized, starting with the main purpose, then filter behavior, then return format details. It's a bit verbose but each sentence serves a purpose: clarifying defaults, ordering, no-match text, and result structure. Could be slightly tightened, but it's structured and front-loaded with the key functionality.

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

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

Given the tool's moderate complexity (5 optional parameters, no output schema, and structured output), the description covers essential aspects: filter semantics, ordering, default behavior, no-match response, and detailed return fields. It lacks explanations for some return fields (e.g., impact_scope, attention_verdict) but provides enough for an agent to call it correctly. Sibling differentiation is implied but not explicit.

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% — each parameter has a description that explains its purpose (e.g., ticker filter, keyword, impact_companies). The tool description adds context on how filters combine (AND) and the default pagination, which the schema doesn't state. But the schema already covers parameter meaning well, so the description adds marginal value.

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

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

The description clearly identifies the tool as searching for 'industry inflections' identified from earnings calls, specifying the resource and its key attributes. It distinguishes this from siblings like 'company_search' or 'news_search' by focusing on structured research of earnings calls and the specific data fields returned.

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 that all filters are optional and combine with AND, the default behavior (newest first page), and the exact ordering. It also describes the no-match return value, which guides agents on what to expect. This is sufficient guidance for when to use this tool versus alternatives, as it's a specialized search tool.

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

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

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?

The annotations already mark the tool as a safe read (readOnlyHint, non-destructive), so the bar is lower. The description adds substantial behavior beyond that: exact Markdown return shape, meanings of columns, the relationship between Events story numbers and Stories, and the fact that lowest-ranked stories are dropped with a meta-line omission count. No contradiction exists.

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 dense but efficient, starting with the intended use, then the output shape, then essential constraints. Every sentence communicates a distinct fact needed to call the tool correctly. It is appropriately sized for an 8-parameter search tool with no output schema.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: Markdown structure, numbered stories, flat events/claims tables, reference columns, source counts, reporting span, and dropped-story behavior. It also covers requirements and constraints, making it complete for an agent to invoke 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 the baseline is 3. The description adds meaningful semantics beyond the schema by explaining cross-parameter requirements, that tickers must be exchange-suffixed, that multiple tickers act as an OR/overlap filter, and that company names/brands are not resolved. This is useful but not exhaustive for every parameter, so a 4 is appropriate.

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

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

The description clearly states the tool is for news, event, development, or statement questions about companies, themes, or the market. It names the resource (news stories/events/claims) and the main filtering dimensions. It does not explicitly contrast itself with sibling tools like company_search or filing_search, 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.

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

It opens with an explicit 'Use for any news...' usage condition and adds concrete parameter-level guidance, such as 'search_type=claims needs query/ticker/a time window, not theme' and 'At least one of query/theme/ticker/since/until is required.' It does not mention alternative sibling tools or state when to prefer them, so no exclusion guidance.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'SELECT only' and 'query fails otherwise' for rule violations. It discloses critical behavioral traits: period columns are TEXT and must be compared as strings, CTEs are disallowed, and certain tables require mandatory filters. This goes well beyond the annotations by explaining the data model quirks and failure conditions, giving the agent a thorough understanding of how the tool behaves.

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-organized into logical sections: purpose, hard rules, and table categories. It front-loads the core purpose and then dives into necessary details. Every sentence serves a purpose—either clarifying rules or listing tables—so there's minimal redundancy. While it's verbose, the complexity of the tool justifies the length, and the structure aids comprehension. It could be slightly more concise, but it's still efficient for the information conveyed.

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

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

For a tool with this level of complexity (multiple table domains, strict query rules), the description is remarkably complete. It covers the key constraints, table inventory, and references to companion tools (get_table_schema, list_tables) for deeper schema exploration. The return type is mentioned ('structured rows'). The only thing not covered is the exact schema of each table, but that's delegated to get_table_schema, so the description does its job without overreaching.

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?

There is only one parameter (sql) with a minimal schema description ('PostgreSQL SELECT query'). The tool description vastly enriches this by explaining the expected query format, constraints, and examples (e.g., WHERE ticker IN ('AAPL','MSFT')). It also lists the tables and hints on filtering, effectively teaching the agent how to construct valid queries. This far exceeds the schema's minimal documentation, making parameter semantics exceptionally clear.

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 opens with a precise statement: 'PostgreSQL SELECT over financial / market / alt-data tables — returns structured rows.' It names a specific verb (run) and resource (SQL query over financial tables), and clearly distinguishes itself from sibling tools like company_search and news_search by focusing on structured SQL access. The mention of returning structured rows further clarifies the output, leaving no ambiguity about what the tool does.

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

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

The description provides explicit usage context: it's for SELECT queries on structured tables, with hard rules and a detailed table listing by domain. It also references get_table_schema and list_tables for additional schema and category info, effectively guiding the agent on how to proceed. While it doesn't explicitly state 'use this instead of X' for each sibling, the scope is clear, and the guidance on filtering by ticker and time_frame is actionable. The only minor gap is the absence of explicit 'when not to use' statements for alternative tools, but the domain-specific focus makes the usage obvious.

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 safety profile is covered. The description adds valuable behavioral detail: it discloses the ranking logic (prefix-hit first, then name length), the result cap (up to 5 matches), and the fact that symbols carry a market suffix. This goes beyond what annotations provide, giving the agent clear expectations of how results are ordered and limited.

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-organized with an opening purpose statement followed by a clear 'Input' section and a note on output. It is concise and front-loaded, making it easy to scan. However, the market value list is redundant and partially incorrect, which is a structural flaw that detracts from its efficiency.

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

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

The description covers the input parameters, the result limit, and ranking logic, but it omits behavior for no-match cases (e.g., what happens if no ticker matches) and does not mention that historical names are also matched (which the schema notes). Given the tool's simplicity and the absence of an output schema, this leaves minor but relevant gaps that could affect correct usage.

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 description adds useful examples for 'query' and clarifies the expected input format, but it introduces a serious inconsistency: it lists market values as 'us' | 'jp' | 'cn' while the schema enum includes five values ('us', 'jp', 'hk', 'cn', 'kr'). This misleading subset could cause an agent to omit valid market filters or mistakenly believe other markets are unsupported. Since schema coverage is 100%, the description should align exactly with the schema, and this discrepancy actively harms parameter understanding.

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

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

The description states a clear, specific action: resolving a company name, brand, or ticker substring to canonical ticker(s). It names the resource (tickers) and the operation (resolve), and the examples make the intent unambiguous. While it does not explicitly differentiate from the sibling 'company_search', the purpose is self-contained and obvious.

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

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

The description implies its use case (converting names/brands to tickers) but provides no explicit guidance on when to prefer this tool over alternatives like 'company_search' or 'news_search'. It does not mention exclusions or alternative tools, leaving the agent to infer the appropriate selection from the purpose alone.

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