ticker-scout

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds valuable behavioral context about what the coverage manifest includes: the fiscal period of latest data, the specific SEC filings used, and the predicted next filing. 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 dense single sentence but front-loads the core concept with 'Company identity and coverage manifest' before enumerating contents. All listed details are relevant, though the long dash-separated list could be cleaner as structured bullets.

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 carries the burden of describing return content, and it does so thoroughly: identity fields, latest data period, filing details with accession numbers and EDGAR links, and predicted next filing. Minor gaps like error behavior or empty results are not critical for this read-only look-up.

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 single parameter ticker already has a clear schema description with examples, including the brk-b format. The tool description adds no extra parameter-level information, so the baseline of 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?

States a specific verb-resource relationship: retrieving company identity and coverage information. The enumerated contents (name, CIK, exchange, SIC, filings, predicted next filing) make it clearly distinct from sibling tools like get_financials, get_key_figures, and get_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?

The description clearly implies use when company profile and coverage details are needed, but it does not explicitly say when to prefer it over alternatives or when not to use it. No sibling exclusions or routing conditions are provided.

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, but the description adds rich behavioral context: it covers a five-quarter window, reads from filings and exhibits, cites SEC accession numbers, returns the full digest by default (calling it 'short'), and allows narrowing via a section. This goes well beyond the annotations and tells the agent exactly what to expect.

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 front-loads the core purpose and content; the second explains the default return and the optional narrowing. Every clause carries information, and the description is appropriately sized for the tool's complexity.

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 explains what is returned (a digest) and its scale ('short'), plus the trailing five-quarter span and the source (filings and exhibits). It covers the parameter semantics, the default behavior, and the optional narrowing. Nothing an agent needs to call it correctly is left unspecified.

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 100% of parameters (ticker and section) with clear descriptions. The description adds the purpose of the section parameter ('Pass a section to narrow it'), reinforcing its role. Since schema already documents case-insensitivity and prefix matching, the description's extra value is the 'narrow' intent, earning a 4 above the baseline 3.

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 specific verb 'get' and a precise resource: 'Digest of a company's material current reports (Form 8-K)'. It distinguishes itself from siblings by naming the SEC form and listing concrete event types (earnings releases, management changes, etc.), so an agent knows exactly what this tool provides compared to get_financials or get_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?

The description implies when to use it (when you need a digest of material 8-K events) but never explicitly contrasts it with siblings or states when not to use it. It provides usage context through the time range and the 'narrow it' instruction, but lacks a clear alternative-selection rule.

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?

Beyond the readOnly and openWorld annotations, the description reveals data sources (annual report, quarterly report, current-report exhibit), fiscal calendar usage, actual dollar/split-adjusted share units, and the behavior that section names vary by company. This is valuable operational context.

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 front-loaded with the core purpose and then provides rationale, data sources, units, and usage strategy. Every sentence contributes useful information without redundancy or filler.

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 covers the return contents (statements, periods, segment/per-share figures), units, and even suggests a discovery call to handle variable section names. It gives an agent enough context to invoke the tool effectively and understand the response.

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 fully documents both parameters (ticker and sections) with descriptions. The description adds semantic guidance for the sections parameter by noting it should be omitted initially and that unknown names return valid lists, which is useful beyond the schema's generic description.

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 explicitly states the tool returns income statement, balance sheet, cash flow, segment revenue, and per-share figures assembled from SEC filings. It clearly identifies the resource and content, distinguishing it from siblings that handle other company data (events, key figures, 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?

The description explicitly recommends preferring this tool over manually building statements from EDGAR or CompanyFacts, and instructs calling with no sections first for discovery. It does not explicitly compare against sibling tools, but the provided context is clear for when to use it.

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 declare readOnlyHint=true and openWorldHint=true, so the description is not burdened with safety disclosure. It adds useful behavioral context beyond annotations: the default returns an index rather than the full document because the document is large, and it flags quarter-over-quarter risk factor changes. This helps the agent anticipate the tool's interaction pattern.

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 earning its place: the first defines the tool's substance, the second explains the default behavior and rationale, the third explains the section parameter options. It is front-loaded with the most important semantic information and contains no filler.

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 two-parameter read-only tool, the description is nearly complete: it names the input, the three invocation modes, and the output shape for the default call. It does not enumerate every possible section name, but the index mechanism deliberately covers that gap, so nothing critical is missing for an agent to use it 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It explains the two-step workflow (index first, then section), why that design exists, and confirms the 'all' escape hatch. This is the kind of practical parameter guidance that makes the tool easy to invoke correctly on the first try.

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 a specific verb and resource: it produces a 'qualitative synthesis' of a company's latest 10-K and 10-Q, and enumerates the covered areas (business description, risk factors, MD&A, legal proceedings, subsequent events). It also differentiates itself from news-based summaries and, by contrast with numeric sibling tools like get_financials and get_key_figures, makes its qualitative nature explicit.

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 context on how to invoke the tool: omit section for an index, pass a section name for text, or use 'all' for the full document. It does not explicitly mention when not to use it versus siblings, but the qualitative-vs-quantitative distinction and the filing-based source are strong usage signals.

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.