AkkruData

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 one genuinely new behavioral fact — the call is free — but says nothing about what the response contains or whether there are quota/rate considerations.

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 short lines, front-loaded with the resource then the action definition. 'Your account.' is mildly redundant with the title but sets scope, and nothing else is wasted.

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, single-action, read-only tool with no output schema, what is present is close to sufficient. It still leaves unclear whether the balance response includes anything besides the credit count, which is the one thing an agent can't infer.

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%, but the schema explicitly defers action semantics to the description ('each action is described in the tool description'), and the description does define what 'balance' returns. The detail parameter is fully documented in the schema and needs no repetition.

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?

Names the resource (your account) and the single action (balance) with a concrete definition: 'the credits left on your account'. It is clearly distinct from all siblings (companies, filings, statements, etc.), which are data-retrieval tools rather than account/billing. Lacks an explicit verb for the tool overall, so not 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?

There is no statement of when to call this versus alternatives, nor prerequisites. The lone signal is 'Free', which implies there is no cost concern, but an agent gets no routing guidance beyond the obvious.

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 readOnly/idempotent annotations, it discloses the non-obvious economics and limits: 10 credits for search, 8 for lookup 'also when no company matches', 30 credits per page for list, results truncated at the plan's coverage, and industry classification only on Pro and above. Billing-on-empty-result and plan gating are exactly the behaviors an agent could not infer from annotations or schema.

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

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

One framing sentence followed by three labeled bullets, each front-loading the action name and appending cost — the highest-value facts in the smallest space for a 13-parameter, three-action tool. No sentence is redundant with the title or with the structured fields.

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

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

With no output schema and 13 parameters, the description carries return-value burden well: lookup is described as returning identity, all historical tickers, filing-list links, and forms/fiscal years/quarters on file, and list returns 100 per page. It never states what a search candidate records contain beyond industry classification, a small gap for the search action.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter constraints the schema cannot express: lookup requires 'exactly one of' the six identifier fields, search matches name-contains versus ticker/registrant-id prefix, and the 8-candidate best-match-first ordering. It does not add format details for identifiers, but the schema already covers those.

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?

Names the resource (companies) and enumerates three distinct verbs — search, lookup, list — with a precise scope for each: 'companies whose name contains query, or whose ticker or registrant id starts with it' versus 'one company by exactly one of ticker, cik, ...'. This is specific enough that an agent can pick the right action without opening the schema, and the identity/lookup semantics distinguish it from sibling tools like akkru_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 bullets give clear per-action selection context (find a company, resolve one entity, enumerate coverage) plus a concrete narrowing rule via jurisdiction. It does not explicitly route the agent to sibling tools (e.g. akkru_filings for the filing lists this returns links to), so there is no stated when-not or alternatives clause, keeping it below 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?

Goes well beyond the readOnly/idempotent annotations by disclosing per-action credit costs (10 per list page, 30 for get, 65-280 per search page), plan gating (Starter vs Pro), the history-window truncation, and the important billing caveat that list, get and search are charged even on empty or not-found results. It also explains that amendments are merged into the filing they amend, which affects what results mean.

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 lead sentence is front-loaded with the resource and the section model, and the four bullets map cleanly to the action enum with costs attached. It is dense and the action labels are abbreviated ('- types:', '- list:'), but almost every clause carries decision-relevant information.

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

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

For a 17-parameter tool with no output schema, the description covers the four modes, their required inputs, and partial return shapes (ids/dates/Items for list; sections, amendment history, optional raw text and exhibits for get). It does not describe the search response layout or the detail-level output differences, leaving a modest gap for a tool this complex.

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 already 100%, so the baseline is 3; the description adds value by tying parameters to actions and by clarifying per-action economics and result semantics (e.g. amendment merging, which shapes how exclude_likely_merged and include_unresolved_amendments behave). It still does not explain item_match, as_of_date, or detail beyond the schema text, keeping it at 4 rather than 5.

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

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

