SEC Company Financials

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the no-effect-on-terminal-states rule, which is exactly what makes the idempotent hint meaningful, plus the fact that updated run details come back. It omits auth/permission requirements and any rate-limit behavior.

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

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

Front-loaded with the core action and the state constraint, and every prose sentence earns its place. The 'USAGE EXAMPLES' block of raw user_input lines is mostly decorative and pads the definition slightly.

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, return values need not be spelled out, and the description still notes that updated run details are returned. For a two-parameter mutation with full annotation coverage, only auth requirements are unaddressed, which is a minor gap.

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

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

Schema description coverage is 100%, so both parameters and the 30-second graceful-abort timeout are already documented in the schema. The description only gestures at 'gracefully' via an example, adding no syntax or semantic meaning beyond the schema. Baseline 3 applies.

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

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

Specific verb (Abort) plus resource (Actor run) and a state qualifier ('currently starting or running'), which immediately distinguishes it from siblings like call-actor and get-actor-run. An agent can select it without opening the schema.

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

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

Explicit when-to-use ('stop a run that is taking too long or misconfigured') and an explicit no-op condition (terminal statuses such as SUCCEEDED, FAILED, ABORTED, TIMED-OUT). It does not name an alternative tool or describe prerequisites, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, but the description adds real behavioral context beyond them: the summary vs. nextStep semantics, and that waitSecs blocks for up to 45s (default 30) before returning the current state. This is substantive added value, though it doesn't cover error/failure modes.

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 segmented into Returns/USAGE/EXAMPLES blocks. Every line carries information, though the two usage examples are somewhat redundant with the USAGE prose, adding minor length.

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 and 100% parameter coverage, the description need only orient the agent, which it does fully: purpose, when to use, wait semantics, and concrete invocation examples. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by framing waitSecs as a blocking/wait mechanism with its cap and default, and by describing what runId's run produces. Slight above-baseline value over 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?

States a specific verb and resource ('Get detailed information about a specific Actor run') and enumerates the returned result fields (status, storages, stats, summary, nextStep). It does not explicitly distinguish itself from siblings like call-actor or abort-actor-run, so it falls just short of the 5 benchmark.

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 USAGE block names the condition ('check the status of a run started by any Actor-running tool') and explains when to pass waitSecs > 0 to block until terminal. It gives clear context but stops short of explicit exclusions or naming the sibling to use for other run operations.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description adds value by disclosing the default limit of 20, what clean=true does, and that results are the raw rows. Return-shape details are largely deferred to the existing output schema, which 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 with the core purpose and the anti-scope sentence, followed by short usage notes and examples. Slightly redundant in repeating the limit default and the clean flag across sections, but nothing wasteful enough to hurt.

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 tool with full schema coverage and an output schema, the description supplies the purpose, trigger, and key defaults an agent needs. Pagination interaction (offset/limit) and flatten behavior are left to the schema, which is reasonable given the output schema exists.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters in depth. The description only restates the default limit and clean=true semantics, adding little beyond the structured fields; baseline 3 applies.

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

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

States a specific verb and resource ('Get items (rows) from a dataset') and immediately delimits scope by saying it returns rows themselves, not metadata, counts, or schema. An agent can distinguish the intent without opening the schema.

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

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

Gives a clear trigger ('When the user provides a datasetId and asks to retrieve results, output, data, or rows, call this tool directly') plus a usage section and two concrete examples. It lacks explicit when-not guidance relative to any alternative, but the sibling list contains no competing dataset-read tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered elsewhere. The description earns credit for adding behavioral context beyond that: the 'requires the exact key name' precondition and the note that the response preserves the original Content-Encoding, which most clients decompress automatically — a real return-value trait callers would otherwise trip over.

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 key facts — scope, exact-key requirement, encoding caveat — are front-loaded in three tight sentences. The subsequent USAGE and USAGE EXAMPLES blocks are somewhat redundant with the first paragraph, costing a little efficiency.

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 two-parameter read tool whose annotations, 100% schema coverage, and output schema already cover safety, inputs, and return shape. The description closes the remaining gap with the Content-Encoding behavior, which is exactly the non-obvious detail an agent needs.

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%, including the keyValueStoreId resolution rules (name vs. username~name) and minLength constraints in the schema itself. The description only reinforces that the key must be exact, adding little semantics beyond what the schema already documents, 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 and resource ('Get the value stored under a specific key in a key-value store') and preemptively scopes it against a listing tool: 'a single record, not a listing of all keys.' An agent can immediately tell this is a point lookup, not an enumeration.

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 says when to use it ('when you need to retrieve a specific record (JSON, text, or binary)') and includes two concrete usage examples showing the store identifier formats. However, it never states when NOT to use it or names an alternative/sibling for enumeration, so the guidance is implied rather than comparative.

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=false, destructiveHint=true and openWorldHint=true, so the safety profile is largely covered structurally. The description adds genuine value with cost transparency ('$0.005/company, $0.0005/run'), but it does not disclose the run lifecycle (that it starts a billable Actor run and may return non-terminal results within waitSecs) and 'retrieves its output results' sits in mild tension with destructiveHint=true.

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

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

Two sentences: a short wrapper statement followed by a dense, information-rich actor summary. It is front-loaded and mostly free of filler, though the 'This tool calls the Actor ... and retrieves its output results' preamble is near-tautological and the 'Actor description:' label is boilerplate overhead.

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, return values need no explanation, and annotations plus the 100%-covered schema carry safety and parameter detail. The description supplies data scope, input flexibility and pricing, making it broadly complete; the only real gap is operational context about the run/poll lifecycle in an agentic workflow.

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 all seven parameters (waitSecs, companies, maxFilings, filingForms, annualPeriods, includeFilings, quarterlyPeriods) are already fully documented in the schema. The description only echoes the accepted identifier types ('Tickers, CIKs or names'), matching the baseline 3 for a schema that does the heavy lifting.

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

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

The actor description names a specific verb+resource well beyond a tautology: it returns SEC EDGAR financials (revenue, net income, EPS, cash flow, margins, TTM) and accepts tickers, CIKs or names. However, the framing sentence ('calls the Actor ... and retrieves its output results') is generic wrapper boilerplate, and it never explicitly differentiates itself from the platform-level siblings (get-dataset-items, get-actor-run), so it lands at 4 rather than 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?

Usage is implied by the subject matter (fetch SEC company financials when you need reported fundamentals), and it notes 'No API key' and per-company run pricing. But there is no explicit when-to-use vs when-not guidance, no mention of the siblings, and no note about the async/run-then-poll flow that would tell an agent when this is the right entry point versus get-actor-run or get-dataset-items.

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