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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the description need not restate that. It does add one meaningful trait beyond the annotations: this tool summarizes rather than returning raw filing text. It says nothing about summary length, behavior when no 8-K exists, or rate 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?

Short and front-loaded, with the core purpose in the first sentence. The Args/Returns block is slightly redundant given a structured schema and output schema exist, but it is not bloated.

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, read-only tool with an output schema present, the description covers the input and the nature of the result. Remaining gaps (summary length, no-filing case) are minor given the output schema carries the return shape.

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 0%, so the description is the only place 'ticker' is defined; it does so as 'Stock ticker symbol'. That is the minimum needed but adds no format guidance (e.g., case, exchange suffix) for the sole required parameter.

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

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

The description states a specific verb pair ('get and summarize') and a specific resource ('the latest 8-K filing for a company'), which is enough to distinguish it from list-style siblings like get_recent_8k_filings and raw-retrieval tools like get_filing_content. It does not, however, name any sibling explicitly to sharpen the boundary.

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?

There is no when-to-use guidance, no exclusion criteria, and no mention of alternatives such as get_recent_8k_filings or get_filing_content. The 'latest' qualifier implies a scenario but the agent must infer when this tool beats its many 8-K/filing siblings.

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, and the description adds behavior beyond them: pagination via has_more/next_offset, a size-limit fallback that returns link_only, the fact that size is checked BEFORE downloading, and case-insensitive matching. These are exactly the operational traits 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?

Front-loaded with the core purpose, then mode-by-mode bullets that each earn their place. The trailing 'Args:' and 'Returns:' blocks partly restate defaults already present in the schema, adding mild redundancy.

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

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

For a four-parameter tool with pagination and mode branching, the description is nearly complete: it covers modes, continuation, and the oversized-document fallback, and an output schema exists so return values need not be spelled out. The only gap is routing guidance versus sibling filing tools.

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 0%, so the description must carry all parameter meaning; it does document all four (filing_url with URL example, max_length as chars per page, offset as character position, search as case-insensitive phrase). It misses only edge details such as how max_length interacts with the size limit or the valid bounds of offset.

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 ('Read or search the text of one SEC filing document') and enumerates three named modes with distinct return shapes. An agent can distinguish this from siblings like get_filing_content or full_text_search 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 clear operational context: modes are chosen automatically, and it explicitly instructs to call again with offset=next_offset when has_more is true, or use offset=position after a search. It does not, however, say when to prefer this tool over the many filing-reading siblings (get_filing_content, get_filing_documents, full_text_search).

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, open-world behavior. The description adds useful operational context beyond that: coverage since 2001, default date range, newest-first ordering, and that results include company, form, date, and document link.

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

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

The description is front-loaded with the core purpose, then organized into compact Args and Returns sections. Every line adds useful information for invoking or interpreting the tool, with no wasted prose.

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?

An output schema exists, so return-value explanation is not required. The description still summarizes return contents and ordering while fully covering the search scope, parameter defaults, and invocation constraints needed for this tool.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does: it explains query syntax, exact phrase usage, form_type examples, date formats and defaults, and limit range/default for all five parameters.

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: full-text search across every EDGAR filing since 2001, including exact-phrase support. The 'full text' scope clearly differentiates it from metadata-oriented sibling tools such as search_filings and get_company_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?

The description gives clear context for what the tool searches and documents defaults for date filters, but it does not explicitly say when to use this tool versus search_filings or get_company_filings. Usage is therefore implied rather than fully guided.

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 open-world semantics, so the bar is lower. The description still adds value by disclosing that it returns the *latest* report period and by explaining the two different row granularities (issuer-level vs security-level).

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 summary sentence followed by compact Args/Returns sections; every line carries information. Slightly verbose in the Returns block, but the top_issuers vs top_positions distinction earns its space.

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?