The opening sentence names the specific resource (US corporate Form 8-K events) and the per-Item section structure, and the bulleted actions (types/list/get/search) give each verb a concrete object. It does not explicitly differentiate itself from siblings such as akkru_filings, so an agent must infer the boundary from the resource name 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?

Each action carries its own guidance: types is free and enumerates Item codes, list takes a ticker or cik, search requires Pro plan and takes items plus date ranges, get takes a filing_id from list/search. Plan tier and history-window constraints are stated, but there is no explicit when-not-to-use or named alternative among sibling 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 establish read-only, idempotent, non-destructive behavior, and the description adds genuinely useful non-annotation context: credit pricing (10/20/30/50 per name by resolution level, 10 per 5 ids), the fact that failed filings appear in failed_filings and are not charged, and that a name match can return several facts, best first. However, the return payload is only sketched and pagination/limits are not discussed.

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

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

Front-loaded with the resource definition, then organized into one bullet per action, which matches the action enum. Dense but earns most of its words given 14 parameters; a missing word in 'A name is matched to the filing's concepts' slightly hurts readability.

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

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

For a 14-parameter tool with no output schema, the description covers cost model, matching behavior, comparison mode, and failure handling well enough to call it correctly. The main residual gap is the shape of returned fact records, which is only described in general terms in the first sentence.

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 every parameter including pricing notes, form_type defaults, and quarter behavior. The description adds the concept of L0-L3 name resolution and the _resolution_level output marker, but most other parameter guidance restates what the schema already says. Baseline 3 is appropriate.

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

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

The opening sentence states the resource precisely (single reported numbers and text facts from filings, each with period, unit, dimensions and a filing link), and the two bullets define the distinct verbs: 'get' retrieves facts by name or id, 'breakdown' splits a consolidated total into segments/products/regions. It does not explicitly contrast itself with siblings like akkru_statements or akkru_metrics, so an agent must infer 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?

Clear routing between the two actions (use breakdown to split a total, get to retrieve values) and between addressing modes (one filing via filing_id or ticker+fiscal_year vs. multiple filings for year/company comparison). No explicit when-not guidance or sibling comparison is given, but the intra-tool alternatives are well covered.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds substantive context beyond them: per-action credit costs (10 vs 300), a one-hour expiry on the Excel download URL, the presence of a has_excel flag, amendment-merge notes, and the caveat that older years and some markets depend on the plan. These are exactly the operational facts an agent cannot infer from the schema.

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

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

One framing sentence followed by two action bullets with costs inline — dense and front-loaded, with no filler. The plan caveat is tucked at the end where it belongs, though the action bullets are terse enough that the fiscal-year scoping assumption has to be inferred.

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

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

With no output schema, the description carries the return-value burden and does so for both actions: it enumerates list fields (id, form, quarter, registrant, fact count, has_excel, amendment note) and describes the Excel response as a time-limited URL. Minor gap: it says list covers 'one fiscal year' while fiscal_year is not a required parameter and no default or error behavior is stated for omitting it.

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

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

Schema description coverage is 100%, so the schema already explains every parameter, including the alternative of naming a filing by filing_id versus ticker plus fiscal_year. The description adds little parameter-level meaning beyond noting that results are confined to a single fiscal year, so the baseline of 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 resource (regulatory filings: 10-K, 10-Q, 20-F, 40-F plus non-US equivalents) and splits it into two clearly named actions, 'list' and 'excel'. An agent can tell this apart from akkru_statements or akkru_facts by resource, though no sibling is named explicitly.

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

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

