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 read-only annotations, the description discloses credit costs per action, that lookup is charged even when no company matches, that search returns up to 8 candidates, that list is paginated at 100 per page, and that results are constrained by plan coverage. These are important operational details an agent needs before invoking the tool.

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

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

The description is front-loaded with its core purpose, then uses compact bullet points for each action with cost and scope details. It is appropriately sized for a 12-parameter tool with three operational modes.

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 complex tool with no output schema, the description provides enough detail about what each action returns: identity, ticker history, filing links, covered forms/fiscal years/quarters, and paginated company listings. Combined with annotations covering safety and the fully described schema, an agent has sufficient context to invoke it 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 each parameter thoroughly. The description adds useful action-level grouping, such as which identifiers are used by lookup and that jurisdiction filters list by market, improving understanding beyond the raw 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?

The description opens with a specific purpose, "Find a company and see what is covered for it," and then breaks the tool into three clearly named operations: search, lookup, and list. This distinguishes it from sibling tools focused on filings, facts, statements, and 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 is given a clear use case: search for partial name/ticker matches, lookup for exact identification by one identifier, and list for enumerating covered companies. It does not explicitly compare against sibling tools such as akkru_filings or akkru_facts, but the internal action guidance is strong.

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 and idempotent annotations, the description discloses crucial operational traits: plan gating ('Starter plan or higher', 'Pro plan or higher' for search), credit costs per action, the fact that list/get/search are charged even when nothing matches, and the history window limit. These are exactly the kind of behavioral details an agent needs before invoking a paid read tool.

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

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

The description is organized as a short intro followed by a bullet per action, which is front-loaded and easy to scan. It is slightly dense but every sentence carries meaningful information about cost, plan, or behavior; there is no 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?

For a multi-action paid data-retrieval tool with no output schema, the description covers everything an agent needs: what each action returns ('ids, dates and Items', 'sections, amendment history, original text and attachments'), pagination behavior, credit costs, plan prerequisites, and not-found billing rules. Nothing critical is omitted.

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 description coverage, the schema already documents all 17 parameters well. The description adds value by explaining the required 'action' enum in detail—each action's behavior, cost, and plan requirement—which the schema defers to ('each action is described in the tool description'). It does not add syntax details for other parameters, but it doesn't need to.

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 opens with a specific resource ('Corporate events US companies report to the SEC') and then enumerates the four actions available (types, list, get, search) with their exact scope, so the agent can immediately distinguish this from sibling tools. The Form 8-K framing and Section-per-Item explanation make the purpose unmistakable.

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 is given a clear role: 'list' is one company's filings, 'search' is across companies by Items and dates, 'get' is one filing by id, and 'types' enumerates Item codes. The description does not explicitly say 'use search instead of list when…' but the action distinctions and plan/price notes make the correct choice sufficiently clear.

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, idempotent annotations, the description adds important behavior: credit costs, four name-resolution levels, best-first multiple-fact matching, and breakdown slicing rules. It does not cover every operational edge case, but it discloses the cost and matching behavior an agent needs before calling.

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 resource definition and then structured by action. It is dense but not wasteful; almost every sentence carries actionable detail about matching, comparison, or 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?

For a complex 13-parameter tool with no output schema, the description is largely complete: it explains actions, filing selection, comparison mode, resolution behavior, and cost implications. Minor details such as failed-filing handling live in the schema rather than the description, but the core calling context is covered.

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 parameter details are already well documented. The description still adds real meaning beyond the schema by explaining how names are priced and matched across L0-L3, how fact_ids are charged, and how breakdown costs count the total and direct slices.

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 clearly states the resource and action: reported financial facts from filings, with 'get' and 'breakdown' modes. It is specific about what is returned (period, unit, dimensions, filing link), but it does not explicitly distinguish this tool from siblings like akkru_statements or akkru_metrics.

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

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