An output schema exists, so return-value explanation is not strictly required, yet the description clarifies the two result groupings an agent must choose between. Coverage of a two-parameter tool is otherwise 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 0%, so the description must carry the load, and it does: ticker_or_cik is explained as manager ticker or CIK with concrete examples ('BRK-B', '1350694'), and limit is clarified as 'number of top positions to return' with a default of 25.

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: 'Get the latest 13F portfolio of an institutional investment manager.' That is concrete enough to separate it from nearby tools such as get_beneficial_ownership and get_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?

Usage is implied by the resource ('13F portfolio'), and the Returns text hints at selection ('use this for largest holdings'). But there is no explicit when-to-use/when-not guidance or comparison to alternative holdings-related tools.

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, openWorldHint and destructiveHint=false, so safety behavior needs no restating. The description adds that the listing is exhaustive and filtered by search_term, but says nothing about pagination, result size limits, or rate/API-status behavior for an SEC-backed call.

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

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

Purpose and the when-to-use hint are front-loaded and useful, but the Args/Returns blocks largely restate the input schema and the existing output schema. The return enumeration is redundant given has_output_schema=true.

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

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

For a simple 2-parameter discovery tool with annotations and an output schema, the description covers purpose, filter behavior, and ticker input adequately. The main omission is guidance on what to do with the results (e.g., feed metric names into the metrics-fetching tool).

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

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

Schema description coverage is 0%, so the description must compensate, and it does: ticker is described with concrete examples ('GME', 'AAPL') and search_term is explained as a filter with examples ('EBITDA', 'Revenue', 'Debt'). Only the exact matching semantics (substring vs exact) remain unstated.

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 available financial metrics ... from SEC XBRL data') and clarifies the discovery role versus metric retrieval tools. It does not, however, distinguish itself from close siblings such as get_company_facts or get_xbrl_frames, and it references 'specific_metrics', which is not 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?

Explicitly tells the agent to call this before requesting metrics ('Useful for AI to find exactly which metrics are available before requesting them'), which is clear usage context. It stops short of naming an alternative sibling or stating when the tool is unnecessary.

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, open-world and non-destructive, so the safety profile is covered. The description adds useful domain context by defining 13D/13G intent, but says nothing about result volume, ordering, or rate limits. With annotations carrying the behavioral load, this is adequate but thin.

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 is front-loaded in a single sentence, followed by a compact Args/Returns block. The docstring-style formatting is slightly boilerplate but nothing is padded or 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?

An output schema exists, so return values need not be spelled out in detail. Purpose and all three parameters are documented, and the tool is a read-only fetch with no side effects to warn about. Only the missing when-to-use guidance against sibling tools keeps it from being fully 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 description coverage is 0%, so the description is doing all the work, and it does it: ticker as the stock symbol, limit as the number of reports, and schedule with its default ('all') and the meaning of each option. Decent compensation, though it omits valid range or upper bound for limit.

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: 'Get beneficial ownership reports (13D, 13G) for a company.' That is enough for an agent to know it fetches ownership filings rather than holdings or insider trades. It stops short of explicitly distinguishing itself from nearby siblings like get_13f_holdings or get_insider_transactions.

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?

There is no when-to-use guidance, no prerequisites, and no named alternative. The parenthetical definitions of 13D (activist or control intent) and 13G (passive holder) explain the filing types but describe the parameter, not when an agent should pick this tool over a sibling.

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, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that data is returned 'over time' (a time-series hint), but says nothing about rate limits, auth, or data sources 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?

Front-loaded with the core purpose followed by compact Args/Returns sections. The Args section largely restates the schema, which is minor waste, but overall it is tight and readable.

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

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