Gives per-action guidance: 'list' for one company's filings for a fiscal year, 'excel' when a downloadable spreadsheet is needed, and the error-listing behavior when a fiscal year has multiple filings of a form. It does not say when to prefer this over sibling tools like akkru_statements, so the routing between tools is left implicit.

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 annotations (which already assert readOnly/idempotent/non-destructive), the description discloses per-action credit pricing, that 'A company outside your plan's coverage returns 403 and the call is still charged', that rows failing a consistency check are silently excluded unless include_anomalies is true, what no_securities_owned=true means, and that shares_owned_total and underlying_shares_total are in different units. These are non-obvious behaviors an agent would otherwise get wrong.

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 lead sentence establishes scope and the anomaly caveat up front, followed by a tight per-action bullet list where each line carries distinct information (scope plus cost). Density is high and the opening sentence is packed, 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 a 26-parameter, six-action tool with no output schema, the description covers action selection, credit cost, plan restrictions, failure semantics, and the anomaly default. Return-value detail is delegated to the parameter schema's detail enum and next_page note, which is acceptable, though a brief note on what a stats response contains beyond ids would help.

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%, so the baseline would be 3. The description still adds meaning the schema does not: the unit-mismatch caveat between the two share totals, the fact that stats returns ids for every holding counted (enabling the 'get' action), and the 100-id cap framing for get. It stops short of clarifying interaction rules among the many search filters.

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 opening sentence names the specific resource and data domain ('What insiders report holding when they become insiders (SEC Form 3)') and explains the nesting order ('nested filing then holdings'), then enumerates all six actions with what each returns. An agent can tell this apart from sibling akkru_insider_transactions because the scope is explicitly limited to Form 3 initial holdings.

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?

Each action carries an inline signal of when to use it: 'list' for one company/insider filings, 'stats' for windowed totals with ids, 'get' for holdings by id 'from stats', 'insiders' for one row per CIK, 'search' for cross-company screening. It also states plan gating (Pro plan or higher) and the natural list->stats->get chaining. It does not explicitly contrast with sibling tools such as akkru_insider_transactions or akkru_institutional_holdings, which is the only real gap.

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

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

Goes well past the readOnly/idempotent annotations by disclosing per-action credit costs, the fact that out-of-plan companies return 403 and are still charged, and the default exclusion of rows failing a consistency check with the omitted count reported. These are decision-relevant behaviors (cost, failure, data filtering) that no structured field carries.

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 one-sentence model of the resource, then a bullet per action with cost, then the plan/403 caveat last. Dense but every line carries information an agent needs to choose an action, 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?

For a 28-parameter, 7-action tool with no output schema, the description covers what each action returns, how ids flow between actions, cost, and pagination behavior. Remaining gaps are error handling beyond the 403 case and any differentiation from sibling data tools, which is a minor shortfall rather than a blocking one.

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

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

Schema description coverage is 100% and the schema itself annotates each parameter with its applicable actions, so the description correctly stays out of per-parameter restatement. It adds a little beyond the schema — the A/D direction meaning and the id handoff between stats and get — but most parameter meaning is already schema-side, so the baseline of 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?

Names a specific resource (insider trades reported on SEC Form 4/5) plus the exact data shape returned (filing-nested transactions with insiders, footnotes and filing links), then enumerates all seven actions so the agent knows the tool is a multi-action surface rather than a single lookup. It also disambiguates the direction field (acquired_disposed_code A/D), which an agent could otherwise misread.

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 between actions: stats outputs ids that get consumes, insiders outputs the insider_cik that list/stats take, types is the lookup for transaction_code, search is plan-gated. That is real when-to-use guidance. It does not, however, say when to prefer this tool over siblings like akkru_filings or akkru_institutional_holdings, so the sibling boundary is left to inference.

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

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

