get_key_financials

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

No annotations are provided, so the description carries full burden. It discloses that data is sourced from annual 10-K XBRL, curated, and returns each line item as a time series with provenance (fiscal year, period end, form, accession number, URL). It does not mention authentication or rate limits, but it transparently covers data origin and output structure. No contradictions with annotations (none exist).

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 sentences plus a brief note about years. It front-loads the core functionality and adds critical detail without redundancy. Every sentence adds value, making it efficient for an AI agent.

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 adequately explains the return structure (time series with provenance fields). It covers the data source and use case. However, it could be more specific about the content of line items (e.g., which metrics are included) to fully prepare the agent. Overall, it is fairly complete for a financial data retrieval 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 description must compensate. Only the 'years' parameter is explained ('how many fiscal years back (default 5)'). The 'query' parameter, which is required, gets no explanation whatsoever in either schema or description. This is a significant gap for the most important parameter.

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 returns curated multi-year financials (income statement, balance sheet, cash flow) from 10-K XBRL data, specifying the verb 'get' and resource 'key financials'. It distinguishes from siblings by targeting 'financial-trajectory and capital-structure parts of a screen', which sets it apart from tools like get_risk_factors or get_financial_concept.

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 'Use this for the financial-trajectory and capital-structure parts of a screen', giving clear context for when to use it. It also explains the years parameter's role. While it doesn't explicitly state when not to use it or list alternatives, the guidance is sufficient given the sibling tool list.

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