AkkruData

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description goes well beyond this by disclosing caveat aggregation into _warnings, Pro+ classification blocks, pricing behavior, and the specific effect of light_weight_mode on dimensional_breakdowns. This is rich behavioral context with no contradictions.

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 well-organized, front-loading the core purpose before diving into row semantics, pricing, and output caveats. Each sentence adds useful information, though the trailing endpoint and documentation reference are slightly redundant given the schema and context.

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, the description covers the essential behavioral and output details: per-row caveats, aggregated warnings, classification availability by tier, and light-weight mode effects. Combined with the schema's limits and required fields, an agent has enough context to invoke it correctly and interpret results.

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 beyond the schema: it explains that each row can compare different fact_ids, clarifies the filing_id OR ticker+form_type+fiscal_year alternatives, and specifies that fact_ids must be non-empty. It also gives concrete meaning to light_weight_mode by naming the dropped field.

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: 'Compare specific XBRL fact_ids across multiple filings.' This clearly distinguishes the tool from siblings like compare_line_items by focusing on XBRL fact_ids, and the per-row fact_ids detail further clarifies its unique 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 gives clear context for when to use the tool: comparing fact_ids across filings, including cases where concept tagging changed between years. It does not explicitly name alternatives or exclusions, but the usage context is strong enough that an agent can infer when this tool is appropriate.

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 annotations (readOnlyHint, idempotentHint, destructiveHint). It discloses the credit/cost structure (L0–L3 tiers, 10/20/30/50 credits per line item × number of filings, itemised in credits_by_line_item), the `_resolution_level` field on each fact, the `unresolved` list per result, the `caveat` field and its aggregation into `_warnings`, the Pro+ `classification` block, and the behavior of light_weight_mode. It also explains that multi-concept matches are pre-ordered via Akkru smart ranking and that the order is a recommendation. This is rich behavioral context that annotations do not provide.

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 earns its place. It front-loads the core purpose and then covers cost, resolution levels, output shape, alternatives, and caveats. It is long, but the tool is complex (3 parameters, mixed filing identifiers, credit tiers, multiple output fields). The structure is logical, moving from what → how → output → when → caveats. Slightly over-long for a 3-param tool, but justified by the 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?

For a tool with no output schema, the description is remarkably complete. It explains the return shape (consolidated totals, one row per logical fact, fact_ids listing every position), the `unresolved` field, `caveat`/`_warnings`, `classification` for Pro+, and the effect of light_weight_mode. It also covers cost, resolution levels, and routing to alternatives. An agent has everything needed to invoke this tool correctly and interpret its results.

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 beyond the schema: it explains that filings rows can use filing_id OR ticker + form_type + fiscal_year (+ optional quarter), that form_type per row accepts 10-K/10-Q/20-F/40-F allowing mixed US/foreign issuers, that line_items must be non-empty and are resolved through L0–L3 tiers, and that light_weight_mode omits results[*].facts[*].dimensional_breakdowns. This adds real value over the schema's terse descriptions, though the schema already covers the basic structure.

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 compares the same set of line-item names across multiple filings, with specific examples (revenue, net income). It distinguishes itself from query_line_items by noting it returns consolidated totals only, and from dimensional-breakdown tools. The verb 'compare' plus the resource 'line items across filings' is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool ('Good for YoY or peer period alignment by named line items') and when not to ('for dimension slice values use the dimensional-breakdown tools or get_filing_statement per filing'). It also provides guidance on how to identify correct line-item names using list_filing_statements + get_filing_statement, and warns that multi-concept matches are pre-ordered but the order is a recommendation only. This is comprehensive usage 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 provide readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety. The description adds critical behavioral details: 28 credits debited even on failure (missing filing, no such statement, or non-SEC), and light_weight_mode for a leaner payload. 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 rich but concise, front-loading the core purpose, then identification methods, then shortcuts and error behavior. It could be slightly shorter by omitting the API endpoint and documentation reference, but overall it is efficient and each sentence adds value.

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 has no output schema but is a fetch operation with 6 parameters and multiple failure modes, the description covers all necessary usage instructions: identification alternatives, error conditions, jurisdiction limits, credit cost, and performance option. 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?

The schema already covers 100% of parameters with detailed descriptions (e.g., ticker examples, quarter formats, filing_id source). The description adds context on parameter combinations (filing_id OR ticker+fiscal_year) and notes light_weight_mode saves context, but mostly reinforces schema info. Baseline of 3 applies given high schema coverage.

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 it returns the filing's Balance Sheet with extracted line items, values, and periods. It identifies the filing via filing_id or ticker+fiscal_year and mentions the exact API endpoint. It also positions itself as a shortcut for get_filing_statement with a specific statement type, distinguishing it from siblings like get_income_statement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says it is a fixed shortcut for get_filing_statement(statement_type='Balance Sheet') and notes it does not take role_label or statement_type, preventing misuse. It also states it returns 404 when the filing has no balance sheet, and is only for SEC filings, with other jurisdictions coming soon. This gives clear when-to-use and when-not-to-use 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 non-destructive behavior. The description adds useful context beyond that: flat 148-credit cost, Starter plan requirement, Pro+ requirement for formula_override, and the specific POST endpoint. 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 dense but information-rich: the metric list is necessary for tool selection, and cost, plan requirements, and endpoint are each relevant. It lacks sectioning and reads as a run-on, but 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 7-parameter tool with no output schema, the description covers the metrics returned, cost, plan constraints, and endpoint. The surrounding schema already documents parameter details, so nothing critical for making the call 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 baseline is 3. The description adds value by listing the exact metric ids that formula_override would be keyed by and by explicitly noting formula_override requires Pro+, which is not stated in the schema itself.

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 the specific resource (cash-flow metrics) and enumerates all 18 returned metrics, so an agent knows exactly what this tool offers. It also distinguishes itself from the related profitability tool by noting that fcf_margin also appears in get_profitability_metrics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving calculated cash-flow metrics and notes the fcf_margin overlap with get_profitability_metrics, which is a weak routing hint. However, it does not explicitly say when to choose this tool over other metric tools like get_metrics_bundle or get_metrics_subset, nor does it state 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds substantial behavioral context: the 28-credit cost debited even when the filing is missing, has no cash flow statement, or is not an SEC filing; the 404 response for missing statements; the light_weight_mode payload reduction; and the SEC-only availability. 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 dense but front-loaded with the core purpose, and every substantive sentence earns its place: purpose, identification, relationship to get_filing_statement, error behavior, cost, light mode, and jurisdiction. It is slightly long, and the trailing 'POST /api/v1/data/cash-flow-statement; FINANCIAL_API_DOCUMENTATION.md' is somewhat redundant with the schema/title, but the overall structure is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, idempotent fetch tool with 6 optional parameters and no output schema, the description is complete: it covers identification modes, required-versus-optional combinations, error semantics (404), cost implications, jurisdiction restrictions, and a payload-lean option. An agent has everything needed to invoke it correctly without additional documentation.

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 each parameter. The description adds value beyond the schema by explaining the identification modes: 'Identify the filing with filing_id, or ticker + fiscal_year (+ optional quarter)' and clarifying that quarter is 'only needed to disambiguate quarterly filings.' This gives agents a decision procedure the schema alone doesn't provide.

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: 'Return the filing's Cash Flow Statement — its extracted line items with values and periods.' It clearly distinguishes this from sibling statement tools (balance sheet, income statement) by naming the statement type, and further differentiates itself from get_filing_statement by framing itself as a fixed shortcut that 'does not take role_label or statement_type.'

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 names the alternative get_filing_statement and explains the relationship: 'A fixed shortcut for get_filing_statement(statement_type='Cash Flow Statement')' with the key exclusion that it does not accept role_label or statement_type. It also gives identification requirements (filing_id vs ticker + fiscal_year) and the SEC-only limitation. It doesn't exhaustively enumerate when to use other statement tools, but the main routing decision is clearly covered.

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, idempotentHint, destructiveHint), the description discloses several non-obvious behaviors: it 'returns 404 when the filing has no comprehensive-income statement,' costs '28 credits, debited even when the filing is missing, has no such statement, or is not an SEC filing,' and states that light_weight_mode reduces the payload. These are important operational details an agent would not infer from the schema or 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 moderately long but every sentence carries unique information: purpose, identification, shortcut relationship, 404 behavior, jurisdiction, cost, light_weight_mode, and endpoint. It is front-loaded with the core purpose and follows a logical order. The trailing 'POST ...' and documentation pointer are arguably extra but not 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 six parameters and no output schema, the description covers identification methods, error behavior, cost, jurisdiction, and payload mode. It gives a high-level view of the response ('line items with values and periods') but doesn't detail response structure or potential pagination. Given that the schema covers all parameters and annotations cover safety, this is a complete-enough definition for an agent to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds relational semantics: it explains that filing_id is an alternative to ticker + fiscal_year, that quarter is optional, and that light_weight_mode yields a leaner payload. This grouping and conditionality is not evident from individual parameter descriptions alone, pushing the score above baseline.

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: 'Return the filing's Statement of Comprehensive Income — its extracted line items with values and periods.' It further distinguishes itself from siblings by explicitly stating it is a 'fixed shortcut for get_filing_statement(statement_type='Comprehensive Income')' and that it does not take role_label or statement_type, so an agent can immediately tell it apart from get_filing_statement and get_income_statement.

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 explicit identification guidance (filing_id or ticker + fiscal_year) and clarifies the shortcut relationship to get_filing_statement. It also gives a clear exclusion: 'Available for SEC filings only — other jurisdictions coming soon,' and warns about the 404 case. However, it doesn't explicitly contrast with get_income_statement or say 'use this when you need comprehensive income instead of the general statement tool,' though that is implied by the shortcut phrasing.

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, the description discloses several important behaviors: recursion defaults to true and can be disabled, pricing is computed from the returned slice fact count, and a 404 still costs 10 credits. It also explains that slice facts are grouped by XBRL axes. This adds significant context beyond the readOnly/idempotent hints.

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 information-dense and front-loaded with the core behavior, then scope, recursion, pricing, and error semantics. The endpoint and documentation reference at the end are slightly redundant, but nearly every clause adds useful operational 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?