Annotations already cover read-only/idempotent, and the description adds what they cannot: per-action credit costs (10/30/40/160-720), Pro-plan requirement for search, per-page charging, and that a 404 for an unknown manager/quarter/security is still billed. It also notes that links open the EDGAR index page and that portfolio carries the amendment record.

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 one-sentence scope followed by five tight action bullets, one line per action. Phrasing is telegraphic ('10 credits.', 'exited') but nothing is wasted.

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 all five actions, their costs, plan gating, error behavior, and paging ('30 credits per page', 'next_page' in schema), which is enough to call a 22-parameter tool correctly. Output shape is only sketched ('row by row', 'header with the quarter's numbers') and no output schema exists, but the gap is minor against the schema's per-param documentation.

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

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

Schema description coverage is 100% and each parameter is already tagged with its applicable actions, so the description's action-by-action summary largely restates structured data. It adds little parameter-level detail beyond page-size implications in the credit lines.

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 institutional managers report holding each quarter on SEC Form 13F, keyed by manager CIK and quarter. The five actions are each named and scoped, so an agent can tell managers/history/portfolio/holders/search apart 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?

Each action has an explicit selection rule (managers to discover CIKs, history for quarters, portfolio for one quarter, holders for reverse lookup, search for screening) plus a plan gate on search. It never names a sibling tool or states when NOT to use this instead of akkru_initial_holdings, so routing is intra-tool only.

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, yet the description adds substantial behavior beyond them: exact credit costs per action ('158 credits', '55 credits plus 148 per period'), plan gating (Starter vs Pro), pricing semantics for price-based ratios, page limits ('up to 5 periods per page'), and the failure mode on unknown metric names. This is far more than the annotations convey.

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

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

Front-loaded with the one-line purpose, then a scannable per-action bullet list with cost appended to each. A few lines duplicate schema content, such as the six category names that also appear in the category enum, but there is little true filler for a five-action, 34-parameter 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 high-complexity multi-action tool with nested filter trees and no output schema, the description covers action selection, cost, plan requirements, naming conventions, and error behavior. The remaining gap is response shape — with no output schema, nothing tells the agent what a metrics payload or a search row looks like beyond incidental mentions of next_page and a 'current-price block'.

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 cross-parameter meaning the schema does not, notably that a filing is named by metric_group_id, filing_id, or ticker+fiscal_year, and that filing_date_price_only suppresses the current-price block. It does not attempt to cover the 34 parameters individually, which is acceptable given the schema carries them.

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

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

Opens with a concrete statement of the resource — '82 metrics computed from each filing' with the metric families enumerated — and then defines five named actions each with a specific object. Scope is narrowed ('US companies only'). It never explicitly contrasts itself with siblings like akkru_statements or akkru_filings, so the computed-vs-raw distinction must be inferred.

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?

Each action gets an explicit routing rule: 'get' for a single filing, 'history' for many periods for one ticker, 'list' to discover metric_group_id, 'catalog' for metric names/operators, 'search' to screen across companies. It also names the fallback path ('a wrong name returns the full list of names') and states which actions require Pro, so the agent knows which action is viable before calling.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses credit pricing per action (28, 48, 10), the surcharge for fuzzy role_label matching, that statement_type is US-only while role_label works in any filing, and the error behavior when a fiscal year has multiple filings ("the error then lists the quarters on file"). That is exactly the operational context annotations cannot carry.

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

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

Front-loaded with the return-shape summary, then bulleted per-action guidance, then the filing-identification rule. Efficient overall, though the closing "Name the filing with filing_id, or with ticker and fiscal_year" restates what the schema already says.

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 11-parameter tool with no output schema, the description supplies what the response contains for both actions (rows with value/period/unit/source; blocks with block_index/statement_type/role_label) and how to resolve a filing. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by tying costs to parameter choices and reinforcing that the filing is named by filing_id or ticker+fiscal_year, not both. Much of the per-parameter wording overlaps the schema descriptions, so it is additive rather than transformative.

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

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

States a specific resource and scope: "Whole statements and notes of one filing, as filed: every row with its value, period, unit and source," then splits it into two named actions (get/list) with distinct return shapes. An agent can tell this apart from akkru_facts or akkru_filings 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?

Explains the get vs list split and, for get, which of the three selectors to use and what each one accepts (statement_type for the five US main statements, role_label for any filer-named block, block_index for a position that list returns), which implies the list-then-get workflow. It does not name a sibling tool as an alternative, so the boundary with akkru_facts is left to inference.

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