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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond annotations: fiscal years end on different dates across companies and the period end used is shown, helping the agent understand cross-company comparability caveats.

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-load the core purpose, scope, and the key caveat about fiscal-year alignment. No filler or redundant repetition of schema 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?

For a multi-company comparison tool with four well-documented parameters and safety annotations, the description covers the essential comparison logic, metric scope, and the period-end caveat. It does not describe output format details, but the response_format parameter and the note that period ends are shown provide adequate context for invocation.

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%, so the schema fully documents companies, metrics, fiscal_year, and response_format. The description adds minimal semantic value beyond restating metric categories and the fiscal-year default, which is already in the schema.

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 ('Compare'), a specific resource (2-10 companies), and a clear scope (key metrics for latest or given fiscal year). It clearly differentiates from siblings like edgar_get_key_metrics (single company) and edgar_rank_companies (ranking) by emphasizing side-by-side multi-company comparison.

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 the appropriate use case: comparing multiple companies on metrics. However, it does not explicitly state when not to use it or name alternative tools, leaving the selection guidance to inference rather than direct instruction.

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 establish read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: the search covers filings since 2001, supports exact phrases in double quotes, and returns company, form, filing date, and document URL for each hit.

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 with no filler. The purpose and key example are front-loaded, and each sentence contributes meaningful information: scope, query syntax, filters, and output behavior.

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?

No output schema exists, so the description compensates by explicitly naming the returned fields: company, form, filing date, and document URL. Parameter behavior is well covered by schema descriptions. Minor additional details, such as no-result behavior or pagination handling are not described, but the tool's essential calling context is complete enough.

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%, so the input schema already documents every parameter. The description reinforces the main filters and query syntax with an example, but adds only slightly to what the schema already provides.

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 and resource: 'Search the full text of all SEC filings since 2001.' It clearly distinguishes this tool from siblings like edgar_list_filings, edgar_search_companies, and edgar_search_concepts by emphasizing full-text content search.

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 for when to use the tool: full-text search over SEC filings, with filters by form type, date range, and company. It also points to a follow-up action, edgar_read_filing, but does not explicitly state when not to use it or name alternatives.

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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true), so the description's job is lighter. It adds useful field-level details—such as 'former names' and 'latest annual/quarterly reports'—that clarify the scope of the operation without contradicting the 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?

A single sentence that front-loads the purpose, followed by a compact colon-delimited list of returned data. No filler, redundancy, or unnecessary 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?

