SEC Financials to Excel: EDGAR XBRL Comps & Model Data

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, and the description stays consistent while adding substantial context the annotations cannot carry: SEC fair-access contact requirement, $0.002 per company-year billing, that run_max_items does not limit the Actor's billing while run_max_charge_usd does, default $0.50 cap, 5-15 s typical latency with run_timeout_secs up to 300, and that unknown tickers come back free with a status. Non-idempotency is implicitly covered by per-call billing and the explicit warning about repeated cost exposure.

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 routing, then parameter cost guidance, then runtime behavior — a sensible order. It is long and dense, and the exhaustive return-field list in the middle sentence competes with the usage guidance for attention, but since no output schema exists the field inventory earns its place.

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

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

Covers everything an agent needs for a 6-parameter, billed, long-running remote Actor call: cost model and caps, timeout guidance and remediation, required SEC contact email, per-item return fields in the absence of an output schema, and where the workbook artifact lands. Nothing material is left to inference.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds real interpretation: it explains the years/company-year cost coupling and warns that run_max_items does not set years, so cost must be capped with years plus run_max_charge_usd — a cross-parameter interaction the schema only hints at. It slightly restates schema content (contactEmail's SEC purpose), which keeps this from 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 — 'Return standardized annual financials for US-listed companies from SEC EDGAR XBRL 10-K data' — and enumerates the content (income statement, balance sheet, cash-flow lines plus EBITDA, FCF, net debt, margins, growth) at one row per company-year. It explicitly contrasts itself with pdf_table_extractor (best-effort PDF tables vs. exact structured filings) and federal_contract_finder (fundamentals vs. government spend), so an agent can separate it from siblings without opening a schema.

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

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

Gives an affirmative trigger ('Use when you need comps, model inputs or multi-year history for tickers or CIKs') and explicit exclusions ('Do not use for private companies, foreign filers without 10-Ks, quarterly data or share prices'). It also names the two alternatives it supersedes, which is the full when/when-not/alternative triad.

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