The tool is a simple read-only lookup with a covered output schema and rich annotations, so little is required. Still, the missing sibling differentiation (get_xbrl_frames vs get_company_concept) leaves an agent without enough context to select correctly among near-identical tools.

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 0%, so the description must carry parameter meaning, and it does document both params: ticker as the stock symbol and concept as an XBRL concept with three concrete examples. That compensates partially, but format/casing expectations for ticker and valid concept names beyond the examples remain undocumented.

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 ('Get specific financial concept data for a company') and clarifies what a concept is with concrete XBRL examples. However, it does not distinguish itself from close siblings like get_xbrl_frames or get_company_facts, so an agent cannot route between them from the description alone.

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?

No when-to-use, when-not-to-use, or alternative-tool guidance is given. With siblings like get_xbrl_frames and get_company_facts in scope, the agent gets no help deciding which tool to call.

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, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description only restates that a dictionary of facts is returned, adding little behavioral context such as freshness, rate limits, or data source 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?

Short and front-loaded, with the purpose in the first sentence. The Args/Returns scaffolding is mild boilerplate but does not bloat the 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?

An output schema exists, so return-value detail need not be repeated, and the single-parameter shape is simple. However, with 0% schema coverage and no usage guidance against a crowded sibling set, the definition is only minimally 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 description coverage is 0% and there is one required parameter, so the description carries the burden. It does slightly clarify the ticker as a 'stock ticker symbol', but adds no format, exchange, or casing guidance.

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 (Get) and resource (company facts) with the data source (SEC XBRL), which is clearer than a bare restatement. It only weakly differentiates from siblings like get_company_concept or get_xbrl_frames, which also serve XBRL data, so no explicit sibling distinction.

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?

No guidance on when to use this tool versus the many related siblings such as get_company_concept, get_company_filings, or get_available_metrics. The agent is left to infer the selection criteria entirely.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the 'None returns all forms' default behavior; it omits pagination, ordering, or result-count behavior, so it contributes limited extra context.

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

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

Front-loaded single-sentence purpose followed by tightly grouped Args and Returns sections; no sentence is wasted. The trailing 'Returns: Dictionary containing filing information' is thin but harmless.

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?

A read-only lookup tool with annotations covering safety and an output schema covering the return shape, plus full parameter documentation in the description. The only meaningful gap is the absence of sibling disambiguation, which is arguably outside the description's core burden.

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 0%, so the description carries the full load and mostly does: it documents all five parameters, gives ticker examples, explains form_type accepts a string or list and screens to all forms when None, states the limit default, and specifies the YYYY-MM-DD date format. It stops short of constraints like a max limit or date-range validation rules.

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 ('Get') plus resource ('SEC filings') and a clear scoping key ('by ticker symbol'). It is distinguishable at a glance, but the description never differentiates itself from close siblings like search_filings or get_latest_10k, so it stops short of a 5.

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

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

No when-to-use guidance and no mention of alternatives despite a crowded sibling set (search_filings, get_latest_10k, get_filing_content, get_recent_8k_filings). The agent gets no signal for choosing this tool over those.

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/openWorld and non-destructive, but the description adds substantial behavioral context beyond them: a 25MB size gate, pagination via has_more/next_offset, the 50,000-character first-page limit, token-efficiency implications of each mode, and the ai_note handoff. This is unusually rich disclosure for a read tool.

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 content is information-dense and mostly earns its place, but the ASCII box art consumes significant space for stylistic rather than informational value, and the marketing framing ('SMART & EFFICIENT') is filler. Front-loading is acceptable but the boxes make it bulkier than needed.

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 4-parameter tool with 0% schema coverage and an output schema present, the description covers modes, workflow, file-size handling, pagination, and every parameter thoroughly. Nothing an agent needs to invoke it correctly appears to be 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 0%, so the description carries the full burden, and it largely delivers: it explains ticker examples, filing_type values ('10-Q', '10-K', '8-K') and the None=latest default, get_full_content behavior, and specific_metrics with a concrete example plus the None fallback. Minor gaps remain (exact metric-name casing rules), so not a full 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?

