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 cover the read-only/idempotent/non-destructive safety profile, so the description goes beyond them with high-value operational facts: 28 credits debited even on failure/absence/non-SEC filings, the SEC-only scope, and the light_weight_mode payload tradeoff at identical cost. This is exactly the kind of cost-and-failure disclosure an agent needs before calling.

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?

Front-loads the return value before the identification and cost clauses, and every sentence carries distinct information (identity, alternatives, limits, cost, endpoint). It is dense but not padded; slightly longer than strictly necessary given the schema duplication.

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 describing the return shape (line items with values and periods), along with scope, cost, and failure behavior. Nothing an agent needs to call this 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 all six parameters are already documented in the schema, including the filing_id vs ticker+fiscal_year exclusivity and the form_type default. The description largely restates that routing guidance and the light_weight_mode behavior rather than adding new parameter semantics. 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?

States a specific verb and resource ('Return the filing's Balance Sheet — its extracted line items with values and periods') and explicitly positions itself as a fixed shortcut for get_filing_statement, naming the parameters it does not accept. An agent can distinguish it from the sibling statement tools without opening either 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?

Gives explicit identification paths (filing_id, or ticker + fiscal_year, optional quarter), names the parent alternative (get_filing_statement), and states the jurisdiction limitation (SEC only) and the 404 condition. Both when-to-use and when-it-fails are 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?

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 readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the 404 on missing statements, the SEC-only scope, the 28-credit cost debited even on missing filings/non-SEC inputs, and the light_weight_mode payload tradeoff. These are behavioral costs an agent needs that structured fields cannot express.

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?

Front-loaded with the purpose, then layers identification, shortcut relationship, failure modes, and cost. Every sentence carries information, but the semicolon-chained final sentences are dense and could be split for cleaner scanning.

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 and six optional parameters, the description still tells the agent what is returned, how to select the filing, what happens on failure, what it costs, and how to trim the payload. Nothing needed for a correct 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?

Schema description coverage is 100%, so every parameter is already documented with examples and constraints (ticker format, quarter labels, form_type defaults). The description only restates the alternation between filing_id and ticker + fiscal_year, adding no format or disambiguation detail beyond the schema. 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?

States a specific verb and resource ("Return the filing's Cash Flow Statement") and enumerates what comes back — extracted line items with values and periods. It explicitly positions itself relative to get_filing_statement as a fixed shortcut, so an agent can tell it apart from the sibling without opening either 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?

Gives the two alternative identification paths (filing_id, or ticker + fiscal_year with optional quarter), names the sibling it shortcuts, states what it deliberately does NOT accept (role_label, statement_type), and specifies the 404 case and the SEC-only restriction. When-to-use and when-not-to-use are both 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 declare readOnlyHint/idempotentHint/destructiveHint, so safety is covered; the description goes well beyond by disclosing the 28-credit cost, that credits are debited even on failure, the SEC-only jurisdiction limit, the 404 behavior, and the light_weight_mode payload tradeoff — none of which appear in structured fields.

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?

Purpose and payload are front-loaded, then identification, then cost/error caveats — a sensible ordering with no filler. It is dense and semicolon-heavy (endpoint path plus doc filename), which costs a little readability but every clause carries 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?

With no output schema, the description still characterizes the return (extracted line items with values and periods) and covers accounting cost, jurisdiction scope, error behavior, and a payload-size toggle. Nothing material 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?

Schema description coverage is 100% and each parameter is individually documented, so the baseline is 3. The description restates the filing_id vs ticker+fiscal_year composition and mentions light_weight_mode, but adds no format or constraint detail the schema lacks.

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 Comprehensive Income — its extracted line items with values and periods") and explicitly positions itself against a sibling: "A fixed shortcut for get_filing_statement(statement_type='Comprehensive Income')". An agent can distinguish it from get_income_statement / get_balance_sheet without opening any 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?

Gives the two identification routes (filing_id, or ticker + fiscal_year + optional quarter) and states the failure condition ("returns 404 when the filing has no comprehensive-income statement"). It also names the alternative (get_filing_statement) and notes the parameters it deliberately does not accept, which is exactly the when-to-use/when-not guidance 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 cover the read-only/idempotent safety profile, and the description goes well beyond them: it discloses the credit-pricing formula, the 404 behavior for an out-of-filing fact_id (still charged 10 credits), and the exact expansion semantics. This is unusually 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?

Front-loads the core operation and scope, then batches the recursion, pricing and error rules into tight sentences. Every clause earns its place, though the endpoint path and documentation filename at the end are lower-value metadata.

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

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

With no output schema, the description carries the burden of describing returns and does so (grouped slice facts, root counted as one fact). Pricing, scope and error handling are covered; minor omissions like result-size limits or pagination are the only gaps.

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 nevertheless adds meaning by tying filing_id/ticker+fiscal_year/quarter into a single scope rule and clarifying that recursive controls depth of expansion. The added value is modest but real beyond the baseline 3.

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

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

States a specific verb and resource: 'Return one consolidated fact plus every slice fact it breaks down into,' and clarifies the grouping unit (the set of XBRL axes). This is clearly distinguishable from the sibling 'get_dimensional_breakdown_by_line_item' because the entry point is a fact_id rather than a 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?

Explicitly states the scoping rules (filing_id OR ticker + fiscal_year, optional quarter) and the recursive default with the opt-out semantics. It does not explicitly say when to prefer this tool over its line-item sibling, but the invocation context is otherwise 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 cover safety (readOnly, idempotent, non-destructive), yet the description goes well beyond them: billing model (tier credit 10–50 + ceil(N/5)×10, partial billing), the meaning of duplicate_root_fact_ids, ordering provenance, and the recursive default. This is exactly the extra behavioral context the bar rewards.

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?

Front-loaded with the core action, then scope, recursion, billing, and an endpoint/docs pointer. Dense and largely waste-free, though the pricing and endpoint-reference clauses make it longer than strictly necessary for tool selection.

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 carries the return-shape burden well: 'each match is one root with axis-grouped slice facts' plus duplicate_root_fact_ids behavior explains what comes back. Scope, recursion, and billing are all covered, leaving nothing essential 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 each parameter; the description adds scope semantics ('filing_id OR ticker + fiscal_year') and reiterates the recursive default that affects result depth. It clarifies the interplay between scope params, adding value over 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?

States a specific verb+resource: 'Resolve a line-item name ... and return the dimensional breakdown'. The examples ('revenue', 'net income') and the distinction of expanding a name (vs the fact_id variant) make the tool's job clear. However, it never names the sibling get_dimensional_breakdown_by_fact_id, so the routing distinction is only implicit.

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 usable context: 'Scope: filing_id OR ticker + fiscal_year' tells the agent how to satisfy the call, and 'review all matches and judge which one you need' clarifies that pre-ordering is advisory. It lacks an explicit exclusion or a named alternative sibling for the fact_id case, 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 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 cover read-only/idempotent/non-destructive, but the description adds substantive context beyond them: the 28-credit cost is debited even on missing filings, non-SEC filings, or absent statements; a 404 is returned when no equity statement exists; and light_weight_mode drops verbose nested fields at the same price. These are the operational facts an agent needs before calling.

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?

Front-loads the return value, then identification, then sibling routing, then constraints and cost. It is dense but every sentence carries distinct information (shortcut equivalence, credit policy, SEC-only scope, endpoint reference) and none is redundant with the schema or annotations.

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 still characterizes the return ('extracted line items with values and periods') and covers cost, error behavior, jurisdiction limits, and the lightweight option. Nothing an agent needs to call this 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 description coverage is 100%, so the baseline is 3 and the schema already documents each field. The description adds value by clarifying the identification logic (filing_id OR ticker + fiscal_year, quarter optional to disambiguate), the absence of role_label/statement_type, and the trade-off behind light_weight_mode ('saves context when you already know exactly what you need').

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 ('Return the filing's Statement of Stockholders' (or Shareholders') Equity') plus the shape of the payload (extracted line items with values and periods). It explicitly distinguishes itself from get_filing_statement by framing itself as 'a fixed shortcut for get_filing_statement(statement_type='Stockholders Equity')' and notes it does not take 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?

Gives concrete filing-identification paths (filing_id, or ticker + fiscal_year with optional quarter) and names the alternative (get_filing_statement) with the reason to prefer this shortcut. It also states the exclusion conditions: SEC-only availability, 404 when no equity statement exists.

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 readOnly/idempotent/non-destructive/closed-world, so the bar is low, yet the description adds real behavior: light_weight_mode omits results[*].dimensional_breakdowns, cost is identical either way, and it maps to POST /api/v1/data/facts with tiers/limits in an external doc. It stops short of describing pagination or result ordering, hence not a 5.

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?

Front-loads purpose and the sibling routing rule in the first two sentences, then handles identification, then the optional flag. Slightly redundant — "light_weight_mode" behavior is repeated verbatim in the schema description, including "Charged identically" — which costs a little density.

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 helpfully names the one nested field affected by light_weight_mode and points to documentation for tiers/limits, which is the main open-world unknown for a charged endpoint. It leaves the general result shape (which fields a fact carries) unexplained, but for a 7-param read tool this is close to sufficient.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter logic the schema states only locally: the filing_id vs ticker+fiscal_year(+quarter) either/or, and the form_type default of 10-K with foreign-issuer (20-F/40-F) and Korean DART nuances. It also confirms fact_ids must be non-empty, which the schema marks required but not as non-empty.

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 specific XBRL facts for a single filing by fact_id") and immediately distinguishes itself from query_line_items by naming the query type it does not serve (line-item names). An agent can route between the two without opening either 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?

Explicit routing rule: line-item-name queries (revenue, net income) go to query_line_items instead. It also states the two mutually exclusive identification paths (filing_id OR ticker + fiscal_year, with quarter only to disambiguate) and when light_weight_mode is worth using. When-to-use and alternatives are both 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?

Annotations already declare read-only, idempotent, non-destructive behavior, and the description goes well beyond them: credit pricing per mode (28 vs tiered 28/48), the 0-match → 404 contract, the concrete response shape, and the context-saving tradeoff of light_weight_mode with the assurance it is 'charged identically'. This is exactly the kind of behavior an agent cannot infer from structured fields.

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?

It is a single dense paragraph rather than a list, but every clause carries load: mode definitions, pricing, jurisdiction limits, sibling routing, prerequisite, scoping, and return shape. Front-loads the core purpose and the two modes; the length is justified by the tool's breadth, though the run-on structure slightly hurts scannability.

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 an 8-parameter tool with no output schema, the description supplies the missing pieces: the exact response shape, the 404-on-zero-matches case, and the light-weight payload variation. Nothing needed to call this correctly is left unstated.

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 a little beyond the schema, chiefly the mutual-exclusivity constraint restated at the mode level and the cost differential between role_label and statement_type. It does not, however, add much about filing scoping composition (filing_id vs ticker + fiscal_year + quarter) beyond what the schema already documents.

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 ('Return extracted financial statement block(s) for a filing') and immediately distinguishes itself from sibling tools by naming get_income_statement, get_balance_sheet, and the other dedicated statement tools, plus list_filing_statements as the discovery step. An agent can route correctly without reading any 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?

Explicitly enumerates both lookup modes and declares them mutually exclusive ('pass exactly one'), states when statement_type is unavailable ('SEC filings only ... use role_label for those'), gives the prerequisite 'Use list_filing_statements first', and points to dedicated tools for the 5 main statements. Both when-to-use and when-not-to-use are 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?

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 cover the read-only/idempotent safety profile, and the description adds substantial context beyond them: 404 behavior when the statement is absent, credit cost of 28 debited even on missing/non-SEC filings, SEC-only jurisdiction limitation, and the light_weight_mode payload tradeoff. This is exactly the value-add the description should 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?

Front-loaded with purpose and return shape before cost and routing details. Dense but nearly every clause carries decision-relevant information (cost, 404, jurisdiction, mode); only minor compression would improve it.

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

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

No output schema, yet the description explains the return content (line items with values and periods), the failure modes, cost, jurisdiction limits, and the sibling alternative. Nothing material for correct 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?

Schema coverage is 100%, so the baseline is 3, but the description adds identification semantics beyond the schema: the filing_id vs ticker+fiscal_year(+quarter) alternatives and the light_weight_mode context-saving intent. Credit for reinforcing how the params combine rather than just restating them.

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 ('Return the filing's Income Statement... its extracted line items with values and periods') and explicitly frames itself as a fixed shortcut for the sibling get_filing_statement, noting it does not take role_label or statement_type. An agent can distinguish it from get_filing_statement and the other statement tools without opening a 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?

Gives explicit selection logic: identify the filing with filing_id, or ticker + fiscal_year (+ optional quarter), and names the general alternative get_filing_statement with the condition (fixed statement_type) that selects this shortcut. It also discloses when not to expect success (no income statement, non-SEC filing).

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavioral context: 403 PLAN_TIER_INSUFFICIENT_COVERAGE with charges still applied, the credits formula (40 + 5 per 1000 holdings), the _warnings field requirement, the unit mismatch between shares_owned_total and underlying_shares_total, and the note that filing counts include no-holding filings. This is far beyond what the structured fields convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense paragraph, but it is front-loaded with the aggregation scope and output fields and every clause carries information (units, warnings, cost, endpoint). It reads as a run-on wall of text rather than cleanly separated concerns, which costs it the top mark.

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 and 12 parameters, the description carries the burden of describing returns and mostly delivers, naming the key output fields, the provenance list, the warnings field, cost, and the coverage error. It names fields like corporate_action_crossing and earliest/latest_filing_date without fully defining them, leaving minor gaps.

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, and the baseline is 3. The prose largely restates output semantics rather than adding parameter-level meaning; it does reinforce the filing-date window framing but contributes little the schema does not already carry.

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 ('Aggregates over Form 3 filings in a filing-date window') and enumerates the exact metrics produced, so an agent knows precisely what comes back. It differentiates itself from the row-level counterpart by pointing to get_initial_holdings_by_id for the underlying rows. It stops short of distinguishing itself from neighbors like list_initial_holdings or search_initial_holdings, so it is clear but not fully sibling-aware.

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 operational caveats ('Read _warnings before using any total', 'two different units, not to be added together') and routes to get_initial_holdings_by_id for provenance rows. However it never states when to choose this aggregation over the sibling list/search/insider-stats tools, leaving the core when-to-use decision implied.

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 a safe read (readOnlyHint, idempotent, non-destructive), and the description layers on genuinely non-obvious behavior: credit pricing (40 + 5 per 1000), that out-of-coverage requests are charged despite 403, the plan history-window limit, _warnings semantics and the instruction to read them before trusting totals, and corporate_action handling. This is exactly the context annotations cannot carry.

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?

Front-loaded with the core purpose and the ids hand-off, then proceeds to behavioral caveats. It is a dense single block rather than a wall of filler, but the run-on structure and parenthetical-heavy paging aside cost it a point on readability.

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 carries the return burden and does so reasonably: it names the stats key families, transaction_ids and their paging, _warnings, and the *_applied echo fields. Coverage is strong for a 14-parameter tool, though the full shape of the stats object is only gestured at rather than enumerated.

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 would be 3, but the description adds meaning the schema does not: the stat key naming per method ('acquired/disposed' for ad, 'bought/sold' for ps), that zero-cash-price transactions count as 0, that share totals and averages use the adjusted basis and drop debt-principal rows, and the paging contract for ids_page/ids_page_size and the 100-id cap on the detail call. These materially change how parameters are interpreted.

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 ('Totals over one company and/or one insider, plus transaction_ids for every contributing row') and pins the scope to one company and/or one insider. It also differentiates itself from the sibling get_insider_transactions_by_id by declaring that tool is where the detail lives, so an agent can route correctly without opening either 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?

Gives the prerequisite ('Requires ticker (or cik) and/or insider_cik'), the delegation rule ('feed those to get_insider_transactions_by_id for the detail'), and the plan-coverage caveat that an out-of-coverage ticker returns 403 yet is still charged. It stops short of an explicit when-not-to-use this tool versus search_insider_trades or list_insider_transactions, so it is clear context rather than full 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?

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?

Far beyond the readOnly/idempotent annotations, the description discloses the three row kinds, the weight string format, the _warnings semantics (amendment action mismatch, unit-multiplier corrections, CUSIP_CHANGE predecessor fields, null deltas for first-quarter comparisons), the 30-credit-per-page cost, and that 404s are still charged. This is exactly the behavioral context an agent needs and cannot get from 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?

Scope is front-loaded and the density is justified by the tool's complexity. The middle sentences are somewhat run-on (warnings and credits packed into long clauses), but nearly every sentence carries operational value and nothing is pure 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 12-parameter financial tool with no output schema, the description supplies the return structure (row kinds and fields), warning semantics, pagination cost, error codes, and even the endpoint and doc reference. An agent has everything needed to call and interpret 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%, so the baseline is 3. The description's explanation of the three row types loosely mirrors the 'type' enum, and the weight format is useful, but most parameter meaning (cik/name, cusip/ticker, activity, restated, sort_by) is already carried by the schema.

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

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

States a specific verb+resource+scope: 'One manager x one calendar quarter: the 13F holdings detail rows.' An agent can tell this is the per-manager-quarter detail view rather than the search or history views. However it never explicitly names the sibling it contrasts with (search_institutional_holdings, get_institutional_manager_history), leaving differentiation to inference.

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 ('one manager x one calendar quarter') implies the use case, and the schema's cik/name rule reinforces the entry point. But there is no explicit when-to-use vs. when-not, and no routing to alternatives for cross-manager or cross-security queries. Usage is implied, not 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 cover safety (readOnly, idempotent, non-destructive, non-open-world), yet the description adds substantial non-obvious behavior: a 404 OWNERSHIP_SECURITY_NOT_FOUND on unknown securities, credit costs (30/page flat, 40 grouped, 404 still charged), and that grouped mode is unpaged. These are the kind of cost/error/mode traits an agent cannot derive from structured fields.

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?

Purpose and anchoring constraint are front-loaded, then modes, then cost/endpoint. It is dense but nearly every clause carries information; the trailing EDGAR-index sentence is partially tangential and the run-on paragraph structure makes it harder to scan.

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 description covers anchoring, error behavior, the securities block, per-row additions, the grouped aggregation shape, pagination, cost and endpoint. Only the mapping of the remaining sort_by/sort_order/paging params to returned ordering is left implicit, 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%, so the schema already documents all ten parameters, including the YYYYQn quarter format, the activity enum values, and the ticker-matches-multiple-CUSIPs case. The description restates these and adds only the framing that quarter/type/activity/sort_by 'narrow' the rows, which is marginal beyond the schema 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?

States a specific verb+resource: 'One security's 13F holder rows across managers, anchored by exactly one of cusip / ticker.' It also distinguishes itself from get_institutional_portfolio by describing its rows as the same detail rows plus manager_cik / manager_name, so an agent can tell the two apart without opening a 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 the selection rule for its own modes (flat default vs group_by_quarter=true) and a precondition (exactly one of cusip / ticker), but it never routes the agent between this tool and the closely related sibling search_institutional_holdings, nor states when a grouped aggregate is preferable to detail rows. Usage is implied by parameter behavior 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, 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 declare the tool read-only/idempotent, yet the description layers on substantial extra behavior: plan history/coverage truncation surfaced via `_warnings`, 403 PLAN_TIER_INSUFFICIENT_COVERAGE, 400 METRICS_UNSUPPORTED_FOR_<jurisdiction> with no credits charged, and plan gating (Starter+, Pro+ for formula_override). This is exactly the beyond-annotation disclosure that helps an agent avoid wasted calls.

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: purpose first, then period_type semantics, then optional args, then failure modes. Every clause carries actionable content, though it slightly sprawls by restating schema-level details (sort values, page_size range).

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-param, output-schema-less tool, the description covers error paths, plan gating, paging limits, and the `_warnings` signal. The one gap is the return payload shape (fields returned), though light_weight_mode hints at nested audit fields and the schema itself documents all inputs.

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 real meaning beyond the schema: formula_override requiring Pro+, the jurisdictional semantics of period_type, and the light_weight_mode tradeoff (leaner payload, same charge). It does not add syntax beyond what the schema already documents for bounds and sort values.

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

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

States a specific verb+resource ('Time series of metrics for a ticker across many periods') and scopes it to trend analysis. It implicitly separates itself from snapshot siblings (get_metrics_bundle, get_metrics_subset) by emphasizing 'across many periods' and 'with paging', though it never names those siblings explicitly.

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 for trends like gross margin or revenue over time, with paging' gives a clear usage context and the geographic/period nuances reinforce when this tool applies. It stops short of naming alternatives for single-period needs or stating 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 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?

Beyond the safety annotations, it discloses non-obvious traits: silent plan-based filtering with `_warnings` populated when rows are dropped, daily cache-refresh guidance, the per-row identifier fields, a Pro+-only `classification` block, and a 175-credit cost. This is exactly the context annotations cannot convey.

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?

Information-dense and front-loaded, with the filter behavior first and metadata (endpoint, credits, doc reference) trailing. It is a single dense paragraph with many clauses, so it is efficient but not maximally 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?

With no output schema, the description carries the return-shape burden and does so fully: enumerates the per-row fields, explains filtering warnings and the conditional Pro+ block, and points to the endpoint and doc reference. Nothing essential to correct 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?

Schema coverage is 100% and the enum values are already listed in the schema description, so the description largely restates them. It adds only the plan-scope behavior ("returns everything the caller's plan includes"), which is marginal 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?

The description opens with a clear verb+resource ("return every company covered") and frames the tool as a discovery endpoint, which cleanly separates it from lookup_company and search_stocks in the sibling list.

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 explains the jurisdiction filter values, the omitted-parameter default, plan-scoped filtering, and caching guidance, giving clear context for how and when to call it. It stops short of explicitly naming alternatives (e.g., lookup_company for a single issuer), so it misses the top tier.

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 annotations already declaring it a safe, idempotent read, the description adds material context: aggregation across all filings, the name_changed caveat semantics, that latest_officer_title is the most recent non-null title with a paired officer_title_as_of date, plan history-window truncation of counts/date ranges, a 403 PLAN_TIER_INSUFFICIENT_COVERAGE that is still charged, 30 credits, and the underlying POST route.

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?

Front-loaded with the output grain before the routing advice, and every sentence carries distinct information (resolution purpose, filter semantics, field caveats, cost, error). It is dense and uses several semicolon-joined clauses, but there is little waste.

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

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

No output schema exists, yet the description enumerates the returned fields (filing_count, form4_filing_count/form3_filing_count, identity flags, date range, owner_name, name_changed, latest_officer_title/officer_title_as_of) and covers plan-window effects, error codes, and cost — everything needed to call and interpret it.

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 real semantic content: the relationship filter's ever_* values mean 'ever reported in this role,' which is an interpretation the schema does not supply. cik/ticker mutual exclusivity is already handled in the schema, so it earns 4 rather than 5.

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 precise verb+resource+scope: 'All insiders of one company, one row per SEC CIK, aggregated over its Form 4 and Form 3 filings.' It immediately names the grain and the source filings, and explicitly differentiates itself from get_insider_stats and search_insider_trades via the ever_* vs is_* distinction, so an agent can identify it without reading sibling 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?

Gives an explicit selection rule: 'Use it to resolve a person to the insider_cik that list_insider_transactions, get_insider_stats and list_initial_holdings take.' It also states when-not-to-use it, noting the filter takes ever_* values here whereas the per-filing is_* form belongs to get_insider_stats and search_insider_trades.

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/non-destructive, but the description adds substantial operational context the annotations cannot: a 10-credit-per-page cost, that empty pages and 404 EVENTS_COMPANY_NOT_FOUND are still charged, the plan-level history window limit, and that _warnings should be read 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?

Front-loaded with purpose and ordering, then prerequisites, alternatives, costs and warnings — every sentence carries weight. It is dense and packs a lot into a run-on sentence, and the trailing endpoint/doc-file reference is mild cruft, but 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 no output schema, the description still conveys the return shape (IDs, dates, Item lists, amendment status), pagination behavior, warnings field, cost model and access tier. An agent has everything needed to call it correctly and interpret the response.

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

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

Schema description coverage is 100% and each parameter is well documented there, which sets a baseline of 3. The description goes beyond the schema by stating 'Requires exactly one of ticker / cik' — a mutual-requirement constraint the schema does not express (required parameters is 0), so it adds genuine 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?

States a specific verb and resource (list corporate event filings), the scope (one company, newest first), and enumerates the returned fields (filing IDs, dates, Item lists, amendment status). It also implicitly separates itself from search_events (cross-company) and get_event_filing (single filing detail).

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 the alternatives and the conditions that select them: 'Use a returned id with get_event_filing to read the sections; use search_events for Item/date filters or searches across companies.' It also states the input prerequisite (exactly one of ticker/cik) and the plan prerequisite (Starter or higher).

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 establish the safe-read profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial non-obvious behavior: results may be truncated by the plan's history window/coverage scope, `_warnings` should be checked, and out-of-coverage companies return 403 PLAN_TIER_INSUFFICIENT_COVERAGE. It also cross-references the equivalent REST endpoint and its credit 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?

Front-loaded with purpose and the 'use this first' routing before the denser argument/edge-case notes. It is information-dense but every sentence carries a distinct payload (return fields, routing, form conventions, truncation, error code); borderline long but not 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?

Despite no output schema, the description describes the shape of the returned rows, the amendment note, truncation behavior, and the failure mode. For a read-only lookup feeding many downstream tools, an agent has everything needed to call and interpret it.

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 parameters are self-documenting; the description still adds value with domain knowledge about form_type conventions (20-F for US-listed foreign issuers, 40-F for Canadian filers, Korean DART filings using 10-K/10-Q). It doesn't explain quarter disambiguation beyond what the schema already says, but the form_type guidance is real added 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?

States a specific verb (List) and resource (SEC filings) scoped to one company and fiscal year, and enumerates what each row carries (rows, ids, fact counts, amendment note, registrant_cik/registrant_name). It is easily distinguished from the many get_* and compare_* 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?

Explicitly says 'Use this first when you need filing_id or to see which quarters/forms exist before calling' and names seven downstream siblings (get_filing_facts, query_line_items, get_filing_statement, compare_line_items, compare_facts, get_filing_excel). Both the trigger condition and the alternatives are given.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-structured context: a flat 10-credit cost, the POST endpoint, and return-field semantics (statement_type is null for non-financial header blocks, a list when a block combines statements). It stops short of pagination or ordering details.

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?

Front-loads the verb and the return payload, then scope, cost, and follow-up, with no filler sentences. It is a fairly dense paragraph, but every clause carries information relevant to selection or 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 takes on the return-value burden and handles it by enumerating the fields and their edge cases. Combined with scope rules, credit cost, endpoint, and the follow-up tool, an agent has everything needed 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 description coverage is 100%, with detailed per-parameter descriptions already present. The description restates the scope rule (filing_id OR ticker + fiscal_year, optional quarter) but adds no syntax or format detail beyond what the schema supplies, 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?

States a specific verb+resource ('list every statement block for one filing') and enumerates the returned fields with their semantics (block_index, statement_type, role_label). It also distinguishes itself from the sibling get_filing_statement by framing this as discovery and that tool as the row-label detail step.

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?

Names the entry condition ('Discovery') and gives the scope selector (filing_id OR ticker + fiscal_year, optional quarter), plus an explicit follow-up tool. It does not spell out when-not to use it versus other statement getters, but the workflow 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?

Annotations cover the safety profile, yet the description adds substantial behavior beyond them: anomaly rows are withheld unless include_anomalies=true with a per-page withheld count, plan history-window truncation surfaced in _warnings, joint filings reported in _warnings, and a 403 PLAN_TIER_INSUFFICIENT_COVERAGE that is still charged at 30 credits per page. This is exactly the kind of cost and edge-case disclosure annotations cannot carry.

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?

Front-loaded with the resource and the Form 3 vs. transaction distinction, then routes to the sibling before the field-level detail. It is a dense single block, but nearly every clause carries non-redundant information; only minor tightening is possible.

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 must describe the return shape — and it does, covering the filing->holdings nesting, issuer_cik/insiders/footnotes/source_url_prefix, the shares_owned vs. underlying_security_shares/value split, and the _warnings channel. An agent has enough to call and interpret results without opening 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 the baseline is 3; the description nonetheless adds consequences the schema omits, such as no_securities_owned=true implying an empty holdings array, the conditional presence of split_adjusted, and what include_anomalies actually admits. It does not, however, cover every parameter (e.g., exclude_likely_merged, include_unresolved_amendments) in prose.

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

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

States a specific verb+resource (list Form 3 initial beneficial-ownership statements and their nested holdings) and explicitly distinguishes it from transaction filings: 'positions, not trades — there is no transaction date, code, price or direction.' That contrast alone separates it from list_insider_transactions and search_insider_trades.

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?

Gives the anchoring requirement ('Requires ticker (or cik) and/or insider_cik') and names the alternative for the uncovered case: 'for unanchored screening use search_initial_holdings.' Both the when and the when-not are 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 declare readOnly, idempotent, non-destructive and non-open-world, so the safety profile is covered. The description adds genuinely new behavioral context: the result is unpaginated and should be cached, it is capped by the caller's plan coverage, and it costs 175 credits — cost and caching are exactly the traits an agent needs to plan around.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences that front-load the row structure, then constraints, then the endpoint pointer. Every clause carries information, though the trailing 'GET /api/v1/ownership/tickers; FINANCIAL_API_DOCUMENTATION.md' is a raw doc reference that slightly clutters an otherwise tight 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?

With no parameters and no output schema, the description fully covers what the agent needs: the grain of the response, the fields in each row, the absence of pagination, the plan-based coverage limit, and the credit cost. Nothing required to call this tool 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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool is 4. The description instead spends its words on the return shape, which is reasonable.

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+resource ('One row per company that has insider-trade (Form 4) and/or initial-holdings (Form 3) data') and enumerates the exact fields returned (ticker, jurisdiction, SEC CIK, forms array). This scope is narrow enough to separate it from generic siblings like list_companies, list_company_insiders, and list_insider_transactions without opening any 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 tells the agent operational constraints ('Unpaginated — cache it', plan-limited coverage, 175 credits) but never states when to choose this tool over alternatives such as list_companies or search_insider_trades. Usage is implied by the scope rather than explicitly routed, so it lands at minimum-viable rather than strong 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 cover the safety profile (readOnly/idempotent/non-destructive), and the description goes well beyond: read direction comes from acquired_disposed_code not transaction_code, split_adjusted appears only off-basis, data_quality_flags rows are withheld unless include_anomalies=true, joint filings land in _warnings, and a 403 PLAN_TIER_INSUFFICIENT_COVERAGE is still charged at 30 credits per page. This is unusually 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?

Front-loads the core purpose and structure before the caveats, and each sentence carries distinct information. It is dense and long, but the density is justified by the number of real gotchas (anomalies, plan windows, billing) it must convey.

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 and 11 parameters, the description carries the return-shape burden and does so: nested filing->transactions, per-filing fields, _warnings, and pagination via page/page_size. Nothing essential to calling or interpreting 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 baseline is 3, but the description adds cross-parameter meaning the schema lacks: the page-scoped anomalies_excluded_on_page versus the whole-range anomalies_excluded_count on get_insider_stats, and the consequence of an insider_cik-only query filtering out uncovered companies. It does not, however, document every one of the 11 parameters' 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?

States a specific resource and its shape: 'Insider-trade filings and their transactions, nested filing -> transactions.' It also distinguishes itself from the sibling search_insider_trades by naming it for unanchored screening, so an agent can route correctly without opening a 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?

Gives the required anchoring ('Requires ticker (or cik) and/or insider_cik') and explicitly names the alternative ('for unanchored screening use search_insider_trades') with the condition that selects it. When-to-use and when-not-to-use are both present.

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?

Goes well beyond the annotations: 10-credit cost, plan requirements (Starter+, Pro+ for formula_override), 403 PLAN_TIER_INSUFFICIENT_COVERAGE, truncation via _warnings, and that unsupported jurisdictions charge no credits. These are exactly the operational facts an agent needs before calling.

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?

Front-loaded with purpose/inputs before usage and caveats, and every sentence carries information (requirements, filter values, cost, error codes). It is dense and slightly long, but nothing is 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?

No output schema exists, yet the description explains the return shape (metric_group_id entries plus filing metadata) and warning surface, and covers auth/plan, cost, and error behavior. Nothing material is missing for a 5-parameter discovery call.

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 a genuine cross-parameter constraint not stated in the schema: at least one of fiscal_year or as_of_date is required. It also enumerates valid form_types values and explains quarter's disambiguation role.

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

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

States a specific verb + resource ('Discover computed metric snapshots for a ticker') and precisely what is returned ('metric_group_id entries and filing metadata'). It also positions the tool relative to its consumers, naming get_metrics_bundle and get_metrics_subset, so the agent can distinguish it from the sibling metric 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?

Gives an explicit selection rule: 'Use this when the user wants metrics but you only know ticker/year or as-of date,' and names the downstream tools the output feeds. It also states when the tool is unavailable (non-US companies fail fast with 400 METRICS_UNSUPPORTED_FOR_<jurisdiction>).

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?

Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond: it discloses the 403 PLAN_TIER_INSUFFICIENT_COVERAGE error, the 8-credit cost, that coverage may be truncated by the plan's history window, that historical tickers produce _warnings notes, and that downstream form_type aliases are accepted. Substantial behavioral context beyond structured fields.

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?

Purpose and the one-of constraint are front-loaded well, but the body is dense and repeatedly re-lists identifier examples that already live in the schema, and mixes coverage-key/jurisdiction detail into a single long run-on. It earns its place functionally but is not tight.

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 return contract: identity, jurisdiction, registrant id, filings-list URL, coverage keys by jurisdiction, normalized_form, and _warnings. It explicitly bounds scope ('identity and coverage only — not facts or statements'). Nothing an agent needs 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 each identifier, but the description adds meaning: that ticker may be any symbol the company ever traded under, that cik may be any CIK filed under, and that current values plus tickers[]/sec_filings_urls[] come back. That is more than restating the schema, though much of the per-identifier example text duplicates it.

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

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

States a specific verb and scope ('Resolve one company and return its identity plus a coverage summary') and explicitly distinguishes itself as the entry point that precedes get_filing_facts, query_line_items, get_filing_statement, etc. An agent can place it in the workflow 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?

Explicitly defines when to use it ('when you only know a company name/ticker and need to discover what filings exist') and names the downstream tools it feeds, plus the constraint to provide exactly one identifier. This is clear when-and-how guidance rather than implied usage.

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, so the safety profile is settled. The description nonetheless adds real non-structured behavior: L0–L3 resolution tiers with per-tier credit costs (10/20/30/50) itemised in credits_by_line_item, the _warnings entry flagging dimensional results, and that light_weight_mode is charged identically. Return format is also described since no output schema exists. This is close to a 4, but the tier/credit model is dense and partly redundant with the schema's light_weight_mode text.

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?

Front-loaded with purpose and primary identification logic before branching into alternatives. The block is long, but nearly every sentence (cost tiers, warnings, alternative tools, ordering caveat) carries operational information rather than 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 compensates by explaining the return shape (_resolution_level, credits_by_line_item, dimensional_breakdowns, _warnings, fact_ids positions) and typical pitfalls (multi-concept ordering is a recommendation only). An agent has what it needs to call 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 description coverage is 100%, so the schema already documents each parameter, establishing a baseline of 3. The description adds value beyond it: how line_items resolve through L0–L3 tiers and what _resolution_level reports back, and the ordering/cost consequences of the choice – semantics the flat schema does not 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?

Specific verb+resource (fetch XBRL facts for a single filing by line-item name) with an example list. It explicitly carves out scope against siblings: 'Returns consolidated totals only' and routes slice/dimension work to get_dimensional_breakdown_by_fact_id / get_dimensional_breakdown_by_line_item, and fact_id lookups to get_filing_facts.

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-and-how: identify the filing with filing_id OR ticker + fiscal_year (+ quarter); form_type defaults to 10-K with 20-F/40-F for foreign issuers; and fallback guidance when unsure of a name ('use list_filing_statements / get_filing_statement'). Alternatives are named by purpose, not just listed.

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 annotations already declaring read-only/idempotent/non-destructive, the description still adds substantial behavioral context: ordering (newest first), excluded content (original text and amendment history), pagination cap (page x page_size <= 500, default 5, max 10), plan history window, and a dynamic credit cost of 65-280 per page that is charged even on empty result sets and on a 504 timeout. The cost-charged-on-empty/timeout disclosure is precisely the kind of non-obvious trait an agent needs.

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?

Every sentence carries distinct load - scope, return shape, date semantics, routing, limits/cost, and endpoint - and the most decision-relevant facts (what it screens and what it returns) come first. It is dense and clause-heavy rather than wasteful, though the packed constraint clauses make it slightly harder to scan than an ideal entry.

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, zero-required read tool with no output schema, the description covers return content and exclusions, ordering, all key filter semantics, pagination limits, cost model, plan gating, related tools, and the endpoint. Nothing material an agent needs 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 description coverage is 100%, so the baseline is 3, but the description adds genuine semantics beyond the schema: dates are said to filter filing_date, and as_of_date is clarified as 'bounds filing_date like end_date, with no start,' plus the pagination arithmetic (page x page_size <= 500) restated as a constraint. It adds meaning rather than repeating field labels.

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: 'Screen corporate events across companies and filing dates,' and the second sentence defines exactly what is returned (filings with matching section summaries, source links, amendment status) and what is not (original text, amendment history). It names list_event_types and get_event_filing as related tools, though it never positions itself against the close sibling list_event_filings, which is the one ambiguity an agent would likely hesitate over.

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 routing guidance: 'Use list_event_types to choose Item codes, and get_event_filing with a returned id for the complete filing,' which tells the agent both the prerequisite step and the follow-up tool when summaries are insufficient. It also states the plan prerequisite (Pro or higher) and the history-window constraint, so when-not-to-use is 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?

Annotations already declare a safe read-only, idempotent operation, and the description adds substantial behavior beyond them: grouped vs flat return semantics, row fields, no-holding filings excluded from row results, a dynamic credit cost charged even on empty results and 504 timeouts, Pro-plan gating, and history/coverage limits.

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?

Front-loaded with purpose and dense with useful detail; every sentence adds operational value (returns, cost, plan limits, pagination cap). It is a single long paragraph rather than clearly segmented, which slightly reduces scannability.

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 12 parameters, nested filter objects, no output schema, and no annotations beyond safety hints, the description covers return shape, grouping behavior, edge cases, cost, and access requirements. An agent has enough to call this correctly without further 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, but the description adds real meaning: shared operators for both filter objects, the role of holdings_count and shares_owned_total in grouped mode, row-level fields, and the shares_owned vs split_adjusted_shares_owned choice.

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: 'Screen Form 3 holdings across the whole library,' with the two filter surfaces named. It clearly separates this screener from a simple listing, but does not explicitly name a sibling tool to route against.

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?

Gives clear usage context through operator syntax, filter grouping, and a concrete decision rule: filter on split_adjusted_shares_owned when the window spans a corporate action. It does not state when-not to use this tool or name alternative tools for simpler lookups.

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/non-destructive, and the description layers on non-obvious traits: credit cost of 65-920 charged even on an empty result set and on 504 timeouts, Pro-plan gating, history-window truncation, and the grouped-mode subtlety that txn_count is the company's full hit count rather than the page's.

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?

Front-loaded with purpose and filter model, then semantics, then constraints and endpoint. It is dense but each sentence carries operational payload; no filler, though the volume is near the upper limit for a single paragraph.

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 enumerating returned fields (accession_number, filing_date, source_url_prefix, insiders, computed block, issuer_cik), explaining grouped vs flat output, and covering pagination, cost, plan tier, and the backing endpoint plus documentation reference. Nothing material for correct 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?

Schema coverage is 100%, so the schema baseline is already 3; the description adds meaning beyond it with the operator set (>, >=, <, <=, between [lo, hi]), the guidance to filter on split_adjusted_shares/price during corporate actions, and the distinction that issuer_cik on a flat row is the filing CIK versus the group's current CIK.

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 with scope: 'Screen insider trades across the whole library,' and immediately distinguishes its two-layer filter architecture (trade_filters vs aggregate_filters) plus its return shape. This separates it from plain listers like list_insider_transactions, though no sibling is named explicitly.

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?

Gives real usage context — Pro plan required, results bounded by plan history window, page x page_size <= 500, dynamic credit cost — but never states when to choose this over list_insider_transactions or get_insider_transactions_by_id. Usage is implied by the screener framing rather than spelled out.

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 cover read-only/idempotent/non-destructive, yet the description adds substantial context beyond them: dynamic credit cost (89-1825), lookback auto-clamping with _warnings population, silent exclusion of out-of-coverage companies, Pro+ gating that returns 403, and a per-row classification block. These are exactly the non-obvious behaviors an agent needs.

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: required where-shape first, then operators and temporal modifiers, then optional params, then billing/plan behaviors. A few clauses duplicate the schema (tickers whitelist <=100, page*page_size <=500), which is minor waste in an otherwise tight block.

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-param tool with nested objects and no output schema, the description covers the prerequisites, plan gating, billing, result-side behaviors (_warnings, classification), and pagination constraints. An agent has everything needed to construct a valid request and interpret the response.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: temporal modifiers are mutex per leaf, lookback is clamped to the plan window, sectors is Pro+-only, and include_metrics_using_filing_date_price gates 13 valuation ratios. It also restates some schema facts (tickers <=100, page limits), which keeps it just short of a 5.

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 companies by a filter DSL over the 82-metric catalog'), and the tool is clearly distinguishable from siblings like list_companies or lookup_company. The DSL-shaped nature of the input is stated up front so an agent knows this is the screening entry point.

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?

Gives a concrete prerequisite ('Pre-run list_screener_filters once to discover supported metric ids + operators') and names the plan gate (Pro+). However, it never states when to prefer this over sibling lookups such as lookup_company or list_companies, so routing among alternatives is left to inference.

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