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

Annotations only declare readOnly/openWorld, so the description carries real weight and adds substance: newest-first ordering, amendments always included, the 5/10 read cap, 'structured': false plus a URL for legacy filings, and the crucial joint-filer warning not to sum counts across reporting persons. It does not discuss rate limits or what happens when a holder has no filings, which keeps it below 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?

Information is front-loaded — the what, then the two input modes, then return shape, then interpretation caveats — and nearly every sentence carries distinct value. It is long and a few clauses (limit/offset restatement, 'a signal worth noting') are expendable given the schema already documents paging.

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 fully covers the return shape: each reporting person's name, type, sole/shared voting and dispositive power, aggregate shares, percent of class, plus purpose/source_of_funds for 13Ds and the structured/URL pair for old filings. Combined with the joint-filer caution, an agent has everything needed to call and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining that 'ticker' doubles as a holder CIK and what each form_type value implies behaviorally (13D = may seek control with stated purpose; 13G = passive/institutional; omit for both). Pagination guidance largely restates schema text, limiting the upside.

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 ('Who owns more than 5% of a company: Schedules 13D and 13G') and pins scope to filings-based ownership rather than aggregated data. An agent can distinguish it from sec_institutional_holdings (13F) and sec_insider_transactions (Form 4) 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 both usage modes — company ticker/CIK for holders, holder CIK (via sec_lookup_cik's 'name') for the companies that holder reported on — plus when to use the form_type filter and how to page with 'next_offset'. It also routes pre-18-Dec-2024 HTML filings to sec_filing_text, naming the sibling alternative directly.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real value beyond that: default page size of 100, the 'matched' total, and the next_offset->offset paging loop, plus the fact that descriptions are omitted unless requested. It does not state row ordering or what a concept with no recent data looks like, so it is solid but not rich.

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 downstream call, then narrowing, then paging, then the descriptions caveat. The Palantir parenthetical is long but teaches the failure mode that motivates the 'latest' check, so it 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?

There is no output schema, and the description compensates by describing the returned row shape (concept, label, latest) and the paging envelope ('matched', 'next_offset'). Combined with the 6-parameter schema, an agent has everything needed to call and paginate 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 schema already documents all six parameters, and the description largely restates them. It does add semantic value for 'query' (matches name OR label, case-insensitive, with realistic examples) and for the offset/next_offset handshake, which is a response-field contract absent from the schema. That lifts it slightly above the baseline but not far.

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 the XBRL concepts a company reports) and frames it as a discovery step whose output feeds sec_financial_concept. An agent can distinguish it from sec_financial_concept (values) and sec_xbrl_frames (cross-company) 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?