The description states a clear verb+resource ('Get SEC financial data') and explains its dual-mode nature (generic vs specific metrics). It differentiates from siblings by naming get_available_metrics and download_filing_text as workflow partners. However, the headline purpose is somewhat muddled by hype ('SMART & EFFICIENT') and the name suggests filing content while the body emphasizes financial 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?

Strong when-to-use guidance: it distinguishes generic mode (omit specific_metrics) from specific mode (provide the parameter), gives a concrete TTM workflow, and points to get_available_metrics for discovery and download_filing_text/full-text search for continuation. It lacks explicit when-NOT-to-use guidance versus siblings like get_latest_10k or get_company_facts, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds real value by disclosing that any URL within the folder is accepted (tolerant input resolution) and by outlining the returned dictionary structure, going 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?

Front-loaded with the core behavior in one sentence, then compact Args and Returns sections. The Returns block partly duplicates the existing output schema, so it is slightly less than maximally efficient.

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

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

A simple one-parameter read tool with annotations and an output schema; the description covers the input's flexibility and the general return shape. Nothing essential for correct invocation is missing, though sibling differentiation would make it airtight.

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 0%, so the description must carry the parameter burden, and it does: it explains that filing_url can be any URL inside the filing folder and gives the concrete SEC Archives path shape. It stops short of edge cases (e.g., what happens with a non-filing URL), so not 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?

States a specific verb and resource ('List every document in a filing') and enumerates scope (main document, exhibits, XBRL, XML) plus returned fields. It is clearly distinguishable from siblings like get_filing_content or get_filing_size, though it never names those alternatives 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?

The args note ('Any URL inside the filing folder') tells the agent what input to supply, which implicitly defines when the tool applies. However, there is no explicit guidance on when to prefer this over get_filing_content, get_filing_size, or download_filing_text, leaving the choice to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond them: the data source (EDGAR filing index) and the meaning of the returned 'recommendation' values. Slightly short of 5 only because it doesn't mention lookup failures for malformed URLs.

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 the usage rule, then compact Args/Returns blocks. Every sentence earns its place with no redundancy.

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

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

For a one-parameter read-only lookup with an output schema, this covers purpose, usage routing, data provenance, and return contents. 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 0% and the single property is documented only as 'Filing Url'. The description compensates by clarifying the parameter is a filing document URL and giving a concrete EDGAR URL pattern, adding real meaning beyond the schema.

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

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

States a specific verb and resource ('Get the exact size of a filing document') plus a timing constraint ('BEFORE downloading it'), and explicitly distinguishes itself from the sibling download_filing_text. An agent can tell it apart from the other filing tools 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?

Explicitly states the decision this tool supports — reading text via download_filing_text vs giving the user a link only — and names the alternative tool. The when-to-use condition is fully spelled out rather than left to inference.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety and repeatability profile is covered. The description adds that the tool returns insider transaction information and names the relevant SEC forms, but it does not discuss rate limits, authentication, or characteristics of the returned data beyond the generic return statement.

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 short and front-loaded with the core purpose. The Args and Returns sections are somewhat boilerplate but still compact and not wasteful.

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

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

Given that the tool is a simple read-only lookup with only two parameters, rich annotations, and an output schema, the description provides enough context to invoke it correctly. The main missing element is guidance on sibling selection, which is not required for correct invocation but would improve routing.

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 0%, so the description must compensate for undocumented parameters. It explains that ticker is a stock ticker symbol and limit is the number of transactions to return, which meaningfully clarifies both parameters, but it omits the default value of 20 and any limits or formatting details for ticker.

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

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

The description states a specific action and resource: retrieving insider trading transactions, specifically Forms 3, 4, and 5, for a company. It is clear what the tool does, though it does not explicitly differentiate itself from related sibling tools such as get_beneficial_ownership.

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 no guidance on when to use this tool versus related alternatives, nor does it mention any preconditions or exclusions. The agent must infer its role from the name and sibling list alone.

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

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