Given only 2 parameters, 100% schema coverage, rich annotations, and no output schema, the description provides all needed information: what the profile contains, how to invoke it via schema, and the read-only safety profile. Nothing essential is missing.

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 fully documented (company examples and formats, response_format enum and default). The description introduces no additional parameter semantics beyond listing result fields, so the baseline 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 uses a specific verb ('Get') and resource ('a company's SEC profile'), then enumerates concrete fields (legal name, CIK, SIC, tickers/exchanges, filer category, latest reports). This clearly distinguishes it from sibling tools like edgar_list_filings or edgar_get_financial_statement, which focus on filings or statements rather than profile 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?

Usage context is implied rather than explicit: the description conveys 'use this when you need a company's SEC profile,' but it does not name alternative tools or state when not to use it. No exclusions or routing guidance is provided, so an agent must infer the right situation from the purpose alone.

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, openWorldHint, idempotentHint, and destructiveHint, so the description appropriately adds value beyond them: annual/quarterly durations, YTD-derived quarters, and 'all' returning every distinct reported period. It does not describe the return payload, but read-only annotations lower the burden; what the description adds is genuinely useful behavioral nuance.

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 with no filler. The first sentence front-loads the purpose and examples; the second packs the period-behavior nuance and the search-first caution. Every clause 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 tool with only two required parameters, 100% schema coverage, read-only/idempotent annotations, and no output schema, the description plus schema is sufficient for correct invocation. It clearly explains concept choice and period behavior; explicit edge cases like empty results are not addressed, but nothing essential for calling the tool is missing.

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 schema documents all six parameters. The description adds value by giving realistic concept examples and warning that a likely-looking concept like us-gaap:NumberOfEmployees is rarely tagged, which helps agents choose concept values. It does not add extra detail for unit/max_points/response_format, but the schema covers those clearly.

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'), resource ('reported history of any XBRL concept'), target ('for a company'), and concrete examples. It distinguishes this tool from siblings like edgar_get_financial_statement or edgar_get_key_metrics by focusing on the history of a single concept, and the 'search first' hint differentiates it from edgar_search_concepts.

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?

It gives concrete usage context: annual/quarterly/all period behavior and points the agent to search first for rarely tagged concepts. It does not explicitly name alternative tools or state when not to use this tool versus a financial statement tool, but the period semantics and search-first warning provide clear practical guidance.

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?

The description goes well beyond the read-only annotations by disclosing important behaviors: 'latest filing wins, so restatements are reflected', YTD quarterly values are derived by subtraction and flagged, and cash flow includes free cash flow (CFO − capex). These are non-obvious transformations an agent needs to interpret results correctly.

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?

Four dense sentences with zero filler. The main purpose is front-loaded, followed by scoping, key behavioral caveats, and an explicit fallback. Every 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?

Given that there is no output schema, the description still conveys the returned structure ('line items × periods'), data caveats, YTD derivation, and free cash flow inclusion. Combined with the complete parameter schema and sibling fallback, an agent has enough to select and invoke the tool 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?

Input schema description coverage is 100%, so the baseline is 3. The description adds useful context about output shape and derived values but does not add per-parameter semantics beyond what the schema already provides, so no higher score is warranted.

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 a specific verb ('Get') and names the exact resources ('income statement, balance sheet or cash flow statement'), source ('SEC XBRL filings'), and result shape ('line items × periods'). It clearly differentiates itself from concept-level tools by naming them as the fallback for individual tags.

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 final sentence gives explicit routing guidance: 'For any tag not covered here use edgar_search_concepts + edgar_get_concept.' It also specifies applicability (10-K/10-Q, IFRS for 20-F/40-F filers), so an agent can decide when this tool is appropriate and when to delegate.

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 cover the read-only, idempotent, open-world, and non-destructive behavior, so the bar is lower. The description adds useful context by specifying the parsed source (Form 4 filings), the output summary, and the meaning of transaction codes—value beyond the annotations. It does not mention rate limits or failure modes, but for a read-only EDGAR tool that is a minor gap.

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 compact and front-loaded: the first sentence states the verb, resource, scope, and output fields; the second sentence efficiently maps transaction codes. Every sentence earns its place and there is 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 read-only tool with no output schema, the description does a good job enumerating return values and the output summary, while the schema covers parameter semantics. It does not precisely define 'recent' or explain pagination/limits, but given the openWorldHint and the simplicity of the tool, this is not a serious gap.

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%, so the schema already documents all four parameters. The description adds value by explaining transaction codes like P, S, A, and F, which supports understanding of open_market_only, but it adds no syntax or format details beyond what the schema already provides.

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 a specific verb ('Get') and resource ('insider transactions from Form 4 filings') and enumerates the returned fields, making it clearly distinct from generic EDGAR tools like edgar_list_filings or edgar_read_filing. It also identifies the reporting subjects (officers, directors, 10% owners), which sharpens the purpose.

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 never says when to choose this tool over alternatives such as edgar_read_filing or edgar_list_filings, nor does it give exclusion criteria. Usage context is only implied by the phrase 'recent insider transactions'; there is no explicit when/when-not guidance.

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, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: 13F reports include only long US-listed positions, exclude shorts/cash/foreign shares, are filed up to 45 days after quarter end, identify securities by CUSIP, and ignore amendments. This gives the agent important expectations about data scope and reliability.

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 compact and front-loaded: the main purpose and output contents come first, followed by concrete examples, then a consolidated Notes section of caveats. Every sentence earns its place and the length is appropriate 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?

Even without an output schema, the description tells the agent what the tool returns: positions by value, % of portfolio, shares, and change versus the previous quarter. Combined with the fully documented input schema and domain caveats, an agent has enough to select the tool, choose parameters, and interpret results 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%, so each parameter is already explained in the schema. The description reinforces the manager concept with examples and mentions the 45-day filing lag relevant to period, but it does not add significant meaning beyond the schema. 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 names a specific verb ('Get') and a particular resource: the US equity portfolio reported on Form 13F by investment managers. It clearly distinguishes this tool from siblings like edgar_get_insider_trades or market_get_stock_price by focusing on quarterly institutional holdings.

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 for when to use the tool: it works for hedge funds, mutual fund families, banks, insurers, and accepts a manager name or CIK. It also explains limitations such as long-only US positions and the 45-day filing lag. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that metrics are computed from SEC filings, but does not disclose any additional behavioral traits such as rate limits, data limitations, or response variability, leaving the baseline at 3.

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 contain the full purpose and use case with no filler. The metric list is dense but informative, and the 'best single call' positioning earns its place by orienting the agent immediately.

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 read-only metrics tool, the description covers what is computed and when to use it, aided by thorough parameter schemas and annotations. There is no output schema, so a bit more detail about the exact output shape could help, but the response_format parameter and metric enumeration make it adequate for correct invocation.

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%, and each parameter (company, period, max_periods, response_format) already has a clear description in the schema. The description adds no extra parameter-level meaning, so the baseline 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 opens with a specific verb and resource, 'Compute key metrics from SEC filings', and enumerates the exact metrics returned. It does not explicitly name a sibling tool to distinguish itself from, but the list plus 'quick fundamental overview' makes its role clear relative to raw statement retrieval.

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?

'Best single call for a quick fundamental overview of a company' gives a clear when-to-use context. It stops short of saying when not to use it or naming alternatives, so it lacks the explicit exclusion criteria that would earn a 5.

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 the operation read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that: results are newest-first and include form type, dates, accession number, and document URL.

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 compact sentences deliver the core purpose, output shape, ordering, and a useful forms reference with no wasted words. The most important information is front-loaded.

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 list tool with rich annotations and full schema coverage, this description is sufficiently complete. It even supplies the return shape despite the lack of an output schema.

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 schema carries most parameter meaning. The description adds domain value beyond the schema, especially the form-type glossary and the note that 8-K items such as 2.02 indicate earnings.

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 action ('List'), a concrete resource ('a company's SEC filings'), and defines the output fields and ordering. This clearly distinguishes it from siblings like edgar_read_filing and edgar_get_company_info.

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 first sentence clearly identifies when to use the tool: to list a company's SEC filings. It does not explicitly name alternatives or exclusions, leaving some routing decisions to inference, but the context is unmistakable.

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 readOnly/openWorld/idempotent/non-destructive hints, so the description only adds value beyond safety. It contributes a useful behavioral detail about how fiscal periods are mapped to calendar periods, which is exactly the kind of context that would otherwise be surprising to an agent.

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 compact and front-loaded: the first sentence states the core operation and examples, followed by only the non-obvious period format and calendar-alignment behavior. Every sentence contributes information that isn't already in the schema, with 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 tool with 7 parameters, no output schema, and annotations carrying the safety profile, the description covers the two required parameters' subtleties and the calendar-period mapping that affects result interpretation. It could additionally mention what fields each ranked row returns, but that is not necessary for selecting or invoking the tool 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?

The schema already covers 100% of parameters, so the baseline is 3. The description adds real added value on top by explaining the period grammar (CY2025/CY2025Q4/CY2025Q4I) and giving concept examples, adding meaning beyond the regex patterns. It doesn't need to add every parameter because the schema already documents unit/limit/order/response_format.

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 names a specific verb ('Rank every SEC filer') with a specific object ('one XBRL concept') and a scope ('calendar period') plus concrete examples like largest revenues and most cash. This makes the tool's purpose unmistakable and distinct from company-specific siblings like edgar_get_financial_statement or edgar_compare_companies.

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 a clear context: universe-wide ranking across all SEC filers, with period semantics and calendar-alignment caveats explained. It does not explicitly say 'use X instead for named-company comparisons' or mention when not to use it, but the framing frames vs specific filer tools is clear enough for an agent to infer the right selection.

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/idempotent annotations, it discloses pagination by characters, jump semantics, continuation via offset, and that the header lists exhibits. It also reveals that omitting accession_number returns the latest annual report. 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 front-loaded with a one-sentence core, followed by four scannable bullets that map to parameters/modes, each with concrete examples. The final sentence adds a useful default behavior. There is 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 7-parameter tool with no output schema, it covers all access modes, pagination continuation, exhibit selection, and the latest-10-K default. It also tells the agent where to find valid document filenames (the header), making the tool safely callable in realistic workflows.

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 useful semantic context with examples for find phrases, exhibit filenames, offset continuation, and accession_number default behavior. It enriches the schema without repeating it.

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 opens with a precise verb+resource: 'Read the text of a filing's main document... or one of its exhibits,' and includes the filing types covered. This clearly distinguishes it from siblings like edgar_list_filings (listing) and edgar_get_financial_statement (structured financials).

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?

It gives explicit operational guidance for the main modes: section, find, document, and offset continuation, and explains the default when accession_number is omitted. It does not explicitly contrast with sibling tools, but the first sentence makes the read-text use case clear.

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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by scoping the search to roughly 10,000 SEC registrants and by specifying the returned fields, which is valuable because there is no output schema.

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 short sentences each earn their place: the first defines the action and scope, the second lists the return fields, and the third gives decision guidance for when to use the tool. There is no 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?

For a simple read-only search with one required parameter and complete schema documentation, the description covers purpose, scope, return values, and usage context. The agent has enough information to decide when to call it and what to expect back.

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%: query, limit, and response_format all have descriptions, defaults, and examples in the schema itself. The tool description does not meaningfully add parameter-level semantics beyond restating that the query can be a ticker or name, 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?

The description opens with a specific verb and resource: 'Find companies that file with the SEC' and explains the two search paths, ticker or name. It also states the exact return fields, which distinguishes it from related search tools like edgar_search_concepts and edgar_full_text_search.

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?

It gives an explicit usage condition: 'Use it when you are unsure of a ticker.' It also tells the agent that most sibling tools accept a ticker, CIK, or name directly, so the agent can skip this lookup when an identifier is already known.

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 cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context beyond those annotations by stating exactly what is returned (concept name, label, units, latest value) and what is intentionally omitted (full history) and where to get it. 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?

Two sentences get straight to the point, with front-loaded action and result. The examples are compact and the pointer to edgar_get_concept is valuable without adding noise.

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 keyword search tool, the description covers what it searches, what it returns, and what to use next. There is no output schema, so the return-field summary is sufficient. It could additionally mention response_format or edge cases, but the schema already documents those.

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%, so parameters like query, company, limit, and response_format are already fully documented there. The description reinforces the meaning of query with examples but does not need to add more parameter detail.

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 (Find), a specific resource (XBRL concepts/tags), and the matching strategy (keyword in tag name or label). It includes concrete examples and points to edgar_get_concept for full history, making it easy to distinguish from sibling tools.

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 intended use is clear: search for concepts by keyword and then use edgar_get_concept if full history is needed. It explicitly names an alternative for follow-up. It does not spell out when to prefer edgar_full_text_search or edgar_search_companies, but the context is strong enough for an agent to route correctly.

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 provide readOnly/idempotent/openWorld hints, and the description adds useful behavior beyond those annotations: data are annual, typically lag 6-18 months old, and arbitrary World Bank indicator IDs are accepted. This helps set expectations without contradicting the 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 front-loaded with the core purpose and use case, and every sentence serves a purpose. The indicator list is long and partially duplicates schema content, which slightly reduces conciseness, but the overall structure is efficient and readable.

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 read-only World Bank retrieval tool, the description covers the important decision-relevant facts: country scope, aggregate support, supported indicators, annual frequency, and lag time. It does not describe pagination or failure behavior, but the schema is thorough and no output schema exists, so this is nearly 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?

Since schema coverage is 100%, the schema already describes every parameter, so the baseline is 3. The description does add aggregate examples such as 'WLD' and 'EUU' and a sample World Bank indicator ID, but it mostly repeats the indicator list already present in the parameter schema.

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 ('Get annual macroeconomic indicators') and resource ('any country from the World Bank'), and clarifies scope with country aggregates. It clearly conveys what the tool does, but does not explicitly differentiate it from the sibling tool macro_get_series, so it falls short of a 5.

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?

It provides a concrete use context ('e.g. to compare the markets a company sells in') and explains data cadence and recency. It does not explicitly state when not to use this tool or point to alternatives, so it is clear context without exclusions.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: series are aligned by date, max_points rows are evenly sampled with the latest value always included, and defaults for dates are explained (10 years back, latest end). This goes beyond the safety profile.

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 dense but every sentence adds value: it covers purpose, usage, examples, and alternative routing in a structured way. It is front-loaded with the primary action and then expands with necessary details, with no fluff.

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 8 parameters, 4 enums, and no output schema, this description is remarkably complete. It covers what to pass, how to transform, how to aggregate, defaults, and references the sibling for discovery. An agent would have no trouble calling 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?

While the schema covers 100% of parameters, the description adds practical meaning: common series IDs (DGS10, CPIAUCSL, etc.), recommended transform for inflation, and how frequency/aggregation work together. This significantly enriches the bare schema definitions.

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 economic time series from FRED, specifies the domain (US/global), and lists common series IDs. It distinguishes itself from the sibling macro_search_series (which is for finding IDs) and other market tools.

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 users to pass 1-5 series IDs, provides guidance on transforms (e.g., 'pct_change_yoy' for inflation) and frequency aggregation, and directs users to macro_search_series for finding other IDs. This clearly delineates when to use this tool versus alternatives.

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 annotations' readOnlyHint and idempotentHint, the description discloses an important behavioral wrinkle: search coverage depends on whether the server has a FRED_API_KEY and falls back to a ~50-series catalog otherwise. This conditional data-source behavior directly affects result completeness and is exactly the kind of context annotations do not provide. It also implicitly communicates that no state is mutated, consistent with destructiveHint=false.

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 with no filler: keyword examples up front and the behavior caveat second. Every statement earns its place and the most call-relevant information is front-loaded before conditional details. Nothing extraneous is present.

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 three simple parameters fully documented in the schema and an output-free output-free output-schema absence, the description covers the key operational context: search by keyword, scale, and API-key fallback behavior. It does not describe the result payload structure or explicit next-step guidance like using macro_get_series once an ID is found. Minor gaps; almost complete for typical keyword-search usage.

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%, so the schema already documents query, limit, and response_format thoroughly. The description adds realistic keyword examples for query, but the description contributes little beyond what the schema itself states. Baseline 3 is appropriate since the schema carries the parameter-semantic burden.

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 a specific verb and resource combo—'Find FRED series IDs by keyword'—and gives concrete example keywords, making it immediately clear this tool searches economic data series IDs. The first sentence distinguishes it from sibling retrieval tools like macro_get_series by framing this as keyword discovery of IDs. The FRED-specific framing and keyword examples leave no ambiguity about its role.

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 establishes the intended use case: keyword-based discovery of FRED series IDs, with representative queries showing when an agent would pick this tool. It does not explicitly name alternatives or state when not to use it, though the sibling set of FRED retrieval tools makes the boundary mostly implicit. Without explicit when-not/alternative language, it stops one step short of a 5.

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 the tool read-only and idempotent. The description adds valuable behavioral context: amounts are split-adjusted per share, denominated in the listing's currency, and the output includes specific growth and yield metrics. 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?

The description is tightly structured: the first sentence states the core function and output, the second adds important data semantics, and the third points to a relevant sibling. Every sentence earns its place without redundancy.

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 compensates well by enumerating the key returned fields: trailing dividend and yield, payments per year, CAGR growth, consecutive increase years, yearly totals, and splits. It also clarifies currency and split adjustment, making the tool fully usable.

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%, so the schema already documents all three parameters. The description reinforces symbol format and mentions yearly totals, which relates to the 'years' parameter, but it does not add substantial meaning beyond the schema.

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 verb 'Get' and the resource: a stock's dividend and split history, with a detailed list of returned metrics. This differentiates it from siblings like market_get_stock_price and market_get_valuation, which cover price and valuation rather than dividend/split 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 provides clear context: it works for any exchange with Yahoo-style symbols, and it explicitly directs users to edgar_get_key_metrics when they need payout ratio inputs like EPS or FCF. It does not explicitly state when not to use this tool, but the use case is well scoped.

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/idempotent annotations, the description warns that the data comes from Yahoo Finance's unofficial public endpoint and may occasionally be unavailable, which is important for agent error handling. It also discloses that closes are split/dividend-adjusted and that the price table is sampled.

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 purposeful sentences with no filler: purpose and input conventions lead, return summary follows, and the source caveat closes. The examples are dense but informative, not padding.

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?

Since there is no output schema, the description's enumeration of return fields (current price, 52-week range, return over the range, max drawdown, sampled price table) is essential and mostly sufficient. Exact output shapes and behavior for invalid symbols are not specified, but an agent can still call the tool 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%, so the baseline is 3. The description adds real value for the symbol parameter by explaining suffix conventions, index formats, exchange-rate symbols, and the USD/MXN meaning. The remaining parameters are already well described by the schema.

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 a specific verb ('Get') and names both the resource and its full scope: current price and price history for tickers, indices, or exchange rates. The instrument taxonomy and examples make it clearly distinct from sibling tools like market_get_dividends or market_get_valuation.

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?

It provides clear eligibility rules: US tickers as-is, non-US tickers with Yahoo suffixes, indices with carets, and FX symbols with '=X'. It does not explicitly name sibling alternatives or exclusion conditions, but the intended use case is unmissable from the scope and examples.

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 readOnly, idempotent, and non-destructive behavior, so the burden is lower. The description adds useful behavioral context: data source, daily par yield curve, default to latest date, and fallback to the closest prior date. This goes beyond the annotations without contradicting them.

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 filler, with the most important information front-loaded: what the tool fetches, from where, and why it's useful. Every clause contributes value, and the date semantics occupy the second sentence without redundancy.

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 zero required parameters, the description covers source, purpose, default behavior, and date fallback. It does not describe the JSON output shape, but the response_format parameter and the straightforward nature of the data make this a minor gap.

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 'date' parameter by clarifying it returns the latest available date by default and the closest date on/before the requested date. This is supplemental information not fully captured in the schema 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 specifies a clear verb ('Get'), a concrete resource ('official US Treasury daily par yield curve'), the source domain (treasury.gov), and the relevant maturity range. It clearly distinguishes itself from market stock/dividend tools and macro series tools, so an agent can tell what this tool does without opening the schema.

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?

It provides a clear use case ('useful as the risk-free rate in valuations (typically the 10-year)') and explains the date behavior ('closest date on/before'). It does not explicitly name sibling alternatives or state when not to use this tool, but the context is sufficiently clear.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it explains the data sources (Yahoo price + SEC filings), the TTM calculation method (sum of last 4 quarters or fiscal year fallback), and the explicit failure condition for currency mismatches. This goes well beyond the annotations and fully discloses the tool's operational behavior.

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 with no filler. The core purpose is front-loaded in the first sentence, followed by concise TTM logic and a failure note. Every sentence adds value, and the structure is efficient for an agent to quickly grasp the tool's function.

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 no output schema, the description lists all expected outputs (market cap, EV, P/E, etc.) and explains the computation inputs and failure mode. It provides enough context for an agent to decide when to call this tool and what to expect, making it complete for a read-only calculation 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 coverage is 100%, with both parameters (company and response_format) already well-documented in the schema. The description does not add parameter-specific details beyond what the schema provides, so the baseline 3 applies. It mentions the company param's accepted forms, but that is already in the schema.

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 computes valuation multiples for US-listed SEC filers, listing specific metrics (P/E, EV/Revenue, etc.). It distinguishes from siblings like market_get_stock_price (only price) and edgar_get_financial_statement (raw fundamentals) by specifying the combined output. The verb 'compute' is specific to the resource.

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 defines the tool's scope (US-listed SEC filers, combining live price and TTM fundamentals) and notes a failure case (currency mismatch for ADRs). It does not explicitly name alternative tools or state when not to use it, but the scope implicitly excludes non-US or non-SEC entities and pure price queries, making the intended context clear.

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