fmp_reference

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

No annotations are provided, so the description carries the burden of disclosure. The verb 'look up' indicates a read-only operation, and the tool's purpose suggests no side effects. However, the description does not mention any potential rate limits, authentication requirements, or specifics about the response format, leaving some behavioral aspects undisclosed. It's not misleading, but it's minimal.

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, concise sentence that immediately states the tool's function. There is zero fluff, every word contributes to clarity, and it is front-loaded with the key action and object. 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?

The tool is simple with one enum parameter and has an output schema (though not shown), so the description does not need to elaborate on return values. The description captures the two main use cases (screener filters and index constituents) and is adequately complete for its simplicity. However, it could add a note about relation to the screener tool (e.g., 'use these values when calling fmp_screener'), which would make the context more 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?

The schema has one parameter ('kind') with a full enum, but no description strings (0% schema description coverage). The tool description adds a categorical distinction between screener filter values (sectors, industries, exchanges, countries) and index constituents (sp500, nasdaq, dowjones), which provides some added semantics. However, it doesn't explain each enum value's meaning beyond that rough grouping, so the description only partially compensates for the lack of 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's purpose: to look up valid values for screener filters or index constituents. It uses a specific verb ('look up') and resources ('valid values for screener filters, or an index's constituents'), and it distinguishes from sibling financial data tools by focusing on reference data rather than raw market data or metrics.

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 usage for prefilling screener filters or obtaining index membership, but it does not explicitly state when to use this tool versus alternatives like fmp_screener or fmp_index_constituents (none exist). It lacks explicit 'use this when you need filter values' guidance or exclusionary language, so the usage context is implied rather than instructed.

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