Explicit ordering guidance: call this first to find the concept name, then query values with sec_financial_concept. Adds the practical rule to prefer concepts whose 'latest' is current, with a concrete warning that tag names drift (Palantir's revenue concept), plus when to use 'query' and when to enable include_descriptions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the data source (SEC EDGAR) and the returned field set, but says nothing about behavior for invalid or unknown tickers, latency, or whether results are cached – minor gaps for a simple read.

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?

One sentence, front-loaded with the verb and source, then a tight colon-delimited field list. No filler and nothing that could be cut without losing 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 one well-documented parameter, no output schema, and annotations covering the safety profile, the description is nearly complete – the field enumeration effectively substitutes for a return-value description. Only the failure mode for an unrecognized ticker/CIK 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% and the single parameter already documents both the ticker form and the CIK fallback for delisted/acquired/renamed companies. The description adds no parameter semantics beyond the schema, so the 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 ("Get general information") and resource ("a public company from SEC EDGAR") and enumerates the exact data returned, which implicitly separates it from sec_company_facts (financial data) and sec_lookup_cik (CIK resolution). It never names those siblings explicitly, so differentiation is inferential rather than stated.

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 field list – an agent can infer this is the profile/metadata call, not the financial-data call. There is no explicit when-to-use statement, no when-not-to-use, and no pointer to sec_company_facts or sec_lookup_cik when those would be the better choice.

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?

Adds meaningful context beyond annotations: the SEC fair-access policy rationale, the required setup ordering, and the need to obtain user permission before collecting the email. Annotations already cover mutation/idempotency safety, and the description supplies the policy and workflow behavior that matters here.

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 short sentences, front-loaded with 'REQUIRED SETUP' and then the reason, ordering, and user-permission instruction. Every sentence contributes directly to correct invocation.

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

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

For a one-parameter configuration tool with no output schema, the description covers why it exists, when it must be called, and what the agent must ask the user. Nothing essential 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 already defines the single contact_email parameter and its User-Agent header purpose. The description reinforces that it is the user's email address but adds no format or validation details 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: register a contact email for SEC EDGAR API access. It also clarifies its role as prerequisite setup, which distinguishes it from all sibling SEC data-retrieval tools.

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

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

Explicitly says to call this tool before any other SEC tools and to ask the user for permission and their email address first. That gives precise ordering and interaction guidance, leaving little 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=true and openWorldHint=true, so the safe-read profile is covered. The description adds real context beyond that: HTML-to-text conversion with ' | ' cell joining, 'next_offset' continuation semantics, 20,000-char default pages, up to 10 find matches, and the document-list fallback when no document is named. It does not repeat the annotations, but it also doesn't cover rate limits or SEC-specific access constraints. A 3 reflects solid added context on a tool whose safety profile the annotations already 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 purpose, then pagination strategy, then caveats; every sentence carries information and nothing is decorative. It is a single dense block of ~120 words that would scan faster as short bullets, which is the only real cost.

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, and the description compensates well: it describes the first page's 'sections' list, the document list shape with document types, 'next_offset', and the image count in the response. Given a long-document reader with 8 optional params, that is close to complete, though the exact response envelope is still only sketched.

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 all 8 parameters, and the default 3 applies. The description goes slightly beyond the schema by explaining the 'next_offset' round-trip pattern and what a missing 'document' yields (a document list), which is genuinely useful interaction semantics rather than restatement.

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 ('Read the text of an SEC filing document') and then enumerates the concrete document types covered (10-K, 10-Q, 8-K, proxy, EX-99.1 exhibit). It also implicitly separates itself from the sibling search/list tools by describing them as the sources of the 'url' argument rather than alternatives for reading text.

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 routes the agent: pass 'url' from sec_recent_filings or sec_full_text_search, or 'accession' plus 'ticker'. It also gives a decision rule for the optional modes (use 'section' to read one part, 'find' to locate passages, 'offset' to continue) which tells the agent which control to reach for and when.

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

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

Beyond the read-only annotation, the description discloses default result count, chronological ordering, total_facts, next_offset paging, and amendment exclusion semantics. These are meaningful behavioral details an agent needs to invoke and interpret the tool correctly.

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

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

The description is front-loaded with the core action, then efficiently covers paging, amendment behavior, and helpful concept examples. Every sentence contributes useful information without 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?

The description covers paging and key return counts, which is important because there is no output schema. However, it does not describe the full shape of returned fact records, leaving some return-value structure implicit.

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 practical meaning for the concept parameter by listing common XBRL concepts and reinforces amendment-filter semantics for period/include_amendments. It does not add much beyond the schema for ticker, taxonomy, limit, or 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 and resource: getting historical values for a financial concept from SEC XBRL data. The scope is clear and concept-specific, but it does not explicitly differentiate itself from siblings such as sec_company_facts or sec_xbrl_frames.

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 paging and amendment behavior but gives no explicit guidance on when to use this tool versus alternatives like sec_company_facts or sec_xbrl_frames. Usage is only implied by the first sentence.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond them — amendments are excluded from form filters unless include_amendments is set and returned amendments are flagged, each hit carries a direct document URL, paging can yield fewer than `limit` hits when filtering, and `total` saturates at 10000 with distinct lower/upper/approximate bound flags. These are exactly the non-obvious traits an agent needs before trusting results.

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

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

Front-loaded with purpose and the sibling differentiator, and every sentence carries operational information (quoting, listing mode, amendment semantics, paging, total flags). It is dense to the point of being slightly packed — several parenthetical caveats chain together — but no sentence 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?

For an 8-parameter, no-required-parameter search tool with no output schema, the description covers both search modes, filtering interactions, result shape (URL per hit), paging, and the semantics of the total counters. Nothing material is left for the agent to discover by trial.

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 already 100%, but the description still adds meaning: it explains the offset/next_offset paging contract and the consequence of filtering on page size, and explains the forms/include_amendments interaction at a semantic level. It stops short of documenting ticker/CIK acceptance details beyond the schema, so it is strong rather than exhaustive.

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 the full text of SEC filings from 2001 onward, exhibits included') and explicitly positions itself against siblings as the tool that finds companies by content rather than by company identifier. The example query ('which filers discussed a climate transition plan') makes the distinction concrete.

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 when-to-use guidance (when you don't have the company up front, unlike other tools here) plus a distinct alternative mode: omit the query with a form filter or date range to list filings by form and date, with a worked example (Schedule 13D last week). It also names the quoting convention for exact phrase matching.

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 and openWorldHint annotations, the description explains that it reads filings directly, expands SEC transaction codes into plain language, and preserves footnotes. It also discloses important edge cases: Form 3 holdings semantics, empty holdings with 'no_securities_owned': true, and that Form 144 notices are intents to sell rather than completed trades.

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

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

The description is front-loaded with the core purpose and then adds only operationally important caveats about SEC form semantics, Form 144 notices, and paging. Despite being dense, every sentence contributes useful context for correctly invoking and interpreting the tool.

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

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

For a read-only SEC filings tool with no output schema, the description is complete enough to guide selection and interpretation. It covers return content, Form 3 and Form 144 special cases, code expansion, footnotes, default/max limits, and pagination.

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; however, the description adds meaningful semantics beyond the schema. It clarifies that Form 144 changes the returned data shape, that '4' is the usual form_type, that ticker may also be a CIK for companies without a current ticker, and that limit defaults to 5 and caps at 10 filings.

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: get SEC Forms 3, 4 and 5 insider transactions by ticker, including who bought/sold, timing, shares, price, insider name and role. It is very clear about what the tool returns, but it does not explicitly distinguish itself from sibling tools such as sec_beneficial_ownership or sec_recent_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 gives clear usage context for form_type: '4' is the usual choice, '3' is holdings-only, '5' is annual catch-up, and '144' returns notices rather than executed trades. It also explains default limit and paging behavior. It does not, however, name alternative sibling tools or say when not to use this one.

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

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

Annotations only cover readOnly/openWorld, and the description adds substantial behavior well beyond them: aggregation by CUSIP/class/put-call, sort order by value descending, confidential-treatment omissions, amendments listed rather than merged, licensed CUSIPs meaning no tickers, and default-25/max-100 paging with next_offset.

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 identity of the resource and then flows into inputs, return shape, and caveats in a logical order. It is a single very dense paragraph, though; splitting the coverage limitations and paging rules into separate sentences would help scanning without losing content.

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

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

Covers everything an agent needs for a five-parameter, no-output-schema read tool: accepted identifier forms, default and paged return size, what each returned field contains, and the coverage caveats (long-only, no shorts/cash/foreign, confidential treatment, unmerged amendments).

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 already 100%, but the description still adds real meaning: 'ticker' accepts either a CIK or a listed manager's ticker (BRK-B), 'report_period' defaults to latest, 'query' matches issuer name fragment or CUSIP, and 'next_offset' feeds back into '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?

Opens with a specific verb+resource ("What an institutional manager holds: its quarterly Form 13F holdings report, read from the filing") and explicitly carves itself away from siblings, naming sec_beneficial_ownership for the inverse question and sec_lookup_cik for resolving the manager.

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 routing rules: use sec_beneficial_ownership for holders above 5%, use sec_lookup_cik's 'name' to find a CIK, and use the 'query' parameter to answer "does Berkshire hold Apple". It also states what the tool is not for (who holds a stock, shorts, cash, foreign shares).

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds real behavioral value by disclosing the default page size of 50 and the 'matched' / 'next_offset' paging contract. It stops short of stating a total cap (the schema mentions max 200) or full return shape.

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 front-loaded sentences with no filler; the pagination mechanics come last where an agent needs them. Minor redundancy with the schema on the default of 50, but it is tied to the paging explanation.

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, and the description covers the essential return contract (list of tickers with exchange info, 'matched' count, 'next_offset'), which is enough to page correctly. A little more detail on response fields would make it fully self-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 the baseline is 3; the description earns extra by explaining the round-trip pattern of passing 'next_offset' back as 'offset' and clarifying what 'matched' means, which the schema alone does not connect.

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 qualifiers: 'List all active SEC-registered tickers with exchange info, optionally filtered by search query'. An agent can tell this is a ticker enumeration tool, though it does not explicitly contrast itself with siblings like sec_lookup_cik.

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 use cases: 'finding a company's ticker symbol or seeing what's listed on a particular exchange'. That is clear context for selection, but no explicit when-not or named alternative is 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?

The description discloses many behavioral details beyond the read-only and open-world annotations: ticker matching is exact and case-insensitive, the ticker list is cached for an hour, unknown tickers are errors, and name search returns up to 10 ranked matches. It also explains share-class behavior and how matching works for people and abbreviations.

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

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

The description is long but front-loaded and dense with operational distinctions rather than filler. Each sentence adds a matching rule, return characteristic, or routing guideline that an agent would need to invoke the tool correctly.

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

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

For a two-mode lookup tool with no output schema, the description fully covers both return shapes: a zero-padded CIK with EDGAR link for ticker lookup, and up to 10 ranked name/CIK/ticker matches for name lookup. It also covers error behavior and the CIK-as-ticker confirmation mode.

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 the schema already documents both parameters at 100% coverage, the description adds substantial semantics: 'ticker' is exact and case-insensitive, accepts a CIK as a secondary mode, and 'name' searches all EDGAR filers with prefix matching in any order. These behavioral rules go well beyond the schema text.

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

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

The description states a specific verb and resource: looking up an SEC CIK by ticker or by name. It also distinguishes this tool from sibling tools that accept tickers directly, so an agent can tell when this lookup is needed.

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 to call this only when the CIK itself is needed or when only a name is available, and notes that other tools take tickers directly. The two modes are clearly explained, including when to use 'name' for filers without tickers.

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, openWorld), and the description adds substantial context beyond them: results are newest-first, 5 by default / max 10 per call, offsets page backward, amendments (D/A) are included with funds filing yearly, and the newest filing carries the running total. It also clarifies the semantic limit — a Form D reports a raise, not price or valuation — a genuinely useful caveat.

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 that front-loads the core purpose and the CIK-lookup prerequisite, then enumerates returns and paging. The long field enumeration is justified because there is no output schema, though it borders on exhaustive.

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 fully enumerates the returned fields and their quirks (indefinite amounts, 'Decline to Disclose', plain-language exemptions), covers paging limits, and notes that it lists raises not valuations. Nothing an agent needs to invoke or interpret results 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?

With 100% schema coverage the baseline is 3, but the description reinforces and adds meaning: it explains the ticker parameter's real-world caveat (most filers have no ticker, use CIK lookup), and restates limit/offset behavior with the next_offset-to-offset handoff. It effectively compensates for the counterintuitive 'ticker'-named parameter that often holds a 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 resource (Form D notices for unregistered offerings) and precisely what it does — returns filings with a detailed enumeration of fields. It distinguishes itself from siblings by naming sec_lookup_cik as the required precondition for finding CIKs. An agent knows exactly what this tool delivers versus the other SEC tools.

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

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

Explicitly says to resolve the CIK via sec_lookup_cik's 'name' first, since most filers lack a ticker, and explains paging via next_offset. It gives clear context and a prerequisite but doesn't explicitly contrast against sibling filing tools like sec_recent_filings, leaving that inference to the agent.

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

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

Annotations only declare readOnly/openWorld; the description adds real behavioral context: the no-ticker feed reaches back roughly two business days, results are newest-first, amendments match form_type filters, and older history is paged in automatically when a form_type is set. It also describes row shape (acceptance time, parties with CIK and role, 8-K items, index URL) and the next_offset paging contract.

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 mode split, and the mode-specific details follow in order. It is a dense, fairly long paragraph with a heavy row-structure clause, but with no output schema that detail is load-bearing 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?

No output schema exists, and the description compensates by describing the returned row fields and the paging field. Combined with the mode split, feed time horizon, and escape hatch to sec_full_text_search, an agent has everything needed to call this correctly on the first try.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning by tying form_type to the auto-paging behavior and amendment matching, and clarifying that offset applies only to the no-ticker feed. It does not restate limit bounds or the CIK-vs-ticker fallback, which the schema already covers.

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 and resource ("Get recent SEC filings") with the form types enumerated and two clearly separated modes: ticker-scoped company filings vs. the all-EDGAR latest feed. It also distinguishes itself from siblings by naming sec_filing_text (for the index URL) and sec_full_text_search (for older history).

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 when each mode applies (ticker vs. omit ticker), when the form_type filter triggers automatic back-paging, and names the exact alternative for the out-of-scope case: "For filings by form further back than the feed reaches, use sec_full_text_search with 'forms' and a date range and no query." That is a complete routing instruction.

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

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

Annotations already declare readOnly and openWorld, so the bar is lower, but the description adds genuinely non-obvious behavior: results are ranked by value descending, default 20, a 'total' count of reporting filers, and that next_offset must be passed back as offset to page. The instant/duration taxonomy rule is domain knowledge an agent could not infer. Minor gap: only the 'total' field of the response shape is described.

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 example are front-loaded, then return behavior, then the paging mechanics, then the instant caveat — a sensible order. A few clauses repeat schema facts (default 20, offset semantics), which is mild waste in an otherwise dense, low-fluff 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 correctly takes on the responsibility of explaining 'total' and 'next_offset', and it pre-empts the most likely failure mode (using a balance-sheet concept with instant=false). It stops short of describing the remaining per-entry fields (entity identity, value, unit), leaving a small hole for a 7-parameter ranking 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 a 3 is the baseline, but the description earns above that by explaining the semantic coupling between concept type and the instant parameter, with named examples (Assets, Liabilities vs Revenues, NetIncomeLoss), and by noting that annual periods only apply to duration concepts — meaning not stated in the schema's period 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?

Opens with a specific verb and scope: 'get a specific financial metric for all companies in a given period', and the 'cross-company' framing cleanly separates it from single-entity siblings like sec_financial_concept and sec_company_facts. The concrete example ('compare revenue across all filers for 2024') removes any ambiguity about what a call produces.

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 use case and, more usefully, states the selection rule for the instant flag: instant concepts require instant=true plus a quarterly period, duration concepts use the default. It does not name a sibling tool for single-company lookups, so the routing guidance is contextual rather than exhaustive.

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