Annotations already cover readOnly/idempotent/openWorld/non-destructive, so the bar is lower, yet the description still adds substantial behavior: the preview is capped at 10,000 chars covering only the cover page and first statements, and a preview_is_partial flag signals truncation. That is exactly the operational context an agent needs to sequence follow-up 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?

Front-loads the purpose and preview scope, then uses Args/Returns sections for the rest; the paging instructions earn their place. Slight redundancy in restating the return dictionary fields that the output schema already covers keeps it from a 5.

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

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

An output schema exists so return keys needn't be explained, yet the description goes further and documents the truncation/windowing workflow. Nothing an agent needs to call this correctly or chain into follow-up tools 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?

Only one parameter and schema coverage is 0%, so the description must carry the burden; it does describe ticker as 'Stock ticker symbol'. That is minimal but sufficient for a single self-evident input, though it adds no format or validation detail.

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

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

States a specific verb and resource ('Get the latest 10-K filing for a company') and immediately scopes the return ('filing link plus a SHORT preview of its text'). It distinguishes itself from download_filing_text by positioning that sibling as the follow-up for the full text, so an agent can tell the tools apart without opening schemas.

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

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

Gives an explicit conditional route: 'When preview_is_partial is true, follow read_more' and names the exact alternative calls (download_filing_text with offset or search). The when/when-not split between this tool and the full-text downloader is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: the preview is limited to the first 10,000 characters (cover page and first statements), the preview_is_partial flag signals truncation, and it explains how to page through or jump within the full filing using download_filing_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?

The description is front-loaded with the core action and return shape, then structured with Args and Returns sections. It is slightly redundant in places (e.g., 'SHORT preview' followed by the 10,000-character limit and later the Returns list), but every sentence contributes useful information and there is no filler.

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

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

Given a single-parameter read-only tool with full annotations and an output schema, the description covers the key behavior an agent needs: what is returned, the preview limit, the partial-preview flag, and how to retrieve more. It omits auth requirements and error behavior, but for this simple, annotated tool the definition 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 description coverage is 0%, so the description must carry the burden. It identifies ticker as a 'Stock ticker symbol,' which gives the parameter's meaning, but adds no format examples, case requirements, or exchange conventions. For a single simple parameter this is minimally adequate but not rich.

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 ('Get the latest 10-Q filing') and clarifies it returns a filing link plus a short preview, which implicitly distinguishes it from get_latest_10k and from full-text retrieval via download_filing_text. It does not explicitly name those siblings or contrast with other filing tools, but the core purpose 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 explains what to do when preview_is_partial is true (follow read_more with download_filing_text), which is useful continuation guidance. However, it gives no explicit guidance on when to choose this tool over siblings like get_latest_10k, get_company_filings, or get_filing_content; usage is implied 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered externally. The description's only added behavioral content is the DEF 14A form type; it says nothing about result ordering, pagination, or behavior on an unknown ticker. With annotations carrying the safety burden, a 3 fits.

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 short and front-loads the actual purpose, but the 'Args'/'Returns' scaffolding duplicates schema and annotation content, and 'Returns: Dictionary containing proxy statement information' is vague filler given an output schema exists. Mild padding rather than tight prose.

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?

Because an output schema exists, the return shape needn't be explained, but the description omits useful context such as ordering of returned statements, what happens when the ticker has no DEF 14A, and how it relates to the other filing tools. For a simple 2-param read tool this is adequate but with clear 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 0%, so the description must compensate, and it does document both parameters ('ticker: Stock ticker symbol', 'limit: Number of proxy statements to return'). However, these are near-restatements of the parameter names with no format, default-value, or ordering detail, so it only partially fills the coverage gap.

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 gives a specific verb and resource ('Get proxy statements') and adds the filing form type (DEF 14A), which lets an agent distinguish it from generic filing tools like get_company_filings or search_filings. It stops short of naming a sibling it should or shouldn't be used instead of.

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?

