ticker-scout

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

Annotations (readOnlyHint, openWorldHint) already establish that this is a safe, read-only operation with potentially changing data. The description adds value by disclosing the exact return payload, including the predicted next filing, which is a behavioral trait beyond the annotations. No contradiction with annotations.

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 enumerates the output fields without unnecessary wording. It is concise and effective, earning its place with specific, relevant details.

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 low complexity (one parameter, no output schema), the description adequately explains what is returned by listing all fields. Minor gaps include lack of details on error behavior for unknown tickers, but for a simple profile retrieval tool this coverage is sufficient.

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 provides full parameter description coverage for the single ticker parameter, including case-insensitivity and examples. The tool description adds no additional parameter semantics, so the baseline score of 3 applies.

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: returning a company identity and coverage manifest with specific fields (name, CIK, exchange, SIC, fiscal period, accession number, predicted next filing). This specific field list distinguishes it from sibling tools like get_financials and get_events.

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 use cases (retrieving static company identity and coverage metadata) but does not explicitly state when to use this tool over alternatives or provide exclusion scenarios. The title and field list strongly suggest the intended use, but no comparative guidance is given.

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 openWorldHint=true, so the description does not need to restate safety. It adds valuable context beyond annotations: the trailing five-quarter time range, the digest being short by default, the optional section filter, and that each item cites an SEC accession number. This exceeds the minimum with annotations present.

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?

Two sentences, front-loaded with purpose and scope, then behavioral details. Every clause earns its place: event types, accession numbers, default behavior, and section usage. No fluff or repetition.

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 read-only tool with one required and one optional parameter, the description is complete: it explains the time range, content types, output size, and section narrowing. No output schema exists, but the description itself clarifies the default return. It does not enumerate all sections, but that is not necessary for the tool to be invoked 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% with both parameters described (ticker examples, section optional and prefix-matched). The description adds only a small clarification that passing a section narrows the result, but this is already implied by the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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 digests a company's material 8-K filings over trailing five quarters, listing specific event types (earnings releases, management changes, etc.) and explicitly mentions returning the digest. This distinguishes it from sibling tools like get_financials or get_company, which focus on other data.

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 when to use the tool: when a user needs material corporate events from 8-K filings. It also provides usage guidance ('Returns the full digest by default; it is short. Pass a section to narrow it'). However, it does not explicitly name alternative tools or state when not to use it, so a small gap remains.

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?

Adds meaningful behavioral detail beyond annotations: all money in actual dollars, share counts in actual shares, section names vary by company, and behavior when 'sections' is omitted. This helps the agent understand response content and how to explore a company's structure. No contradiction with readOnlyHint.

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?

Three sentences, each essential and front-loaded with core purpose. Includes critical usage notes about units and section discovery without unnecessary verbosity.

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?

Despite lacking an output schema, the description sufficiently outlines expected contents (financial statements, units, periods) and the discovery workflow for sections. It does not detail response structure or pagination, but for this tool the description is reasonably 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?

Schema covers both parameters, so baseline is 3. The description adds value by explaining the 'sections' parameter behavior (omitting it returns available sections, unknown names return valid list) and clarifies that the 'ticker' is case-insensitive. This goes beyond the schema's static 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 retrieves financial statements from the latest 10-K and 10-Q, listing specific contents (income statement, balance sheet, cash flow, etc.) and time periods. This distinguishes it from sibling tools that cover company info, events, key figures, and narrative.

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?

Provides clear guidance on usage: call with no sections first to discover company-specific section names, then request only needed sections. While it does not explicitly discuss alternatives among siblings, the context is clear and useful for effective invocation.

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 and openWorldHint. The description adds behavioral context: the tool returns only the most recent period, includes year-over-year change and exact dollar amounts, and cites the SEC accession number. It also warns about response size relative to get_financials. This exceeds the annotation baseline.

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?

Two sentences, no fluff. The first sentence fully specifies what is returned; the second provides usage guidance and a comparison. Information is front-loaded and each sentence earns its place.

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 tool with no output schema and strong annotations, the description is complete. It explains the scope ('most recent reported period'), the output fields, and the relationship to siblings. No critical gaps remain.

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% for the ticker parameter, which is well-documented with case-insensitivity and examples. The description doesn't add parameter-level detail beyond the schema, but it indirectly reinforces that the tool operates on a company. Since coverage is high, 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 clearly states the tool returns headline figures (revenue, net income, diluted EPS) for a company's most recent reported period. It distinguishes itself from the sibling get_financials by explicitly saying it's 'far smaller' and by anchoring to 'how much did X earn' questions.

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 directs the user to 'Start here' for earnings questions, implying this is the first tool to use. It also contrasts with get_financials by noting size difference. However, it does not explicitly cover when not to use other siblings like get_events or get_narrative, but those are contextually distinct.

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 read-only and open-world behavior. The description adds valuable non-obvious behavior: calling without a section returns an index, the full document is large, and risk factors have quarter-over-quarter changes flagged. This goes beyond the structured annotations.

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, front-loaded with purpose and content areas, followed by concise usage instructions. Every sentence serves a function with no redundancy or extraneous detail.

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 no output schema and two parameters, the description thoroughly covers the retrieval modes (index, section text, full document) and the qualitative content. It does not mention error handling for invalid section names or missing filings, but that is not critical given the clear interaction model.

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 meaningful semantics for the optional 'section' parameter by explaining the index-first retrieval pattern and the 'all' option, which is more detailed than the schema's simple 'Omit for the section index.'

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 'Qualitative synthesis of a company's latest 10-K and 10-Q' and enumerates specific content sections (business description, risk factors, MD&A, legal proceedings). This verb+resource+scope is precise and distinguishes the tool from siblings like get_financials, which is quantitative.

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 clear internal usage guidance (omit section for index, pass section name for text, use 'all' for the full document) but does not explicitly state when to use this tool over siblings. Differentiation is implied by the word 'qualitative' rather than explicitly stated.

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, so the description doesn't need to cover safety. It adds behavioral context about what the list includes (covered companies) and the metadata shown (fiscal period, predicted next filing date). No contradictions with annotations.

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?

Two concise sentences, front-loaded with action and list contents, followed by usage guidance. No wasted words, perfectly sized for its purpose.

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 simplicity (one optional parameter, no output schema), the description covers purpose, output contents, and when to invoke. Annotations support the safety profile, making this complete for the tool's complexity.

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% for the query parameter. The description adds value by explaining the real-world use of the filter: to determine coverage or resolve a company name to a ticker, enriching the purpose beyond the basic schema text.

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 uses specific action 'List' with resource 'public companies Ticker Scout covers', and specifies the output contents (fiscal period, predicted SEC filing date). It clearly differentiates from sibling get_* tools by positioning itself as the discovery/listing tool.

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 'Call this first when you do not know whether a company is covered, or to turn a company name into a ticker.' This provides clear when-to-use guidance and implicitly contrasts with alternative family-specific tools.

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