The description covers the key call-time decisions: scope, recursion, pricing, and the 404 case. Since there is no output schema, the description explains the return shape at a conceptual level (consolidated fact plus grouped slice facts) but does not detail the response fields. This is sufficient 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%, so the schema already documents every parameter. The description restates the filing_id-vs-ticker scoping and recursive default, but it does not add meaningful new detail about parameter formats, allowed values, or relationships beyond what the schema provides. 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 the specific verb and resource: it returns one consolidated fact plus every slice fact it breaks down into. It also clarifies the grouping principle (by XBRL axes) and the fact_id-based scope, which separates it from the sibling get_dimensional_breakdown_by_line_item.

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 invoking the tool: it specifies the two valid scoping forms (filing_id OR ticker + fiscal_year), optional quarter, and the recursive flag with its default. It does not explicitly name alternatives or state when not to use this tool, so it falls 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 cover readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context: matches are pre-ordered via Akkru smart ranking but the order is a recommendation only, and duplicate_root_fact_ids lists alternative fact_ids for the same logical fact. This goes beyond annotations and helps the agent 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?

The description is a single dense sentence but remains readable and front-loads the core purpose. It packs in scoping, defaults, pricing, and an API reference without excessive wordiness. It could be split into two sentences for readability, but every clause adds information and nothing is redundant.

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 7 parameters and no output schema, the description must convey return structure and usage constraints. It explains that each match is a root with axis-grouped slice facts and mentions duplicate_root_fact_ids, giving an agent enough to interpret the response. It also covers scoping and pricing. It is not exhaustive (e.g., no detailed example of the response JSON), but it is sufficiently complete 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%, so the baseline is 3. The description adds meaning by explaining the alternative scoping relationships (filing_id vs ticker + fiscal_year), the default for recursive, and the purpose of duplicate_root_fact_ids (though it's an output, not a param). It clarifies how parameters interact, which is useful beyond the individual field 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 states a specific verb ('Resolve') and resource ('line-item name') and clearly defines the output ('dimensional breakdown of every consolidated fact'). It distinguishes itself from the sibling get_dimensional_breakdown_by_fact_id by explicitly scoping to line items, leaving no ambiguity about what this tool does.

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 scoping rules ('filing_id OR ticker + fiscal_year (+ optional quarter)') and notes that recursive defaults to true. It does not explicitly name alternatives, but the scope and prerequisites are well-defined, and the note about reviewing multi-concept matches gives usage advice. Slightly short of an explicit 'use this when' statement.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds valuable operational context beyond that: the fixed credit cost, the HTTP endpoint, the documentation reference, and plan-level authentication requirements. Mentioning that formula_override is Pro+ is especially useful before invocation.

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 two tightly packed sentences with no filler: it front-loads the returned metrics, then gives cost, endpoint, documentation, and plan restrictions. Every clause adds actionable information.

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, this is complete: it enumerates the exact output metrics, gives the endpoint, cost, documentation path, and plan requirements, while the input schema fully covers all 7 parameters. Even without an output schema, an agent has enough context to understand inputs and expected results, including the lighter payload option.

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 already has a detailed explanation, including defaults, constraints, and semantic behavior (e.g., as_of_date cutoff, current_price limitations). The description's plan-requirement note for formula_override largely restates what the schema already says, so it adds no meaningful parameter guidance 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 states the exact resource—'Turnover ratios and working-capital days'—and enumerates all 10 returned metrics, making it immediately distinguishable from sibling metric tools like get_profitability_metrics or get_valuation_metrics. It also names the concrete endpoint, POST /api/v1/metric/efficiency, so the operation is unambiguous.

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 relevant usage constraints, including the flat 148-credit cost and the plan requirements ('Requires the Starter plan or higher; formula_override requires Pro+'). However, it does not explicitly explain when to choose this tool over alternatives such as get_metrics_bundle, get_metrics_subset, or other metric-specific tools; the usage context is implied by the metric names rather than 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=true, idempotentHint=true, destructiveHint=false, and the description is fully consistent with them — no contradiction. The description adds substantial value beyond annotations: SEC-only availability, 404 when no equity statement exists, the 28-credit cost debited even on failure/missing/SEC-exclusion, and the light_weight_mode tradeoff. This is rich behavioral 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?

Dense but front-loaded with the core purpose in the first clause, followed by identification, scope, cost, and endpoint. Every sentence is functional — no filler or repetition of schema content. Slightly long, but each clause earns its place given the failure modes and cost disclosure it must carry.

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 must explain the return value, and it does ('extracted line items with values and periods'). It covers identification, failure mode (404), scope (SEC-only), cost, and the leaner-payload option. Adequate for a read-only data fetch; the only unstated item is the precise response envelope, which is minor.

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 every parameter already has a meaningful description, so the baseline is 3. The description adds value beyond the schema by explaining the filing_id-vs-(ticker+fiscal_year) identification tradeoff and clarifying the light_weight_mode effect ('drops the most verbose nested fields'). Minor but genuine additive value over 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?

Opens with a specific verb+resource: "Return the filing's Statement of Stockholders' (or Shareholders') Equity — its extracted line items with values and periods." It names exactly what is returned and clearly distinguishes this from the many sibling statement tools by stating it is a 'fixed shortcut for get_filing_statement(statement_type='Stockholders Equity')' and by omitting role_label/statement_type.

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 prescribes how to identify the filing (filing_id OR ticker + fiscal_year + optional quarter), declares the SEC-only scope, states the 404-on-missing behavior, and names the exact alternative (get_filing_statement) it is a shortcut for. No inference is required to decide when to use this tool.

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 readOnlyHint, idempotentHint, destructiveHint=false. The description adds behavior beyond annotations: cost of 30 credits per call, that 404 and 403 are still charged, plan requirement (Starter or higher), as_of_date behavior (404 EVENTS_FILING_NOT_YET_FILED), and the _warnings field for omitted sections/differences/unresolved amendments. This is rich, valuable transparency beyond 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 dense but efficiently structured: opening sentence, then field-by-field guidance, then cost/error/plan notes. Every sentence carries useful information. It could be slightly more scannable with bullet points, but it is appropriately sized and front-loaded with the core 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?

The description covers purpose, selection source, parameter effects, cost, errors, plan requirement, warnings, and endpoint. With no output schema present, it doesn't describe the return value shape beyond mentioning section summaries, source links, and history, which is adequate. The only minor gap is not describing what the response object looks like structurally, but the description is otherwise complete for a correctly-callable 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%, so baseline is 3, but the description adds meaning beyond the schema: it explains the effect of items ('selects sections only; filing metadata and amendment history remain complete'), that include_original_raw_text returns raw_text at no extra cost, that include_exhibits includes attachments too, and that as_of_date yields a 404 if not yet filed. This is meaningful value 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 states a specific verb and resource ('Read one corporate event filing') and distinguishes it from siblings by requiring an id from list_event_filings or search_events. It also clarifies the resource is a single filing, differentiating it from list/compare/search siblings.

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: id comes from list_event_filings or search_events, and it explains optional behaviors (items, include_original_raw_text, include_exhibits, as_of_date). It doesn't explicitly say when NOT to use it vs alternatives, but the source-id requirement plus the detailed field behavior makes usage fairly 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?

Beyond the readOnlyHint/idempotentHint annotations, the description adds important operational context: the URL is short-lived and using the tool costs 300 credits. This helps the agent set user expectations and avoid unnecessary calls, though it does not mention what happens if has_excel is false or the endpoint errors.

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: it states the purpose, cost, usage condition, required parameter, precondition, and endpoint in a few sentences without redundancy. 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?

For a single-parameter tool with no output schema, the description is sufficient: it identifies the input source, the precondition (has_excel), the cost, and the nature of the return value (short-lived download URL). An agent has enough information to invoke 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?

Schema description coverage is 100%, and the parameter description already explains that filing_id is a numeric ID from list_filings and to check has_excel first. The tool description only repeats this information without adding new semantic detail, 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 clearly states the action: obtaining a short-lived download URL for the SEC-derived Excel attachment for one filing. This distinguishes it from sibling data-retrieval tools like get_filing_facts and get_filing_statement, which return structured data rather than a file download.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use it only when the user needs the spreadsheet, and instructs the agent to check has_excel from list_filings first. This gives clear when-to-use and preconditions, and references the sibling list_filings as the source for validation.

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, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context: light_weight_mode drops dimensional_breakdowns and is charged identically, form_type defaults to 10-K and varies by jurisdiction, and the equivalence to POST /api/v1/data/facts. 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?

The description is dense and packed with necessary details, front-loading the core purpose and then layering usage guidance, parameter specifics, and a pointer to documentation. While it is longer than some, every sentence earns its place and there is no fluff. It could be slightly more compact but is well-organized.

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 and no output schema, the description covers identification methods, defaults, edge cases (foreign/Korean forms), the light_weight_mode option, and charging note. It also points to external documentation for tiers/limits. Nothing essential for correct selection and invocation 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?

Although schema description coverage is 100%, the description adds meaning beyond the schema: fact_ids must be 1–500 items each ≤128 chars and are for line-item names (pointing to query_line_items); light_weight_mode's effect on the payload; form_type defaults and jurisdiction-specific values; and the mutual exclusivity of filing_id vs ticker+fiscal_year. This significantly aids correct invocation.

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 begins with a specific verb and resource: 'Fetch specific XBRL facts for a single filing by fact_id.' It clearly differentiates from query_line_items by stating that line-item-name queries (revenue, net income, etc.) should use that tool instead, which prevents confusion among the large sibling set.

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 explicitly names the alternative tool (query_line_items) and the condition for using it. It also details how to identify the filing (filing_id or ticker + fiscal_year + optional quarter), and provides guidance on form_type for foreign issuers and Korean filings. This is comprehensive 'when-to-use' 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?

Beyond the readOnly/idempotent/destructive annotations, the description discloses mutually exclusive lookup modes, tiered credit costs, a 404 when statement_type yields zero matches, response shape, and light_weight_mode payload changes. It even notes that light_weight_mode is charged identically, which an agent cannot infer from annotations or 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?

The description is long but information-dense and front-loaded with the core behavior and differentiation. Some content repeats schema parameter descriptions (mutual exclusivity, light_weight_mode), and the trailing endpoint/file pointer adds noise, but the structure is transparent and scannable.

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-mode, 8-parameter tool with no output schema, the description supplies the response shape, lookup semantics, filing scoping rules, credit implications, and sibling tool routing. Nothing an agent needs to decide between modes or construct a valid request 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?

Although schema coverage is 100%, the description adds essential cross-parameter meaning: exactly one of role_label/statement_type, filing_id OR ticker+fiscal_year scoping, form_type defaults and DART mapping, and canonical statement names. It also enriches role_label with a real-world example (AAPL) and explains statement_type's SEC-only availability.

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+resource ('Return extracted financial statement block(s) for a filing') and immediately distinguishes this general tool from five dedicated siblings (get_income_statement, get_balance_sheet, etc.). It also names the companion discovery tool list_filing_statements, making the tool's role unambiguous.

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 explicitly routes usage: use the five dedicated tools for main statements, use list_filing_statements first to discover valid role_label/statement_type values, and use role_label for non-SEC filings where statement_type is unavailable. This is direct when-vs-alternative guidance with no reliance on inference.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the flat 148-credit cost, the plan gating, and the fact that formula_override requires Pro+. It also notes that current_price omission yields a hint instead of a value, which is useful beyond the 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?

The description is compact and front-loaded with the metric list, then cost, endpoint, and plan requirements. It packs useful information into two sentences without redundancy. Minor deduction for the dense metric list, but it 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 read-only metrics tool with 100% schema coverage and no output schema, the description covers cost, endpoint, plan gating, and metric scope. It does not describe the response shape, but the absence of an output schema and the read-only annotations make that less critical. The main gap is not naming sibling metric tools for comparison, but the metric list largely compensates.

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 7 parameters thoroughly. The description adds the flat cost and plan gating but does not add parameter-level meaning beyond what the schema provides. 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'), a resource ('financial health metrics'), and enumerates the 11 metrics included, which clearly distinguishes it from sibling metric tools like get_profitability_metrics or get_valuation_metrics. The endpoint and plan requirements add further specificity.

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 states the plan requirement (Starter or higher) and the Pro+ requirement for formula_override, giving clear conditions for use. It does not explicitly contrast with sibling metric tools, but the metric list and endpoint make the use case clear enough.

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 non-destructive behavior, so the description doesn't need to restate safety. It adds useful operational context beyond annotations: flat 148-credit cost, the specific POST endpoint and documentation file, and Starter/Pro plan gates. It doesn't describe output shape, but that gap is not a contradiction.

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 front-loads the key fact ('Growth rates (15 metrics)') and packs scope, cost, endpoint, documentation, and plan requirements into a compact block. The long metric enumeration is justified because it defines exactly what this tool covers, though the trailing semicolon-separated operational details feel slightly cramped.

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 100% schema coverage and read-only annotations, the essential parameter semantics are fully supplied elsewhere. The description doesn't explain response format or interactions between the seven parameters, and since there is no output schema, some of that burden falls on the description. The 15-metric list implies what the output contains, so the gap is noticeable but not severe.

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 detailed parameter descriptions for as_of_date, current_price, current_fx_rate, metric_group_id, formula_override, light_weight_mode, and accept_suggested_formula. The tool description adds only a plan-level note about formula_override, which is already reflected in 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 the resource ('Growth rates') and enumerates 15 specific metrics, leaving little doubt this is the growth-metrics retrieval tool among the many get_* siblings. It relies on the title for the verb but the metric list and endpoint make the purpose unambiguous.

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 explicit metric list lets an agent infer this tool is for growth rates and rule out profitability, valuation, or cash-flow metrics. However, it never states when to choose this over alternatives like get_metrics_bundle or get_profitability_metrics, and it provides no exclusion guidance. The cost and plan notes are prerequisites, not usage direction.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral details: it returns 404 when the filing has no income statement, debits 28 credits even on failure or non-SEC filings, supports light_weight_mode, and specifies the API endpoint. This goes beyond what annotations alone provide.

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 information-dense yet well-structured, leading with the core purpose, then identification methods, shortcut relationship, error behavior, scope, cost, and options. Every sentence contributes essential facts; there is no fluff. It remains a single paragraph but is easy to scan due to logical flow.

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 explaining return values — it states the response contains 'extracted line items with values and periods.' It also covers error cases, scope limitations, credit cost, and the optional payload mode. Given the tool's complexity (6 params, no output schema), this is adequate, though a more detailed response shape might be expected for a financial statement tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter already has a description. The tool description adds meaning by clarifying the identification logic (filing_id OR ticker + fiscal_year, with optional quarter) and explaining the purpose of light_weight_mode ('leaner payload... saves context'). This supplements the schema without redundancy.

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 it returns the filing's Income Statement with extracted line items, values, and periods, and specifies identification methods (filing_id or ticker + fiscal_year). It distinguishes itself as a fixed shortcut for get_filing_statement with a specific statement type, and the sibling list includes other statement tools, so an agent can easily tell this apart from get_balance_sheet or get_cash_flow_statement.

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 explains it is a shortcut for get_filing_statement(statement_type='Income Statement') and notes it does not accept role_label or statement_type, implying the general tool is for other statements. It also mentions the SEC-only scope and the 404 case, but does not explicitly say 'use this for income statements, use get_balance_sheet for balance sheets' — though the shortcut nature and sibling names provide adequate context.

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 cover read-only/idempotent/non-destructive safety, and the description goes well beyond by disclosing response-side behavior: non-existent ids land in missing_ids, out-of-plan-scope ids in restricted_ids, 404 OWNERSHIP_HOLDING_NOT_FOUND only when none exist, and the credit cost formula ceil(n/5) x 10 (max 200). This gives the agent accurate expectations for error and cost 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?

Four dense sentences, front-loaded with the operative purpose and companion relationship, then error behavior, cost, and endpoint reference — every sentence earns its place and nothing is redundant.

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, it covers the return shape (full rows nested under filings), error/edge cases, and cost, which is enough to call it correctly. It falls just short of fully specifying the holding-row fields or the shape of the missing/restricted lists, but the description is largely 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 coverage is 100% with all three params documented, so the baseline is 3; the description adds genuine extras — the deduplicated-id count used for credit calculation and the missing/restricted id classification, which clarify what actually happens to invalid or out-of-scope holding_ids beyond the schema's '1-100' range note.

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 and resource (fetch full holding rows by holding id, up to 100, nested under filings) and explicitly names its companion get_initial_holding_stats, distinguishing it from the many list/search siblings. The title reinforces the Form 3 by-id scope.

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 frames when to use it: as the companion of get_initial_holding_stats, when you hold holding_ids from that tool's list and want the full rows behind a figure. However, it never names alternatives for other scenarios (e.g., search_initial_holdings or list_initial_holdings), so there are no explicit when-not/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 mark this as read-only and non-destructive, and the description goes well beyond them: it warns that non-derivative and derivative totals use different units and must not be added, that filing counts include filings with no holdings, that _warnings must be read before using totals, that out-of-coverage tickers return 403 and are still charged, and it states credit costs. This is rich behavioral disclosure.

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 and front-loaded with the core purpose and metric list. It is long, but nearly every clause earns its place given the tool's complexity; minor extras like the POST path and documentation filename are slight overhead rather than significant bloat.

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 11 parameters, no output schema, and no enums, the description is unusually complete: it names the returned aggregate fields, explains unit incompatibility, warns about anomaly/amendment behavior, identifies the provenance mechanism, and discloses error and pricing behavior. An agent has enough context to invoke the tool 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 the baseline is 3; the description adds value by explaining that the date fields define a filing-date window, that ticker out-of-coverage has a charge implication, and that holding_ids are paged and fetched with a sibling tool. This is meaningful enrichment beyond the schema, though not exhaustive for every parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: it aggregates over Form 3 filings in a filing-date window and enumerates the exact computed metrics. It also distinguishes itself from the row-level sibling by noting that holding_ids should be fetched with get_initial_holdings_by_id, so an agent can tell aggregate from detail 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 description provides clear context: use this tool for aggregate Form 3 statistics within a filing-date window, and use get_initial_holdings_by_id to fetch the underlying holding rows referenced by holding_ids. It does not explicitly enumerate when not to use related list/search tools, but the aggregate-vs-row distinction is strong enough to guide 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?

Annotations already mark the tool as read-only and idempotent, but the description adds substantial behavioral detail beyond that: method-dependent key naming, zero-cash counting, adjusted-basis share totals, corporate action handling, _warnings semantics, plan history limits, 403 PLAN_TIER_INSUFFICIENT_COVERAGE behavior, and credit cost. 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 dense but every clause carries operational weight: purpose, paging, requirement, key naming, edge cases, warnings, plan limits, errors, and cost. It front-loads the main purpose and pagination before caveats, with no filler or repeated schema content.

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 13-parameter tool with no output schema, this description is remarkably complete. It covers response-relevant fields (transaction_ids, ids_total, ids_has_more, _warnings, start_date_applied, as_of_date_applied, corporate_action_crossing, corporate_actions), error behavior, plan limitations, and pricing, so an agent can invoke it correctly without external documentation.

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 cross-parameter information such as how method changes response key names (acquired/disposed vs bought/sold), how ids_page/ids_page_size control transaction_ids paging, and the sibling's 100-ids-per-call cap. This goes beyond the schema's individual field 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 opens with a specific action and resource: 'Totals over one company and/or one insider, plus transaction_ids for every contributing row.' It clearly frames this as the aggregation counterpart to get_insider_transactions_by_id, so an agent can distinguish it from sibling tools without opening schemas.

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 tells the agent to feed transaction_ids to get_insider_transactions_by_id for detail and documents the paging mechanism and the 100-id limit of the sibling. It also states the prerequisite combination of ticker and/or insider_cik. It does not explicitly enumerate when not to use this versus other aggregate siblings, but the detail-vs-aggregate routing is 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 indicate read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral detail beyond that: deduplication, _warnings, missing_ids, restricted_ids, 403 semantics, credit cost formula, and endpoint reference. This is far beyond the 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?

The description is dense but every sentence adds value, covering usage, edge cases, and cost. It is front-loaded with the core relationship to get_insider_stats. The length is justified by the tool's complex behavior, though it could be slightly better organized.

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 complexity and the absence of an output schema, the description covers key edge cases, error conditions, and credit costs. It references the output shape via list_insider_transactions, which is adequate, though a bit more detail on the normal successful response payload would make it fully self-contained.

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 page, page_size, and transaction_ids. The description adds useful context that transaction_ids come from get_insider_stats, but it does not need to compensate for missing schema information.

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: fetch insider transactions by id. It clearly distinguishes itself as a 'detail companion to get_insider_stats' and references the same shape as list_insider_transactions, so an agent can differentiate it from siblings.

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 explicit context for when to use it: after get_insider_stats returns transaction_ids. It also explains edge-case behavior for missing and restricted ids. It does not explicitly state when not to use it versus alternatives, but the companion relationship is a strong usage signal.

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 mark the tool read-only and idempotent; the description adds genuinely valuable behavior beyond those hints: 404 behavior with error code, flat 30-credit charge even on 404, null quarter-over-quarter fields for the earliest quarter, response layout, and EDGAR URL semantics. 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 longer than average but front-loaded with the core purpose and each section adds operational value: anchoring, response shape, null behavior, cost, and endpoint. The endpoint path and documentation file reference are slightly redundant, but not enough to hurt usability.

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?

There is no output schema, so the description correctly carries the burden of explaining return values: top-level manager fields, per-quarter row fields, and null behavior for the earliest quarter. It also covers error behavior, cost, and sort default, leaving the agent with what it needs to select and 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 coverage is 100%, so the baseline is 3. The description adds useful extra meaning for cik/name by explaining that an ambiguous name causes a 404 and recommending CIK as the reliable anchor, and it reinforces sort_order's newest-first default. Page and page_size semantics are left to the schema, but the additional guidance raises the score.

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: 'One institutional manager's 13F history' and explicitly contrasts its scope with search_institutional_holdings ('the same quarter rows ... for one manager'). It is not a tautology and clearly differentiates this tool from its sibling.

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 clear operational guidance: anchor with exactly one of cik/name, query by CIK because several managers can share similar names, and expect 404 when no single manager matches. It references search_institutional_holdings as the row-format source, though it stops short of explicitly saying 'use search_institutional_holdings when you need multiple managers.'

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?

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds substantial behavioral context: the shape of the quarter header, the meaning of _warnings, null deltas when no prior quarter exists, the 30-credits-per-page cost, and the fact that 404s are still charged. This goes well beyond 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 dense but front-loaded with the core purpose, then efficiently organizes row types, weight formatting, warnings, costs, and errors. A few trailing references like "The URL opens the filing's EDGAR index page; see the files listed there for full details" are less actionable and slightly dilute an otherwise high-value definition.

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 complex tool with 12 parameters and no output schema, the description is exceptionally complete: it covers the response structure, row-type distinctions, warning cases, null-delta behavior, credit costs, error statuses, the HTTP endpoint, and external documentation. An agent has enough context to invoke the tool correctly and interpret likely failures.

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 describes every parameter with 100% coverage, including the cik/name exclusivity, type values, quarter format, and sort options. The description adds thematic context around row types and output fields, but it does not meaningfully extend the meaning of the input parameters 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 immediately specifies "One manager x one calendar quarter: the 13F holdings detail rows", naming the exact resource and granularity with a clear verb implied by the tool name. It also details the three row kinds, which distinguishes the tool from search-oriented or aggregate institutional tools among the siblings.

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 scope is clearly implied by "One manager x one calendar quarter" and the 13F-holdings context, and the description explains the three row types and warning semantics. However, it never explicitly names when to use this tool versus siblings like search_institutional_holdings or get_initial_holdings_by_id, nor does it state when not 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 only cover the safety profile (read-only, idempotent, non-destructive), so the description carries the burden of behavioral disclosure — and it delivers. It discloses a specific error code (404 OWNERSHIP_SECURITY_NOT_FOUND), credit costs per mode (30 flat / 40 grouped) and that a 404 is still charged, multi-CUSIP ticker matching, and the unpaged behavior of grouped mode. This is exceptional context beyond what annotations provide.

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 purpose and anchoring constraints, and each sentence carries real information: error behavior, securities block contents, output modes, pricing, and sibling relation. It runs slightly long and ends with noise — the raw 'POST /api/v1/...' endpoint, a doc-file reference, and an ambiguous trailing sentence ('The URL opens the filing's EDGAR index page...') whose antecedent is unclear. Minor clutter in an otherwise dense, well-structured definition.

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 10-parameter, dual-mode tool with no output schema, the description is remarkably complete: input anchoring, unknown-security error, credit costs, pagination differences between modes, output shape for both modes, and the relationship to get_institutional_portfolio are all covered. The few gaps — per-row column details delegated to the sibling's schema and no routing guidance versus search_institutional_holdings — are minor relative to 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%, so the baseline of 3 applies; the tool description largely paraphrases the schema ('anchored by exactly one of cusip / ticker', group_by_quarter returning 'holders, total_shares, total_value over live stock rows — unpaged'). Its modest added value is organizing which parameters narrow flat mode (quarter, type, activity, sort_by) versus which switch modes, but it introduces no genuinely new per-parameter meaning.

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-scope statement: 'One security's 13F holder rows across managers, anchored by exactly one of cusip / ticker.' It explicitly differentiates from the sibling get_institutional_portfolio ('returns the same detail rows as get_institutional_portfolio with manager_cik / manager_name added'), so an agent can tell these apart without opening schemas. The title and description agree, and the security-anchoring constraint is front and center.

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?

Clear context is established: this is the security-anchored counterpart to the manager-anchored get_institutional_portfolio, and the two output modes (flat detail vs grouped aggregates) are explained with their narrowing parameters. What's missing is an explicit exclusion — e.g., no guidance on when the sibling search_institutional_holdings would be the better choice for cross-security or text-based searches. It names the relationship but stops short of full when-not-to-use routing.

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, idempotentHint=true, and destructiveHint=false, and the description adds context beyond that: it states the response includes both filing-date and realtime price blocks, that the realtime block returns a hint when current_price is omitted, and discloses credits (148) and the exact endpoint (POST /api/v1/metric/all). This gives an agent a clear model of what happens on invocation without contradicting 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 long but densely packed; it front-loads the core purpose and then methodically covers distinctions, response behavior, prerequisites, and each optional parameter with constraints. While it could be tightened, every sentence carries useful information and the structure is logical. It earns a 4 rather than a 5 because of its length, though it is not verbose.

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 the tool having 7 parameters and many siblings, the description covers the critical context: what the tool returns, how to obtain the required metric_group_id, cost, endpoint, plan requirements, and parameter-specific behavior. Since there is no output schema, the description also gives a useful note about response composition (both price blocks and the hint behavior). It leaves no obvious gap an agent would need to resolve before 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?

Schema coverage is 100%, so the baseline is 3, but the description adds value by explaining the purpose and behavior of parameters beyond their schema descriptions. For example, it explains that current_price is 'supply to compute realtime price-sensitive ratios' and that omitting it 'receive a hint instead', and that light_weight_mode is meant to 'strip per-metric audit fields to reduce payload size'. It also frames formula_override as 'for user-formula metrics (per API rules)', which is helpful context not found in the schema alone.

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: 'Return the full metrics bundle for one metric_group_id' and clarifies it covers 'all computed ratios and line-backed metrics for that filing-period snapshot.' It clearly differentiates from siblings by stating these are 'precomputed metrics, not XBRL facts' and explicitly names query_line_items and get_filing_facts as the alternative for line-item values, plus get_metrics_bundle_filing_date for filing-date-only needs.

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 when-to-use and when-not-to-use guidance: directs users to call list_metric_snapshots first to obtain metric_group_id, tells them to use query_line_items or get_filing_facts for line-item values, and says to call get_metrics_bundle_filing_date if only the filing-date computation is needed. It also includes plan-level prerequisites (Starter or higher, Pro+ for formula_override) which helps an agent decide if it can invoke 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=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: unsupported parameters are ignored with a warning, the endpoint path is given, credit cost is stated, and plan requirements are disclosed. It doesn't describe the response shape, but with no output schema and read-only annotations, the description carries the behavioral burden well.

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 well-organized, front-loading the key distinction from get_metrics_bundle and the unsupported-parameter warning. It packs endpoint, credits, plan requirements, and parameter notes into a compact block. Slightly long, but 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?

For a read-only, idempotent metrics tool with 100% schema coverage, the description covers the essential context: what it returns, what it doesn't accept, when to use it, the endpoint, credits, and plan requirements. The only notable gap is the lack of any description of the response structure, but since there is no output schema and the tool is a variant of get_metrics_bundle, an agent can infer the response shape from the sibling.

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 five parameters. The description adds context for light_weight_mode (strips audit fields to reduce payload) and notes formula_override requires Pro+, but these are minor additions over 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 clearly states the tool returns the filing-date price-sensitive block from get_metrics_bundle, with no realtime computation. It names the sibling tool it is not (get_metrics_bundle) and explicitly says current_price/current_fx_rate are not accepted, so an agent can distinguish it from the regular bundle 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?

The description gives explicit when-to-use guidance: use this when you don't need today's market price, for historical filings, batch loads, or when current stock price is irrelevant. It also names the alternative (get_metrics_bundle) and states the condition for choosing it (when realtime metrics are needed).

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, but the description adds substantial behavioral detail beyond that: the cost equivalence (same 148 credits), partial success with error listing (_metric_name_errors and _supported_metric_names), plan-level requirements for formula_override, and the effect of light_weight_mode. 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 dense but every sentence adds value: scope, timing, partial success, flags, endpoint, and plan requirements all in one paragraph. It is front-loaded with the primary purpose and usage, and no filler or redundancy exists.

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 8 parameters (2 required) and no output schema, the description covers the essential aspects: what it returns, how errors surface, optional flags, plan gates, and a cross-reference to a sibling. For an agent that needs to call this correctly, nothing crucial 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?

Although schema description coverage is 100%, the description enriches several parameters: metric_names is explained with a catalog example and contrast to non-catalog labels, light_weight_mode is contextualized ('strip per-metric audit fields'), and formula_override has a concrete example plus a plan requirement. This exceeds the baseline 3 by adding actionable semantics.

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 ('Fetch'), a concrete resource ('computed metrics'), and scopes it to a single metric_group_id. It explicitly distinguishes itself from get_metrics_bundle by its purpose ('keep the response small when you already know the names'), which clearly differentiates it from the sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool ('when you already know the names') and references the sibling get_metrics_bundle, implying when the alternative is preferable. It also clarifies partial success behavior and that the same flags as get_metrics_bundle apply, giving the agent enough context to decide and invoke 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 mark this read-only/idempotent; the description adds substantial non-obvious behavior: plan-tier truncation with `_warnings`, 403 PLAN_TIER_INSUFFICIENT_COVERAGE, 400 METRICS_UNSUPPORTED_FOR_<jurisdiction> with no credits charged, and plan requirements for formula_override. It also clarifies jurisdiction-specific form-type coverage. 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 dense but front-loaded: purpose and use case appear in the first two sentences before optional parameters and error handling. It is long because the tool is complex, and nearly every sentence carries operational information; minor redundancy with schema parameter descriptions keeps it from a 5.

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 12-parameter tool with no output schema, it covers required input, defaults, paging, date filters, plan limits, error codes, and jurisdiction caveats. It does not detail the response shape beyond paging and `_warnings`, but the operational guidance is sufficient to invoke 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 covers all 12 parameters, so baseline is 3; the description adds value by explaining period_type's form-type implications (10-K/20-F/40-F vs 10-Q, Korean DART equivalence), light_weight_mode's effect on audit fields, and plan gating for formula_override. This goes beyond the schema's own 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 opens with 'Time series of metrics for a ticker across many periods' — a specific verb, resource, and scope — and immediately frames the use case ('trends like gross margin or revenue over time'). It clearly distinguishes itself from sibling metrics tools by emphasizing multi-period time series and paging.

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 states 'Use for trends like gross margin or revenue over time, with paging,' giving clear context for when to call it. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full exclusion 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 establish readOnly/idempotent/non-destructive behavior, so the description only needs to add context. It adds the flat 148-credit cost, the POST endpoint, and plan gating (Starter generally, Pro+ for formula_override), which are useful operational constraints.

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 front-loaded: purpose, metric enumeration, cost, usage trigger, route, and auth in a compact block. The long metric list is warranted because there is no output schema and it clarifies exactly what this tool returns.

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 fetch with a fully described schema and safety annotations, the description covers cost, route, plan requirements, and when to use it. The only modest gap is that it never states the response shape, but the metric enumeration and schema largely compensate.

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 applies and the description does not need to explain parameters. It adds the formula_override privilege requirement and mentions metric names, but does not materially clarify the schema's already-detailed parameter semantics.

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 identifies the resource as profitability margins and return ratios, enumerates all 16 metrics, and explicitly scopes it to profitability questions. This separates it from the sibling efficiency/valuation/growth metric tools even though it never names a counter-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?

"Use when the user asks about profitability without naming a specific metric" gives an explicit positive trigger and an implicit exclusion. It also states the API route and plan requirements, but it does not name an alternative tool to use when a specific metric is named.

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 mark the call read-only, idempotent, and non-destructive; the description adds cost (148 credits), plan gating (Starter; Pro+ for formula_override), and the dual realtime/filing-date return behavior. It doesn't detail response shape, but that is less critical given the safety 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 dense but every clause adds information: metric list, return blocks, cost, sibling routing, endpoint, and plan limits. The list of 13 ratios is long but necessary for purpose clarity.

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 with fully documented parameters and no output schema, the description covers the essential invocation context: what is returned, when to use the sibling, cost, and access requirements. It doesn't describe the exact response envelope, but the metric list and schema compensate.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds only that current_price drives the realtime block and formula_override has a plan requirement; it doesn't add semantics 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 names a specific resource ('valuation metrics'), enumerates all 13 ratios, and states the two output blocks (realtime and filing-date). It also names the sibling get_valuation_metrics_filing_date, so an agent can distinguish this tool from the closest alternative.

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 says 'For the filing-date block only, use get_valuation_metrics_filing_date instead,' and notes that current_price is optional for realtime values. It also includes plan requirements and flat cost, giving an agent clear conditions for 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 mark the call read-only and idempotent; the description adds non-obvious behavioral context: flat 148-credit cost, endpoint path, Starter plan requirement, formula_override requiring Pro+, and light_weight_mode's payload-reducing effect. 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 most important contrast (filing-date-only vs realtime sibling) is front-loaded, and the remaining sentences each carry operational facts: use cases, cost, optional payload flag, endpoint/docs, and auth tiers. It is dense without being padded.

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?

Together with the fully documented schema, the description is sufficient for selecting and calling the tool. It doesn't spell out the exact return shape, but the 'same 13 valuation ratios as get_valuation_metrics' reference supplies that context via the sibling.

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 already covers 100% of parameters with clear descriptions, so baseline is 3. The description adds value beyond the schema by explaining plan gating on formula_override and clarifying that current_price/current_fx_rate are not accepted in this variant.

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-resource pair and immediately distinguishes this tool from get_valuation_metrics: same 13 ratios but filing-date only, with no realtime computation or current_price/current_fx_rate. This makes the tool's identity and boundary unambiguous.

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 states exactly when to use it (historical filing-date snapshot, analyzing past filings, batch loads), explicitly excludes realtime computation, and names the sibling alternative it differs from. This is explicit when/when-not/alternative 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 mark it read-only and idempotent; the description adds substantial behavioral context: plan-based silent filtering with `_warnings`, cache/refresh cadence, per-company `classification` only for Pro+, and the exact endpoint/credit cost. 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 long but front-loaded ('Discovery') and each sentence adds a distinct fact: return columns, caching, plan filtering, Pro+ differences, endpoint, and cost. Slightly dense, but no 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?

With no output schema, the description names every major return column, jurisdiction-specific identifiers, filtering behavior, warnings, and plan-dependent fields. It is complete enough for an agent to invoke and interpret results confidently.

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 single optional `jurisdiction` parameter, and the description restates the same values and default behavior. It adds no new semantic information beyond the schema, so baseline 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?

Opens with 'Discovery: return every company covered', a specific verb and resource, then details optional jurisdiction filtering. This makes the tool's role as a comprehensive company-list endpoint unambiguous and distinct from the more targeted search/lookup siblings.

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 frames this as a discovery endpoint and gives operational guidance (omit jurisdiction for all plan-covered companies, cache and refresh at most once daily). However, it never explicitly names when to prefer list_companies over search_stocks or lookup_company, so the when-vs-alternatives guidance is implied rather than explicit.

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 set readOnlyHint=true, idempotentHint=true, and destructiveHint=falselint. The description adds substantial behavioral context: aggregation across all filings, ever_* relationship filter semantics, owner_name coming from the most recent filing, caveats for name_changed, plan history window coverage, 403 error behavior with charge, and the 30-credit cost. 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 dense but every sentence adds value: core purpose, resolution use, relationship filter semantics, return field meanings, plan limits, error behavior, cost, and endpoint. Information is front-loaded with the most important purpose and usage guidance first, then details in natural order.

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 thoroughly explains return fields (filing_count, form4_filing_count, form3_filing_count, owner_name, name_changed, latest_officer_title, officer_title_as_of), filtering semantics, plan constraints, and error handling. This is complete for an agent to understand what it will receive and how to use 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 coverage is 100%, so the baseline is 3. The description adds meaningful value by explaining that the relationship filter takes ever_* values and means 'ever reported in this role,' and contrasts it with the per-filing is_* form found in other tools. This goes beyond the schema's enum list and helps clarify parameter semantics.

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: it lists all insiders of one company, one row per SEC CIK, aggregated over Form 4 and Form 3 filings. It clearly defines the output granularity and distinguishes it from related tools like list_insider_transactions by emphasizing the aggregation and CIK-level granularity.

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 states when to use this tool: to resolve a person to the insider_cik used by list_insider_transactions, get_insider_stats, and list_initial_holdings. It also names alternatives for per-filing is_* semantics (get_insider_stats, search_insider_trades), providing clear routing 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 provide readOnlyHint=true and idempotentHint=true; the description adds substantial context beyond that: 10 credits per page, empty pages and 404 EVENTS_COMPANY_NOT_FOUND still being charged, the plan's history-window limit, and the need to read _warnings for history notices and differing Item lists.

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 purpose and usage guidance, and nearly every sentence carries useful information. However, the middle section is semicolon-heavy and mixes cost, warnings, plan limits, and error behavior into a run-on structure, and the trailing API path/doc reference adds minor clutter.

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 names the returned fields, ordering, warning field, cost, error-charging behavior, and plan requirement. The parameter selection rule and sibling routing complete the picture, making this fully actionable for an agent.

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?

All four parameters have full schema descriptions, including the ticker/cik mutual exclusivity noted in both properties. The tool description restates 'Requires exactly one of ticker / cik' but does not add meaningful detail about page, page_size, or formatting 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 opens with a specific action and scope: 'List one company's corporate event filings, newest first, with filing IDs, dates, Item lists and amendment status.' It clearly distinguishes itself from siblings by naming get_event_filing and search_events as the alternatives for nearby use cases.

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 explicitly states the selection constraint 'Requires exactly one of ticker / cik' and tells the agent when to use siblings instead: get_event_filing for reading sections and search_events for Item/date filters or cross-company searches. It also surfaces the plan requirement and charged-error behavior, so the agent can decide whether the call is appropriate.

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, and the description adds valuable context: '0 credits' and 'Requires the Starter plan or higher,' plus the API endpoint. This goes beyond the structured data and helps the agent understand cost and access requirements.

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 concise sentences: the first states what is returned, the second guides usage, the third adds cost/plan/endpoint docs. Every sentence earns its place and the core purpose 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 zero-parameter list endpoint, the description covers output contents, purpose, downstream usage, credits, access plan, and endpoint. No required context is missing for an agent to call 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?

The tool has 0 parameters, so by the rubric the baseline is 4. The description adds no parameter semantics because none are needed; it focuses on output shape, which 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 states the tool returns 'Supported corporate event Item codes and their official English titles, plus source_url,' which is a specific verb-resource-output combination. It also names the downstream tools (get_event_filing, search_events) that rely on this list, distinguishing it from sibling list tools like list_event_filings.

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 explicitly says 'Use this to choose items for get_event_filing or search_events,' providing clear when-to-use context. It does not include an explicit when-not-to-use or name a direct sibling alternative, but the context is sufficient for an agent to select 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 mark it read-only, idempotent, and non-destructive; the description adds important runtime behavior: possible truncation with `_warnings`, 403 PLAN_TIER_INSUFFICIENT_COVERAGE for out-of-coverage companies, and equivalence to POST /api/v1/data/filings. 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 dense but every sentence carries operational information: purpose, when-to-use, parameter semantics, truncation, errors, and API equivalence. It is front-loaded with purpose and usage before caveats.

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, it tells the agent what to expect (rows, ids, fact counts, amendment note, `_warnings`) and where to find field details. It also covers error conditions and plan-scope behavior, so an agent has enough to call 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?

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds value by specifying accepted form_type values (10-K, 10-Q, 20-F, 40-F) and Korean DART mapping, which goes beyond the schema's generic examples.

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 and resource ('List available SEC filings for one company and fiscal year') and enumerates returned fields (rows, ids, fact counts, amendment note). It also distinguishes itself from downstream siblings by naming them, so an agent can tell it apart from get_filing_facts and query_line_items.

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 says 'Use this first when you need filing_id or to see which quarters/forms exist before calling' a list of sibling tools, giving a clear when-to-use. It also documents form_type coverage and error behavior, making the selection context unambiguous.

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 meaningful context beyond that: '10 credits flat' (cost), the POST endpoint, and crucial semantics – statement_type is a list of canonical names, can hold more than one when a block combines statements, and is null for non-financial header blocks. This is substantial behavioral disclosure.

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 compact paragraph front-loaded with 'Discovery'. Every clause earns its place: scope, return fields, credit cost, next step, endpoint, and documentation reference. There is no filler or 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 read-only discovery tool with no output schema, the description fully covers what the agent needs: exact return fields with edge-case behavior (null header blocks, combined statements), the two valid scope modes, cost, and the natural next tool. The sibling context and annotations round out the picture, leaving no critical 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 baseline is 3. The description reinforces the filing_id vs ticker+fiscal_year relationship, but the schema already documents this ('Use with fiscal_year when filing_id is omitted', 'Required together with ticker when filing_id is omitted'). The description adds little beyond what the parameter descriptions already convey.

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 'Discovery: list every statement block for one filing' – a specific verb and resource – and enumerates the returned fields: block_index, statement_type, and role_label. It differentiates itself from get_filing_statement by naming it as the follow-up for row labels, so an agent can place this tool correctly relative to siblings.

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 explicit scope modes ('filing_id OR ticker + fiscal_year') and explains that quarter is optional. It provides workflow guidance: 'Follow with get_filing_statement to see the exact row labels a statement uses.' It doesn't spell out when not to use this tool versus other sibling listing tools, but the context is clear enough for 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?

Annotations already mark readOnlyHint and idempotentHint true, and the description adds substantial behavioral context: nesting shape, no_securities_owned edge semantics, split_adjusted conditional presence, anomaly withholding unless include_anomalies=true, joint-filing warnings, plan history limits, 403 charging behavior, and credits per page. 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?

Dense but every sentence earns its place: definition and differentiation come first, followed by response semantics, edge cases, warnings, costs, and endpoint. Although long, there is no filler, and with no output schema the detail is justified.

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 having no output schema, the description covers the response structure, conditional fields, filtering semantics, error behavior, plan limits, credits, and endpoint. An agent has enough context to call the tool correctly and interpret the result without additional discovery.

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 covers 100% of parameter descriptions, so the baseline is 3, but the tool description adds meaningful parameter context: ticker can trigger PLAN_TIER_INSUFFICIENT_COVERAGE and still be charged, no_securities_owned=true means the holdings array is empty, and include_anomalies gates data_quality_flags rows. This goes beyond simple schema repetition.

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 opening sentence names the exact deliverable: 'Initial beneficial-ownership statements (SEC Form 3) and the holdings they report, nested filing -> holdings.' It also clarifies the Form 3 context ('positions, not trades') and distinguishes itself from the sibling for unanchored screening, so an agent can tell this tool apart from search_initial_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 explicitly states the prerequisite ('Requires ticker and/or insider_cik') and gives a when-not condition: 'for unanchored screening use search_initial_holdings.' It also warns about a plan-coverage failure mode for tickers, which helps an agent decide whether this tool is appropriate before calling.

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. The description adds valuable behavioral details beyond these: unpaginated (so cache it), limited to plan coverage, costs 175 credits, and provides the API endpoint. It also explains the purpose of the CIK field. These details meaningfully augment the annotation 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 earns its place: it states the core purpose, the output fields, caching guidance, a usage tip, constraints, cost, endpoint, and documentation reference. There is no fluff or repetition; it front-loads the purpose and supplies operational details efficiently.

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 zero-parameter list endpoint with no output schema and annotations covering safety, the description is fully sufficient. It explains what is returned (tickers, jurisdiction, CIK, forms array), how to use the result (verify issuer_cik), and constraints (plan coverage, credits, unpaginated). Nothing an agent needs to invoke it correctly 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?

The input schema is empty (0 parameters), so schema coverage is trivially 100%. The description correctly focuses on output semantics, not parameters. With zero parameters, the baseline is 4; the description doesn't need to add parameter details because there are none.

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 (list) and a precise resource: every ticker with insider-trade (Form 4) and/or initial-holdings (Form 3) data, and details the returned fields (jurisdiction, SEC CIK, forms array). This clearly differentiates it from sibling tools like list_companies or list_insider_transactions, which cover broader or different scopes.

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 context for when to use it: to enumerate tickers with insider coverage, and specifically to use the returned CIK to verify a filing's issuer_cik. However, it does not explicitly name alternatives or state when not to use it (e.g., vs. list_companies), so it barely misses the bar for explicit 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?

The description goes far beyond annotations by disclosing subtle behaviors: use acquired_disposed_code rather than transaction_code, split_adjusted block semantics, data_quality_flags gating behind include_anomalies, page-scoped anomalies_excluded_on_page, joint filing warnings, plan-window truncation, 403 behavior still being charged, and 30 credits per page. Annotations already mark the tool read-only/idempotent/non-destructive, so the description meaningfully adds behavioral context above that 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?

The description is dense but every sentence carries operational value: output structure, field interpretation, anomaly behavior, warnings, error handling, pricing, and endpoint. It is front-loaded with the core purpose and then layers critical caveats, making the length justified for a 10-parameter financial data tool with many edge cases.

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 schemaholpen, the description covers the nested filing->transaction structure, key fields, anomaly suppression, warning semantics, plan limits, error conditions, credit cost, and endpoint. It also contextualizes the page-scoped anomaly count against get_insider_stats. Nothing essential to calling this tool correctly appears 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 baseline is 3; the description adds extra semantic clarity for several parameters, including how include_anomalies affects row withholding, how transaction_code unknown values are dropped and reported, and how ticker/insider_cik interact with coverage and filtering. It doesn't exhaustively walk every parameter, but it meaningfully supplements 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 opens with a specific statement: 'Insider-trade filings and their transactions, nested filing -> transactions,' precisely naming the resource and its structure. It also distinguishes itself from search_insider_trades by noting that unanchored screening belongs there, and the title mirrors the tool's exact scope.

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 explicitly states the required anchoring inputs ('Requires ticker and/or insider_cik'), names the alternative for unanchored searches ('for unanchored screening use search_insider_trades'), and gives important usage caveats such as ticker coverage returning 403, insider_cik-only filtering, plan history windows, and credit costs. This is strong when-to-use 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 cover read-only, idempotent, and non-destructive behavior. The description adds meaningful extras: 'Free, no credits' (cost behavior), the API endpoint, and the semantic warning that codes don't imply direction, which helps an agent avoid a common misinterpretation. 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?

Three concise sentences plus endpoint and doc reference. The purpose is front-loaded, every sentence adds value (contents, usage, caveat, cost), 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 zero-parameter, read-only reference tool with annotations covering safety, the description provides enough for an agent to call it correctly: what it returns, why to call it, cost, and endpoint. No output schema is present, but the description adequately summarizes the response contents.

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?

There are 0 parameters, so the baseline is 4. The description doesn't need to explain parameters; instead it clarifies the output semantics (transaction codes and grouping), which is relevant to parameter usage in downstream filtering tools.

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 ('List'), a resource (SEC insider-trade transaction codes), and the exact contents (20 codes, official name, grouping, source_url). It distinguishes itself from transaction-filtering siblings by positioning itself as the reference step before filtering, and clarifies that codes don't indicate direction.

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 an explicit usage context: 'Run this to learn legal transaction_code values before filtering.' It also warns readers not to infer direction from a code, directing them to `acquired_disposed_code`. However, it does not explicitly name alternative sibling tools or state when *not* to use it, so it's not a full 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 readOnly, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: plan truncation with _warnings, 403 PLAN_TIER_INSUFFICIENT_COVERAGE, US-only jurisdiction with 400 METRICS_UNSUPPORTED_FOR_<jurisdiction> and no credits charged, 10 credits, endpoint, and plan requirements. No contradiction exists.

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 purpose and return value, then requirements, then usage, then error/plan context. It is dense but every section earns its place; minor noise includes the formula_override note and endpoint/documentation reference, which are useful but slightly tangential.

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 does explain the core return concept (metric_group_id entries and filing metadata) and directs users to check _warnings for truncation. It covers key errors, credits, and plan limitations. It stops short of describing the full response shape, but for a discovery tool feeding into named siblings, this 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 coverage is 100%, so baseline is 3, but the description adds meaningful semantics not visible in the schema: the mandatory 'at least one of fiscal_year or as_of_date' rule, accepted form_types values (10-K / 10-Q / 20-F / 40-F), and the meaning of quarter for disambiguation. This materially helps correct invocation.

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: 'Discover computed metric snapshots for a ticker' and immediately states what is returned (metric_group_id entries and filing metadata). It also names the downstream consumers (get_metrics_bundle, get_metrics_subset), clearly distinguishing this discovery tool from the metric-fetching siblings.

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?

Explicit when-to-use guidance is provided: 'Use this when the user wants metrics but you only know ticker/year or as-of date.' It also names the alternatives (get_metrics_bundle or get_metrics_subset) and states required inputs and the at-least-one-of constraint, so an agent can 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 declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds meaningful behavioral context: 10 credits per call, Pro plan requirement, and that Pro+ responses include a sectors list. It also gives the HTTP endpoint and a documentation reference, going beyond 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?

The description is information-dense but well-organized: first sentence lists contents, then usage guidance, then plan-dependent behavior, then cost/endpoint/documentation. It is front-loaded with the main purpose. While it is slightly long, every sentence earns its place, and there is no redundancy or 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?

Given there is no output schema and no parameters, the description carries the full burden. It covers what the tool returns (metrics, operators, modifiers, etc.), mentions an example_request, plan-dependent sectors list, cost, endpoint, and documentation reference. It also explains when to use it. An agent has all necessary information to invoke 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?

The tool has zero parameters, so the baseline is 4. The schema coverage is 100% (no properties), so no parameter explanation is needed. The description focuses on output contents and usage, which is appropriate for a parameterless tool. No extra parameter context is required.

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 lists supported screener inputs (metric names, operators, temporal modifiers, form types, derivations) and explicitly ties it to constructing a search_stocks call. It distinguishes itself from siblings by being the catalog for the screener, and the mention of the endpoint adds specificity. This is a clear verb+resource with strong differentiation.

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 instructs to run this before constructing a search_stocks call to discover legal metric ids, which is a precise when-to-use directive. It also notes the Pro+ response includes sectors for the sectors filter, adding contextual usage. Prerequisites (Pro plan) are stated. There are no alternative tools to exclude, so this is comprehensive.

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?

With readOnlyHint, idempotentHint, and destructiveHint already present, the description still adds substantial behavioral context: coverage may be truncated by history window with _warnings, out-of-plan responses return 403 PLAN_TIER_INSUFFICIENT_COVERAGE, coverage keys differ by jurisdiction, and the response is identity/coverage only. There is 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 long but every section earns its place: entry-point guidance, exact parameter examples, jurisdiction-specific coverage semantics, warning behavior, and downstream routing. It is front-loaded with the core verb/resource and organized so the most critical usage guidance appears first.

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 having no output schema, the description explains what the response contains (jurisdiction, registrant id, filings-list URL, coverage map, normalized_form), what can go wrong (truncation, 403), and what to do next. For a multi-jurisdiction lookup tool with this complexity, 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%, so the schema already documents all parameters, including jurisdiction-specific examples and the 'exactly one of' rule. The description largely repeats that information rather than adding 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 opens with a specific verb and resource: 'Resolve one company and return its identity plus a coverage summary'. It clearly positions this as the entry point for discovering filings before calling downstream tools like get_filing_facts, thereby distinguishing it from the many data-retrieval siblings.

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 explicit: use this when you only know a company identifier and need to discover what filings exist before calling downstream tools. It also states what the tool does NOT return and recommends follow-up tools. However, it does not explicitly describe when-not-to-use alternatives such as list_companies or search_stocks, so it falls just 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?

Beyond the read-only/idempotent annotations, the description discloses per-tier credit costs (10/20/30/50), the presence of `_resolution_level`, consolidated-totals-only behavior, multi-position fact_ids, smart ranking behavior, and the payload effect of light_weight_mode. These are substantive behavioral details not visible in annotations or 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?

The description is long but densely packed with operationally relevant details, and the most important scoping constraints (single filing, consolidated totals only) appear early. A few points are repeated or elaborated more than strictly necessary, but overall each sentence contributes to correct invocation.

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 by explaining result structure (`_resolution_level`, credits_by_line_item, dimensional_breakdowns, _warnings, fact_ids), limitations, pricing, mode options, and alternative tools. An agent has enough context to call this correctly and know what to expect.

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 beyond the schema: line-items resolved through L0-L3 tiers, per-line-item cost breakdowns, the exact payload effect of light_weight_mode, and form_type nuances for foreign/Korean filings. This elevates it above the baseline but does not radically expand every parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Fetch XBRL facts for a single filing by line-item name'. It immediately distinguishes itself from siblings by naming alternatives like get_filing_facts, get_filing_statement, and get_dimensional_breakdown_by_line_item, and by clarifying that only consolidated totals are returned.

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 explicit routing guidance: use get_dimensional_breakdown_by_fact_id/get_dimensional_breakdown_by_line_item for slices, use list_filing_statements/get_filing_statement when unsure of names, and use get_filing_facts when fetching by fact_id. It also clearly states a negative condition: dimension slices are not served here.

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 mark the tool read-only, idempotent, and non-destructive, and the description adds substantial non-obvious behavior: dynamic credit cost '65-280 per page, charged even when the result set is empty and on a 504 timeout,' plan history limits, and the Pro plan requirement. It also clearly discloses what is omitted from results.

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 logically front-loaded: purpose and return behavior come first, followed by date semantics, pagination, costs, and plan requirements. Every sentence carries useful information, though the trailing endpoint and documentation reference add modest 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 10-parameter tool with no output schema, the definition covers return semantics, omissions, date behavior, pagination bounds, plan/history limits, credit costs including empty-result and timeout charges, and sibling tools for setup and full filing retrieval. Nothing essential for an agent to call it correctly 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 already documents every parameter; the description still adds meaning by stating that date parameters filter filing_date and clarifying that as_of_date acts as an end bound with no start. It also ties items to list_event_types, though pagination details partly duplicate 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?

Opens with a specific verb and resource: 'Screen corporate events across companies and filing dates,' and then defines the result shape (filings with matching section summaries, source links, amendment status, newest first). It also distinguishes itself from siblings by pointing to list_event_types for Item codes and get_event_filing for complete filings.

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 names alternatives and when they apply: 'Use list_event_types to choose Item codes, and get_event_filing with a returned id for the complete filing.' It also signals when the screener is insufficient by noting that original text and amendment history are not included.

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 mark this as read-only and idempotent, but the description adds substantial behavioral detail: grouped-mode semantics for holdings_count/shares_owned_total, row field guarantees, no-holdings filings behavior, split-adjusted filter advice, pagination limit, dynamic credit cost (including charges on empty results and 504 timeout), and plan restrictions. This is far beyond what annotations provide and fully discloses operational 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?

The description is dense but well-organized: it starts with purpose, then filter mechanics, output behavior, edge cases, pagination, cost, and plan requirements. Every sentence carries useful information, though the length is substantial. It is front-loaded and each clause earns its place, so this is strong but slightly heavy for a 10% weight.

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 complex tool with 12 parameters and no output schema, the description is remarkably complete. It clarifies return row fields, grouping semantics, edge cases for no-holding filings, cost and timeout behavior, plan limits, endpoint, and documentation pointer. An agent has enough context to invoke the tool correctly and anticipate results without needing to read external docs.

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 baseline is 3. The description adds meaningful parameter semantics by explaining how holding_filters and aggregate_filters work together, the operators allowed, the grouped-vs-flat interpretation of aggregate metrics, and the split_adjusted_shares_owned guidance. It doesn't enumerate each parameter but adds context beyond the schema fields, earning a 4.

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 ('Screen Form 3 holdings across the whole library') and resource ('initial holdings'), with concrete filter dimensions (holding_filters, aggregate_filters). This clearly distinguishes it from siblings like search_institutional_holdings or list_initial_holdings, so an agent can tell them apart without opening their schemas.

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: this is a screener for Form 3 holdings over the whole library with both holding- and company-level filters. It doesn't explicitly name alternatives or state when not to use this tool, but the role is unambiguous given the filter capabilities and scope, so it provides enough 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 readOnlyHint/idempotentHint true, and the description goes far beyond them: grouped-mode txn_count is the company's full hit count not the page's, credit cost is dynamic (65-920) and charged even on empty results and 504 timeouts, results are gated by Pro plan and limited to the plan's history window/company coverage, and rows carry a computed block with value/status/inputs. This is unusually rich behavioral disclosure that materially changes how an agent should plan and budget the call.

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 long but every sentence carries operational value: purpose and filter levels are front-loaded in sentence one, followed by output shape, a subtle counting gotcha, pagination limits, cost behavior, and plan gating. The tail ('POST /api/v1/screener/ownership; FINANCIAL_API_DOCUMENTATION.md') is slightly miscellaneous for an MCP context where the transport is already known, but it does not bloat the core message. Well-ordered and dense, if not terse.

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 12-parameter composite-filter tool with no output schema, the description is remarkably complete: it covers the output row structure (issuer_cik, accession_number, filing_date, source_url_prefix, insiders, computed block), grouped-mode semantics, pagination cap, cost/error behavior, and plan restrictions. The only gap — a full response schema — is partially compensated by the row-composition sentence, and the input side is already fully specified by the 100%-covered 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?

Despite 100% schema coverage (baseline 3), the description adds substantial cross-parameter meaning the schema alone cannot convey: the trade_filters vs aggregate_filters distinction, the shared operator syntax (> , >=, <, <=, between), the guidance to prefer split_adjusted_shares/prices over filed values when the window spans a corporate action, and the page x page_size <= 500 constraint. This lifts the semantics well above the schema's individual field 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 states a specific verb+resource+scope — 'Screen insider trades across the whole library' — and immediately distinguishes this from the sibling list/get tools (list_insider_transactions, get_insider_transactions_by_id) by emphasizing whole-library screening with two layered filter levels. The 'Screener:' title prefix plus the filter-level breakdown make the tool's identity unambiguous even before an agent looks at 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?

The description gives clear context on when to use the tool: whenever an agent needs to screen the whole library with trade-level and company-level conditions. It thoroughly explains the operators, filter payload shapes, grouped-vs-flat modes, and the split-adjusted field guidance for corporate-action windows. However, it never explicitly names sibling alternatives or states when NOT to use it (e.g., when fetching a known transaction by ID), so it stops short of a full when/when-not routing.

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 mark the tool read-only, idempotent, and non-destructive. The description adds substantial behavioral detail beyond that: null qoq/turnover/activity_counts for first-time quarters, count conditions never matching nulls, a _warnings signal for multi-quarter results, page x page_size <= 500, dynamic credit cost charged even for empty results, the Pro plan requirement, and the EDGAR URL 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 long but information-dense and front-loaded with the core purpose before listing output fields and constraints. Each clause adds operational detail (pagination limit, cost, plan, endpoint, EDGAR URL semantics). It is structured enough to be navigable, though slightly dense.

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 explaining return values, and it does so thoroughly: row granularity, field list, null semantics, multi-quarter warnings, pagination limits, cost, plan requirement, and endpoint. For a 10-parameter screener with no output schema, this is a complete and actionable definition.

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 10 parameters. The description adds some useful context, such as 'count conditions never match it' for null quarters and the default full listing behavior, but most parameter-level meaning is already in the schema. This is the baseline 3 case where 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 opens with a specific verb and resource: 'Screen SEC Form 13F institutional filings across the whole library.' It clearly defines the output granularity ('one row per manager-quarter') and lists the headline fields returned. This distinguishes it from single-manager or filing-specific sibling tools like get_institutional_portfolio or get_event_filing.

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 usage context: an empty body returns the full listing, it scans the whole library, and it explains quarter-over-quarter null behavior. It does not explicitly name alternatives or say when not to use this tool, 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=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: dynamic credit cost per request (89-1825), auto-clamping of lookback with _warnings, silent exclusion of out-of-coverage companies with _warnings, and the Pro+ classification block. It does not describe the full response shape, but with no output schema and a complex tool, the cost and warning behaviors are the most decision-relevant traits and they are disclosed.

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 well-organized: it front-loads the required 'where' shape, then operators, then temporal modifiers, then optional parameters, then cost and warnings. Every sentence earns its place, and the most critical operational facts (required field, pre-run companion, cost, clamping) are prominent. It is long, but the tool is genuinely complex with 14 parameters and a nested DSL, so the length is justified. It loses one point only because a few details (e.g., 'FINANCIAL_API_DOCUMENTATION.md' reference) are marginal for an agent deciding how to call the tool.

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 14-parameter tool with nested objects, no output schema, and no enums, the description is unusually complete: it covers the required DSL, operator set, temporal modifier semantics, constraints (leaf count, depth, page limits, ticker limits), plan gating, cost range, and warning behavior. The main omissions are the exact response row shape and the full list of sortable keys, but the schema's where description covers sort_by options and the description points to list_screener_filters for metric discovery. Given the complexity, this is close to complete but not perfect.

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 meaning beyond the schema by explaining the required shape of 'where' in compact DSL form, clarifying that temporal modifiers are mutually exclusive per leaf, noting the leaf count and nesting depth limits, and explaining the effect of include_metrics_using_filing_date_price ('gates 13 valuation ratios'). It also adds the page*page_size <=500 constraint that is repeated in the schema but consolidated here. The only minor gap is that the description doesn't enumerate the sort_by options, but the schema's where description does.

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 ('Screen companies') and a precise resource ('82-metric catalog'), and the title 'Screener: search stocks by criteria' matches. It clearly distinguishes this from the many get_* and list_* siblings by framing it as a filter-DSL screening tool, and it names the companion tool list_screener_filters for discovering metric ids. An agent can tell this is the cross-sectional screener, not a timeseries or statement retrieval 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?

The description explicitly says to 'Pre-run list_screener_filters once to discover supported metric ids + operators,' which is direct when-to-use guidance. It also states the Pro plan requirement and the Pro+ gating on sectors, and it explains when _warnings is populated (lookback clamping and coverage exclusions). The sibling list includes list_screener_filters, so the routing to that companion is explicit.

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