There is no guidance on when to use this tool versus the many filing-retrieval siblings (get_company_filings, search_filings, get_filing_content), and no prerequisites or exclusions are stated. The agent must infer usage entirely from the tool name.

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), and the description adds real behavioral detail beyond them: the 5,000-character preview cap, the preview_is_partial flag, and the escalation path via read_more/download_filing_text. Auth requirements and pagination across the limit are not addressed, but the truncation behavior is well disclosed.

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

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

Front-loaded with the core purpose and the critical preview constraint, then organized into Args/Returns. The Returns block is partially redundant since an output schema exists, which is the only wasted space.

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

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

For a two-parameter read tool with annotations and an output schema, the description covers what the agent still needs: the truncation limit, the partial-preview signal, the recovery path, and both arguments. The return-value listing is unnecessary given the output schema, but nothing essential is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden, and its 'Args' section documents both parameters (ticker: stock ticker symbol; limit: number of recent 8-K filings). The explanations are terse but sufficient to invoke the tool correctly.

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 ('Get recent 8-K filings for a company') plus the preview scope, so the agent knows exactly what comes back. It does not, however, distinguish itself from the many filing siblings (get_company_filings, get_filing_content, search_filings), which keeps it below a 5.

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

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

Gives a concrete follow-up rule: 'When preview_is_partial is true, follow read_more: download_filing_text(...)', naming the sibling and the triggering condition. It omits when NOT to use this tool versus alternatives like get_company_filings, so it falls short of an explicit when/when-not statement.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuine domain context by defining what each returned list contains and the underpinning filing types (424B4, S-1, F-1), which helps the agent interpret results; it does not, however, mention rate limits or any behavioral caveats.

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

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

Front-loaded with the one-line purpose, then structured Args/Returns sections. Every line carries information, though the docstring formatting is slightly heavier than a tight prose definition would be.

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?

Purpose, both parameters, and the two return categories are all covered, so an agent has enough to invoke and interpret the call. An output schema exists, so explaining returns is a bonus rather than a requirement, and the definition supplies it adequately.

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 0%, so the description must carry the load, and it does: 'limit: Max companies per list' and 'days: Look-back window in days' fully explain both parameters with their defaults. It does not add much beyond these definitions, but the gap created by the empty schema is closed.

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 ('Get recent IPO activity from EDGAR') and unpacks it into the two result sets it produces (priced prospectuses vs. new registrations). No sibling tool covers IPOs, so the agent can route here unambiguously.

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

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

Usage is implied by the name and description, but there is no explicit when-to-use, when-not-to-use, or reference to any alternative/sibling tool. The look-back semantics hint at 'use for recent activity' but no boundaries are drawn.

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, openWorld and non-destructive, so the safety profile is covered. The description adds only that connectivity is checked in addition to status, and it never says what a degraded result looks like or whether the tool can be used to verify credentials. Useful but thin beyond what annotations provide.

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

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

The operational sentence is front-loaded and tight. The trailing 'Returns: Dictionary containing API status information' is largely redundant because an output schema exists, which costs it one point but not more.

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 diagnostic tool with an output schema and full annotation coverage, the definition supplies enough to call it correctly. It is only missing practical framing such as when to invoke it or how to interpret a failure result.

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 to document. The schema is an empty object and the description correctly implies no inputs are required, which is the baseline for no-parameter 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 names a specific verb and resource: 'Check SEC API status and connectivity.' That is clearly distinguishable from every sibling, all of which retrieve filings or company data. It stops short of a 5 only because 'status' is a slightly generic notion, but an agent can still tell what this tool is for.

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 says nothing about when to call this instead of alternatives. The sibling run_self_test looks like it also performs a health check, yet the description draws no distinction and gives no trigger condition, for example 'call before other SEC tools if requests are failing.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only that results are 'ranked by value' and that the default is the top 20 companies, which is modest behavioral context; it says nothing about rate limits, result volume ceiling, or coverage gaps. With annotations carrying the safety burden, a 3 is appropriate.

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 opening sentence states the core operation, followed by cleanly labeled Args/Returns blocks. The Args list is dense but every line adds real information; the Returns line lightly duplicates the existing output schema, which is the only small redundancy.

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

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

