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.