It provides substantial guidance for choosing between 'get' and 'breakdown' and for naming one filing versus passing multiple filings to compare. However, it does not say when to use this tool instead of related sibling tools such as akkru_statements, akkru_metrics, or akkru_filings.

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 annotations (readOnly/idempotent/non-destructive, closed-world), the description discloses credit costs (10 for list, 300 for excel), that the download URL expires after one hour, that amended filings are noted in the list output, and that older years and some markets depend on the plan. That is meaningful operational context an agent cannot get from the annotations alone.

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 structure is strong: a one-line scope statement followed by two bulleted action definitions, each front-loading what the action returns. The parenthetical listing of form types is long but earns its place by preempting ambiguity about regional filings. Minor density keeps it from a 5.

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

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

With no output schema and seven parameters, the description does the necessary work: it enumerates the list response fields (id, form, quarter, registrant, fact count, has_excel, amendment note) and describes the excel return value plus its expiry. The plan-dependent limitation is flagged, though it could be more specific about which years or markets are restricted.

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 action-scoping value the schema cannot: which parameters apply to list versus excel, that form_type defaults to 10-K for excel, that quarter is optional for list and conditional for excel, and that mutual exclusivity rules govern filing naming. This meaningfully reduces mis-invocation risk.

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

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

The description names the resource (a company's financial reports, with the specific form types 10-K/10-Q/20-F/40-F and their regional equivalents) and splits it into two concrete actions: list filings for a fiscal year, and fetch an Excel download URL for one filing. An agent can distinguish exactly what this tool returns versus a generic financial-data sibling.

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 is given its own when-to-use context, including that quarter is only needed for excel when a fiscal year has multiple filings of that form and that the error will list the available quarters. It also explains the either/or naming (filing_id or ticker+fiscal_year). It stops short of naming sibling tools to redirect to, so it stays at 4.

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, and the description adds substantial context beyond them: per-action credit costs, a Pro-plan gate on search, and the key warning that a 403 for out-of-plan coverage is still charged. It also discloses that rows failing a consistency check carry data_quality_flags and are excluded unless include_anomalies is true, and warns that shares_owned_total and underlying_shares_total use different units.

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

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

Front-loaded summary followed by one bullet per action is the right structure for a 26-parameter, 6-action tool, and pricing is folded into each action rather than a separate block. A few clauses are dense ('nested filing then holdings'), but nothing is 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?

For a wide, multi-action tool with no output schema, the description covers action selection, cost, plan gating, anomaly handling, and a units caveat. Response shape is only loosely implied (via the detail levels and the stats/get id handoff), so an agent still learns the return format largely from the schema.

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 real meaning on top: the anomaly-flagging behavior tied to include_anomalies and the unit mismatch between the two aggregate totals. It also clarifies what no_securities_owned=true represents (filer reported holding nothing) in business terms rather than just a boolean.

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 (SEC Form 3 initial holdings reported by insiders on becoming insiders), its nesting shape, and the meaning of no_securities_owned. This clearly separates it from siblings like akkru_insider_transactions (Form 4) and akkru_institutional_holdings (13F).

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 of the six actions is scoped explicitly (list = one company/insider, stats = window totals, get = ids from stats, insiders = roster per company, tickers = covered companies, search = cross-company screening), with cost and plan requirements attached to support action choice. It stops short of naming sibling tools as alternatives (e.g., when to prefer akkru_insider_transactions), so 4 rather than 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 cover read-only/idempotent/closed-world, but the description adds unique behavior: per-action credit pricing, Pro-only gating on search, the fact that an out-of-plan company throws 403 and is still charged, and that anomaly rows are filtered unless include_anomalies is set with the excluded count reported. This is well beyond annotation coverage.

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

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

Front-loaded summary paragraph establishes response shape and anomaly behavior, then a tightly scannable per-action bullet list with costs. Every line carries actionable information; 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, seven-action tool with no output schema, the description covers return shape ('nested filing then transactions, with the insiders, footnotes and links'), insiders row granularity, stats id emission, pagination hints, cost and error/plan behavior. Nothing an agent needs to invoke 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 description coverage is 100%, so the schema already documents all 28 parameters in detail; the description only adds the acquired_disposed_code A/D direction meaning and the anomaly filtering flow. That is modest added value over an already complete schema, so baseline 3 plus a negligible bump is right.

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

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

States a specific verb+resource (SEC Form 4/5 insider trades) and then enumerates each of the seven actions with what it returns. Clearly distinguishable from siblings like akkru_institutional_holdings or akkru_initial_holdings by naming the filer type (insiders) and form type (4/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?

Provides explicit routing between actions: 'get: transactions by id (from stats)' and 'insiders ... gives the insider_cik the other actions take', plus plan prerequisites for search (Pro or higher) and per-action credit costs. An agent can pick the right action without opening schemas, and knows when a call is costly or gated.

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?

Adds a lot beyond the readOnly/idempotent annotations: per-action credit costs, plan requirements, the filing-date vs current-price ratio behavior, filing_date_price_only, the 5-periods-per-page cap, and that a wrong metric name returns the full name list. Caveat: 'US companies only' conflicts with the schema's Korean/Japanese/European/China ticker examples and with the search tool's sector/ticker coverage, which is a factual inconsistency an agent could 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?

Front-loaded one-line purpose followed by a bullet per action, so an agent can scan to the right sub-command. It is long, but for a 34-parameter, five-action tool the length is largely earned; a few schema-echoing phrases (six category names, price-based ratio wording) could be trimmed.

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

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

Given the complexity (five actions, nested where-clause, no output schema), the description covers action selection, costs, plan gates, and the main return-shape hints (current-price block, wrong-name error, next_page exists per schema). It leaves the actual response payload of get/history/search under-described, but an agent has enough to invoke 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 description coverage is 100%, so the baseline is 3. The description does add real value on metric naming (catalog ids like gross_margin) and on the three ways to name a filing, but most parameter semantics remain in 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 resource (82 computed metrics per filing, with formulas and source facts) and enumerates the five sub-actions, each with what it returns. It does not distinguish itself from siblings like akkru_facts or akkru_statements, so an agent still has to infer that this is the derived-metrics layer rather than raw facts.

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 a use case and a selector: get names the filing via three alternatives, history covers multiple periods for one ticker, list returns filings with metric_group_id, catalog lists metric ids, search screens companies. Plan gates (Starter+, Pro for formula_override and search) are stated, but no guidance on when to prefer a sibling 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 this read-only, idempotent and closed-world, so the safety profile is covered. The description adds real value with pricing (28 credits, 10 for list) and the 48-credit surcharge when role_label is matched to a differently worded name, which is a behavioral trait not in any structured field. It does not cover response size limits, pagination, or what happens for non-US filings on statement_type beyond saying it is US-only.

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

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

Front-loaded summary sentence, then dash-delimited per-action blocks, then a one-line filing-identification rule. Every sentence carries information, though the mutual-exclusivity instruction is repeated from the schema and costs a little 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, so the description must characterize returns, and it does: get yields every row with value, period, unit and source; list yields block_index, statement_type and role_label per block. It also explains that detail tiers trade fields for tokens, which the schema covers. Inputs are fully covered at 10 parameters; only extreme cases (non-US statement naming, very large statements) are left unaddressed.

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 carries the field definitions and the baseline would be 3. The description goes further by explaining the practical semantics: statement_type only resolves the five main statements and only for US filings, role_label accepts any filer-given name and costs more when fuzzy-matched, block_index mirrors what list returns, and quarter is only needed for ambiguous fiscal years. That is meaning 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 opening sentence names the exact resource and scope: whole statements and notes of one filing, as filed, with rows carrying value, period, unit and source. The two actions are then given concrete verbs (return one block vs. enumerate all blocks). It does not say how it differs from akkru_facts, which an agent might reach for when it wants numbers instead of full statements.

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 states explicitly how to select a block — exactly one of statement_type, role_label or block_index — and explains what each selector is for and where block_index comes from. It also says a filing is named either by filing_id or by ticker plus fiscal_year, not both, and when quarter is needed. No guidance on when to prefer this tool over sibling fact/metric tools.

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