The output schema covers return values and annotations cover the safety profile, so the description's remaining job is parameter meaning and it fulfills that well. What is missing is guidance on scope limits (e.g., how many companies qualify, server-side rate limits) for an openWorld tool, but nothing essential to invoking it correctly is absent.

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 0%, so the description must carry the full burden — and it does. All five parameters get meaning: concrete XBRL tag examples for concept, three distinct period formats ('CY2024', 'CY2024Q3', 'CY2024Q4I') with their semantics, enumerated unit values, enumerated taxonomy values, and the limit default. This compensates completely for the empty schema descriptions.

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

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

Specific verb ('Compare'), resource ('one financial concept'), and scope ('across ALL reporting companies for one period'). The explicit cross-company scope implicitly separates it from the single-company sibling get_company_concept, so an agent can route correctly without opening schemas.

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

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

Usage is implied by the phrase 'across ALL reporting companies for one period' — i.e., use for cross-company peer comparison rather than single-entity lookup. However, no alternative tool is named and there are no explicit when/when-not conditions or prerequisites, so the agent must infer the routing decision.

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=true, idempotent=true, destructive=false, and openWorld=true, so the safety profile is fully covered structurally. The description adds the useful scope fact that it exercises ALL tools (not a single subsystem), but says nothing about runtime, side effects on downstream services, or failure behavior. Adds modest value over 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?

Very short and front-loaded, which suits a no-arg tool. The trailing 'Returns: Dictionary containing test results' sentence is largely redundant given an output schema exists, but it costs little.

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 no-parameter diagnostic with rich annotations and a present output schema, the description covers the essential scope. It stops short of stating how long the test takes or what a failure implies, which an agent running it might want to know.

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?

Zero parameters, so there is nothing to document and the baseline is 4. Schema coverage is reported as 100% and the empty object schema is unambiguous.

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 ('Run') and resource ('comprehensive self-test of all SEC-AI tools'), with scope made explicit. None of the sibling tools (all SEC data-retrieval tools) overlap with this diagnostic purpose, so an agent can immediately tell it apart.

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?

There is no guidance on when to run this diagnostic — before a session, after failures, as a health check — and no prerequisites or cost/time warnings. Usage is only implied by the tool name, 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 declare readOnlyHint, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is covered. The description adds nothing beyond that – no mention of result caps, rate limits, auth requirements, or what happens with zero matches – so it contributes no behavioral context not already in structured data.

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 purpose is front-loaded in a single sentence and the parameter list is scannable. The trailing "Returns: Dictionary containing search results" is redundant padding given a full output schema exists, which is the only real 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?

With an output schema present, the description needn't explain return values, and annotations cover the safety profile, so the remaining obligation is parameter clarity. It meets that at a minimum level given 0% schema coverage over five parameters, though it leaves form_type values and limit/pagination semantics unexplained.

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 0%, so the description must carry the parameter burden. It does list all five parameters with brief glosses and, usefully, the date format (YYYY-MM-DD) that the schema omits. But the glosses are terse (e.g. "SEC form type to filter by") and omit accepted form_type values, whether multiple values are allowed, or how the limit interacts with paging.

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 ("Search SEC filings") and notes the primary axis (company name) plus open criteria. However, it never distinguishes itself from overlapping siblings such as get_company_filings, full_text_search, or get_filing_content, so an agent cannot tell which filing-search tool to pick without comparing 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?

There is no when-to-use guidance and no mention of alternatives, despite several sibling tools that clearly overlap (full_text_search, get_company_filings, download_filing_text). The agent is left to infer the selection criteria entirely on its own.

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