get_available_metrics

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety behavior needs no restating. The description adds that the listing is exhaustive and filtered by search_term, but says nothing about pagination, result size limits, or rate/API-status behavior for an SEC-backed call.

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?

Purpose and the when-to-use hint are front-loaded and useful, but the Args/Returns blocks largely restate the input schema and the existing output schema. The return enumeration is redundant given has_output_schema=true.

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 2-parameter discovery tool with annotations and an output schema, the description covers purpose, filter behavior, and ticker input adequately. The main omission is guidance on what to do with the results (e.g., feed metric names into the metrics-fetching 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 description coverage is 0%, so the description must compensate, and it does: ticker is described with concrete examples ('GME', 'AAPL') and search_term is explained as a filter with examples ('EBITDA', 'Revenue', 'Debt'). Only the exact matching semantics (substring vs exact) remain unstated.

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?

States a specific verb+resource ('Discover available financial metrics ... from SEC XBRL data') and clarifies the discovery role versus metric retrieval tools. It does not, however, distinguish itself from close siblings such as get_company_facts or get_xbrl_frames, and it references 'specific_metrics', which is not in the sibling list.

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 tells the agent to call this before requesting metrics ('Useful for AI to find exactly which metrics are available before requesting them'), which is clear usage context. It stops short of naming an alternative sibling or stating when the tool is unnecessary.

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