Valuein — SEC EDGAR Fundamentals & Smart-Money Data

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

Adds substantial context beyond the annotations: execution uses caller credentials, idempotent/race-safe re-entry returns current state with executed_now:false, underlying-tool failure surfaces as 'failed' while the approval call still succeeds, and cross-tenant ids return NOT_FOUND without leaking ownership. Annotations (destructive/idempotent/openWorld) are corroborated rather than repeated.

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-loads the core action and consequence, then layers idempotency, failure semantics, and auth. Sentences are long and clause-heavy but each carries distinct information; 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 destructive, execution-triggering mutation this covers what an agent needs: what executes, whose credentials, idempotency behavior, failure interpretation, and error masking. An output schema exists, so return-field detail (executed_now, tool_result) is helpfully signposted rather than over-explained.

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 already documents the single staged_action_id parameter. The description adds meaningful semantics beyond the schema — that a foreign-customer id is treated as unknown/NOT_FOUND — which the schema does not state.

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 ('Approve a staged action by id') and immediately clarifies the non-obvious side effect: it RUNS the underlying tool call. This clearly separates it from stage_action (proposal) and reject_staged_action (denial).

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 execution context (caller's own credentials, never the proposer's) and the conditions under which it does not re-execute (already approved/rejected/executed/failed), plus the tier requirement. It stops short of explicitly naming reject_staged_action as the alternative path for denial, but the surrounding routing is 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?

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: the pending-only constraint, the no-op idempotency behavior, undoability rules (future wake time + tier cap room), and the tier gate. No contradiction with annotations.

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-loads the action and id source, then layers constraint, idempotency, undo, and tier in compact clauses. Every sentence carries 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?

An output schema exists so return values need no explanation, and the description covers all behavioral edges an agent needs: eligibility, idempotency, recovery, and the tier requirement. Nothing material 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% and the single `task_id` param is already well documented. The description adds provenance (where the id comes from) which is genuine value, though the syntax itself is left to 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 (cancel) and resource (scheduled task) with the identifier source named explicitly (`schedule_task` or `list_scheduled_tasks`). Clearly distinguishable from siblings like `schedule_task`, `list_scheduled_tasks`, and `restore_deleted`.

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 constrains usage to `pending` tasks and rules out completed ones. Names the concrete alternative/undo path (`restore_deleted` with kind `scheduled_task`) and the conditions under which it works, so an agent can route correctly without 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 the safety profile (readOnly, idempotent, non-destructive), yet the description adds genuinely new behavior: inverted periods are auto-swapped with a `swapped: true` flag so delta signs stay correct, significance bands are defined numerically, and as_of_date is described as look-ahead-bias elimination. These are non-obvious server-side behaviors an agent could not infer from the schema or annotations.

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 response interpretation, then parameter rules last; structure is logical and nearly every sentence carries information. Minor waste in the parenthetical restatement of the 5% threshold and the trailing 'Available on all plans', which adds little for an agent.

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 4-parameter, read-only comparison tool with annotations and an output schema, the description supplies everything needed: purpose, period format, ordering edge case, point-in-time semantics, and how to read the material_changes scalar. Nothing an agent needs to call it correctly 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?

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by defining the ordering contract (period_a must be earlier, period_b later) and the consequence of violating it — auto-swap plus `swapped: true`. The format strings largely restate the schema, but the swap/sign semantics are new information.

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 a specific verb and resource: compare a company's core financial metrics across two fiscal periods side-by-side, with deltas and a significance classification. An agent can distinguish it from single-period siblings like get_company_fundamentals or get_financial_ratios by the two-period framing. It stops short of explicitly naming those siblings as alternatives.

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 concrete usage context ('use it as a quick scalar to triage filings — anything > ~3 typically signals a material event') and parameter-format guidance for both annual and quarterly periods. It does not say when to prefer this over a fundamentals or ratios tool, nor does it state exclusions, 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 cover read-only/idempotent/non-destructive, and the description layers on substantive behavior: which market data is fetched, how the acquirer's price converts stock consideration into new shares versus the target price being premium-disclosure only, how cash funding source drives an after-tax interest drag, and the tier gate (sp500+). The explicit modeling limitations and pointer to result.caveats[] are exactly the disclosure an agent needs.

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 headline definition come first, then data sourcing, then knob semantics, then limitations and the output sign convention. Roughly 150 words for an 11-parameter financial model with no filler sentences; parenthetical nesting is dense but each clause carries distinct 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 an output schema present and 100% param coverage, the description only needs to supply the modeling scope, caveats, and result interpretation — all of which it does, plus the tier constraint. Nothing an agent needs to call this 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 individual params are already documented. The description nonetheless adds cross-parameter meaning: the cash/stock split, that cash is funded by new debt or the balance sheet, pretax run-rate synergies, and the interest rate tied to the debt path — semantics that are not visible from any single property description.

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 specific analytic output (first pro-forma-year EPS accretion/dilution), states exactly what inputs it pulls (net income, shares outstanding, EOD closes for both companies), and precisely describes the sign convention of the primary output. It is unmistakable against siblings like compute_dcf, compute_lbo, or project_three_statement.

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?

Frames the tool as the 'standard sell-side/banker quick-screen' and defines hard exclusions (single-year bridge, no synergy ramp, no integration costs, no PPA amortization, see caveats[]), which tells an agent when NOT to use it. It stops short of naming the alternative tool an agent should pick for a full multi-year merger model.

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/non-destructive, but the description adds substantial behavior beyond them: currency is never converted (USD for US filers, filer currency otherwise), a null `value_per_share_cents` is explicitly NOT a zero valuation and signals a degenerate model (WACC ≤ terminal growth, FCF base ≤ 0), and degenerate/overridden/three_statement runs ship without a provenance id. It also discloses the data-pull lineage (R2 FCF base, net debt, shares fallback chain) and the sp500+ tier.

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 correctly — what it does and returns come first, then input definitions, then provenance rules, then usage routing. Every section carries information, but the citation/derived_id paragraph is dense and partly reads as reporting instructions rather than tool semantics, and the repetition about assumptions having no filing backing could be tightened.

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 10-parameter tool with a nested object and an output schema, the description is thorough: it explains currency handling, null/degenerate semantics, provenance id availability rules, the `as_of_date` strict-PIT behavior, and the tier gate. An agent could call and correctly report results without consulting anything else.

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 genuine meaning the schema cannot: `fcf_source` 'trend' compounds a single base by `stage1_growth_rate` while 'three_statement' runs a linked projection and causes `stage1_growth_rate` to be ignored, and overrides (`fcf_base_override`, `shares_override`) suppress the output `derived_id`. It also defines the derived inputs (FCF base = OCF − capex, net_debt treating long-term marketable securities as not netted) that the schema never states.

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 + method: 'Forward discounted-cash-flow valuation (two-stage Gordon-growth model)' and states exactly what it returns (per-share intrinsic value in cents plus a 5×5 sensitivity grid). It explicitly contrasts itself with `get_valuation_metrics` (pre-computed, no assumptions) and `create_report` (persistence), so an agent can distinguish it from siblings without opening schemas.

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 when-to-use rule ('when you want to drive the assumptions yourself') and names the alternative with the condition that selects it (`get_valuation_metrics` for the pipeline's pre-computed DCF/DDM). It also states what the tool does NOT do ('Does NOT persist a report — use `create_report`') and discloses the sp500+ tier prerequisite, 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 only declare read-only/idempotent safety; the description goes far beyond them by disclosing the Day-1 pro-forma build (cash-free/debt-free convention), the 100% FCF sweep default, the EBITDA-proxy caveat, that non-converged IRR is returned rather than fabricated, and that simplifications surface in `result.caveats[]`. These are exactly the behaviors that change how an agent interprets output.

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 purpose, then mechanics in a single dense paragraph. Every clause carries information (formulas, proxy behavior, convergence semantics), though the parenthetical algebra and the trailing 'Tier' note make it heavier than ideal for a first read.

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 13-parameter model with an output schema, the description covers what the schema cannot: computational methodology, default sweep behavior, universe restriction, and named result fields (`result.entry_ebitda_is_proxy`, `result.irr.converged`, `result.caveats[]`). Nothing material is missing for correct invocation or interpretation.

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 3 baseline applies, but the description adds genuine meaning: the entry_debt = leverage x EBITDA and sponsor_equity = EV + minimum_cash - entry_debt derivations, the exit-multiple default to entry, and how `entry_ebitda_override` changes the EBITDA basis for both multiples.

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: 'Leveraged buyout returns analysis' producing MOIC and IRR. It implicitly separates itself from `compute_dcf` (no LBO/sources-&-uses math) and `generate_lbo_xlsx` (this computes rather than exports), and it names the shared engine with `project_three_statement`.

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 through the required inputs (entry/exit multiples, leverage, hold period) and the 'Tier: sp500+' constraint, but there is no explicit statement of when to pick this over `compute_dcf`, `compute_accretion_dilution`, or `generate_lbo_xlsx`. The `project_three_statement` reference describes mechanics, not tool selection.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false) it discloses that the call is synchronous/blocking, that output includes markdown plus structured JSON plus a per-claim citation chain to SEC accessions, and that reports are per-author state rather than sample-tier shared data. The retired-thesis refusal behavior is also real context an agent needs. Loses a point only because the tier sentence is terse to the point of obscurity.

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 verb sentence, then a scannable subtype bullet, then retirement notice. Every block earns its place except the final 'Tier: sample tier rejected — reports are per-author state' line, which is compressed into near-unreadability and reads like an internal note.

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 five-param nested creation tool with an output schema, the description covers the one live subtype, required inputs, blocking behavior, persistence/ownership, and the deprecated path. An agent has everything needed to call it correctly and to avoid the thesis trap.

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 genuinely adds meaning: it ties `params` to a 5×5 WACC × terminal-growth sensitivity grid, which explains what those two numeric inputs drive rather than merely restating their defaults. It also confirms ticker + params are required for the only live subtype, which the schema expresses only through a prose field description.

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 first sentence gives a specific verb and resource plus the persistence semantics ('generate a research report and persist it under the caller's authorship'), and the subtype block states exactly what the one supported report type computes. This clearly separates it from compute_dcf (calculation only) and save_freeform_report / update_report (other creation paths), even though those siblings are not named.

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 usefully warns that `report_type: "thesis"` is refused in 3.14.0 while stored thesis reports still read, which prevents a failed call. But it never states when to call this versus compute_dcf, save_freeform_report, or compute_accretion_dilution — the closest non-persisting alternatives — leaving that routing 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?

The description is unusually rich about wiring status, retired `score_thesis`, tier limits, and the limited `condition_expr` grammar. However, it states that `replaces_rule_id` is implemented as 'create-then-delete,' which is a destructive side effect, while annotations declare `destructiveHint: false`. Under the rules, that contradiction requires a score of 1.

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 the most important operational caveats. It is dense but mostly earns its length; minor improvement would come from structuring the trigger/action matrix and wiring caveats into separate lines rather than one long 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?

An output schema exists, so return-value documentation is not required. The description nevertheless covers the critical behavioral context an agent needs, including trigger wiring status, accepted/refused types, condition expression limits, tier restrictions, and replacement semantics.

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 schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains live vs not-yet-wired triggers, why `price_threshold` and `manual` are accepted but never fire, that `score_thesis` is refused, the exact shape and anti-loop purpose of `condition_expr`, and the cap-neutral behavior of `replaces_rule_id`.

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: 'Persist a trigger -> action rule and register it with the evaluator.' It also immediately identifies the trigger and action model, making clear this is the rule-creation tool rather than a test, list, or delete operation.

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 strong operational guidance: use `test_rule` immediately after creation, omit `condition_expr` to fire on the trigger alone, and set `replaces_rule_id` when saving an edit. It does not explicitly compare `create_rule` to sibling tools such as `create_signal` or `update_signal`, so it falls short of a full when/when-not/alternatives treatment.

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 the write/non-idempotent/non-destructive profile; the description goes far beyond, disclosing entitlement failure behavior (ENTITLEMENT_DENIED with upgrade_url), delivery semantics (morning digest at local 7am vs. one transactional email per UTC day, overflow to inbox), webhook HMAC-SHA256 signing, the 5-minute cron cadence, and that agent_run bills the owner's own AI key. That is exactly the operational context an agent needs before creating a live recurring artifact.

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 in sentence one, then a well-structured bulleted enumeration of condition shapes and a dense but purposeful delivery-channel paragraph. It is long, and the delivery paragraph could be tightened, but nearly every clause carries decision-relevant detail.

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?

Output schema exists so return values need no explanation, and the description covers the hard parts (entitlements, channel mechanics, cron, test_signal). The notable gap: it announces 'Five condition shapes' while the schema accepts six — `watchlist_restatement` (Restatement Radar) is never mentioned in the description, so an agent skimming only the prose would miss a supported mode. There is also no warning about the non-idempotent duplicate-creation risk on retry.

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 channel/condition unions are already richly documented inline, so the baseline of 3 applies. The description adds a little beyond the schema — the 7am local digest timing and 'each with its SEC link' — but on the key parameters it largely restates what the schema already says.

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?

A specific verb+resource ('Persist a signal and register it with the firing pipeline') followed by an enumerated taxonomy of condition shapes with concrete examples (interest_coverage < 1.5, 8-K/10-K). It reads nothing like the neighboring delete_signal, list_signals, update_signal, or test_signal tools, so an agent can pick it out immediately.

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 plan prerequisites (Institutional for smart-money forms and empty `forms`; Pro+ for price_move and fundamental_change) and names the right pre-flight alternative: 'Use `test_signal` to verify your channels are wired correctly before relying on the cron.' It does not, however, tell the agent when to prefer update_signal over this tool — that routing advice lives only in the `replaces_signal_id` schema field, not the description.

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, the description discloses the undo path, exact behavior for already-deleted or unknown IDs (NOT_FOUND), rejection of system agents, and a tier requirement. This is unusually complete behavioral context for a destructive 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 compact and front-loaded: purpose, undo, system-agent exclusion, idempotency behavior, and tier are each covered in one useful sentence. 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?

Given the output schema, annotations, and single-parameter schema, the description supplies everything an agent needs: scope, undo path, exclusion rules, failure semantics, and tier.

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 agent_id. The description adds that the id must refer to one of the caller's own standing agents, not a system agent, which gives useful selection semantics 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?

The description states a specific verb and resource: deleting one of the caller's own standing agents by id. It further distinguishes these from system agents, which cannot be deleted, so an agent can immediately understand the scope.

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 clearly says what can and cannot be deleted, points to restore_deleted as the undo alternative, and notes that system agents should be identified via get_agent/list_agents. It does not explicitly contrast this with other delete_* siblings, but the conditions for use are 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?

Annotations declare destructive and idempotent, but the description adds the substance: why staleness matters (entries are re-read every run), the exact idempotency semantics ('returns deleted:false, not an error'), the undo procedure and its caveat (restore_deleted fails if the key was rewritten), and the blast radius (your memory note only). That is real context beyond the structured hints.

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, trigger, and blast radius are front-loaded, and the idempotency and undo details earn their sentences. The trailing tier line ('Tier: sp500+ (sample rejected)') is operational metadata rather than tool guidance and slightly dilutes the close.

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 and full annotations already supplied, the description covers everything left: motivation, failure modes, undo path, cap interaction, and scope boundaries. An agent needs nothing more to call 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% and the schema already documents the key parameter, including the get_agent_memory discovery hint. The description restates 'by key' without adding format, length, or key-naming conventions, so it does little beyond the schema baseline.

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 ('Forget ONE durable memory entry by key') and explicitly scopes what it does not touch ('never touches a thesis, claim, report, or any financial fact'), which separates it from delete_thesis, delete_claim, and delete_report. An agent can identify it unambiguously.

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 triggers ('now wrong, superseded, or was only ever scratch'), names the cap-pressure case ('free a slot when the 200-entry cap is reached'), and routes to the counterpart tools: get_agent_memory for key discovery and restore_deleted for undo. No exclusions are 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?

Goes well beyond the destructiveHint/idempotentHint annotations: it defines the idempotent contract precisely (deleted=false, no error), states the deletion is undoable with a stated caveat about replacement saves, and explains the downstream effect that reports revert to canonical values on regeneration.

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, then the idempotency and undo semantics in tight sequence. The trailing 'Tier: paid + free (sample rejected)' is terse and somewhat opaque but occupies one clause.

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 destructive mutation with an output schema, the description covers the safety profile, reversibility, idempotency contract, and downstream consequences — nothing an agent needs to decide and call 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% and the single fact_id parameter is already documented in the schema, including its provenance from save_citation_override or list_citation_overrides. The description adds no format or lookup detail beyond that, so 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 ('Remove') and resource ('user-authored citation correction') keyed by fact_id, which cleanly distinguishes it from save_citation_override and list_citation_overrides among the many delete_* siblings.

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?

Implies the use case (undoing a user correction) and names the concrete alternative path for reversal (restore_deleted with kind 'citation_override'). It does not explicitly say when to prefer editing via save_citation_override instead of deleting, so it falls just short of full routing guidance.

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 behavior beyond the annotations: idempotency is explained as returning `deleted: false` when no mark existed, and ownership is clarified so a report the caller does not own simply returns `deleted: false`. This complements the destructive and idempotent hints without contradicting them.

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 purpose is front-loaded, followed by the undo relationship, idempotency, ownership, and tier in compact form. Every sentence carries operational 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?

For a destructive mutation with an output schema and complete parameter documentation, the description covers the important missing context: undo semantics, idempotency behavior, owner scoping, and tier restrictions.

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 required parameters are already documented. The description reinforces the composite key as (report_id, figure_key), but adds little new format or constraint detail 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: removing the caller's own review mark for one figure in a report. It explicitly frames itself as the undo for save_figure_review, so it is distinguishable from the related save/list 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?

Directly identifies the use case as undoing save_figure_review so the figure needs review again. It also states owner scoping and the tier gate, which tells the agent when this tool will not apply.

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 flag destructive and idempotent behavior, but the description adds concrete effects the agent cannot infer: status becomes `delisted`, visibility becomes `private`, the row and R2 artifact are preserved, and a 90-day audit window applies. It also confirms idempotency with a specific example. This is substantial behavioral context beyond structured fields.

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 a single front-loaded sentence with zero filler: the soft-delete behavior, state changes, artifact retention, idempotency, and sample-tier rejection are all delivered compactly. Nothing is repeated unnecessarily.

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 that an output schema exists, the description covers the important behavioral and precondition details an agent needs: ownership, state transition, non-destructive retention, idempotency, and rejection of sample tier. No critical call-time context 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?

There is only one parameter, and schema coverage is 100%, with the schema documenting report_id as coming from create_report or list_my_reports. The description does not add format or syntax details beyond that, so the baseline of 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 description states a specific verb and resource ('Soft-delete a report') and immediately distinguishes it from a hard delete. It also clarifies ownership scope, so an agent can tell it apart from sibling tools like unpublish_report or restore_deleted.

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 preconditions: the report must be owned by the caller, and sample-tier reports are rejected. However, it doesn't explicitly name alternatives such as unpublish_report or spell out when to choose delisting versus unpublishing, so it stops short of a full usage guide.

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, the description discloses that deletion hides the rule from the catalog and removes it from the evaluator's scan index so it stops firing immediately. It also explains that the operation is undoable via restore_deleted (subject to the signal cap) and that rules are immutable, which are non-obvious behavioral facts the agent needs.

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 short and front-loaded with the core action and effect. Every sentence carries useful information: scope, undo path, immutability workaround, idempotency, and tier constraint.

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 destructive mutation tool, the description covers effect, undo, immutability, idempotency, and tier access, and an output schema is present. There are no material gaps for an agent deciding whether and how to delete a rule.

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 rule_id. The description adds useful provenance by saying the id comes from create_rule or list_rules, going beyond the schema's generic 'Identifier of the rule to delete.'

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 ('Delete a rule by id') and adds scope details that distinguish it from the create/list/restore siblings. It also explains the source of the id (create_rule/list_rules), which makes the operation unambiguous.

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 names the alternatives: restore_deleted for undo and create_rule for modification, and it states the tier prerequisite ('sp500+ (sample rejected)'). It doesn't explicitly say when deletion is the wrong choice versus another behavior, but the immutability note covers the main routing decision.

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?

Despite annotations covering readOnlyHint=false, destructiveHint=true, and idempotentHint=true, the description adds substantive behavioral detail: it is a soft-delete, the status becomes `deleted`, and the signal is removed from the cron evaluator index so it stops firing. It also discloses immutability and restates idempotency, and gives a tier constraint — all beyond what annotations provide.

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 efficient and front-loaded: the action and mechanism come first, followed by immutability guidance, idempotency, and tier constraint. Every sentence earns its place, and no filler is present.

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 destructive mutation, the description covers soft-delete behavior, cron index removal, immutability, idempotency, and tier requirements. An output schema exists, so return values need not be explained. Given the annotations and schema, an agent has everything needed to invoke it safely and 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% and the single parameter is fully described in the schema, including its provenance from create_signal or list_signals. The description repeats that provenance ('by its id (from create_signal/list_signals)') but adds no format or syntax details beyond the schema. This meets the baseline 3 for high schema coverage.

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 ('Soft-delete') and resource ('signal') and immediately clarifies the mechanism: status flips to `deleted` and the signal is removed from the cron evaluator index. It also distinguishes the tool from update_signal by noting signals are immutable and must be deleted then recreated. This lets an agent differentiate it from create_signal, list_signals, and other delete_* siblings without opening schemas.

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 clear usage context: use it to remove a signal by id, and to change a signal you must delete then create_signal. It also states the access tier ('sp500+ (sample rejected)'), which is a prerequisite. It does not mention restore_deleted as an undo path, but otherwise gives explicit guidance on when and how to use it.

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 annotations (destructive, idempotent, not read-only): it discloses the undo path (restore_deleted with kind 'uploaded_document'), the TTL window during which undo works, and that missing/expired/foreign ids return deleted:false instead of erroring. Those are exactly the mutation-side details an agent needs before calling a destructive 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?

Three short sentences, front-loaded with the action, then the recovery path, then the failure semantics. Every sentence carries distinct information an agent needs; 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?

Destructive verb plus annotations mean safety is covered, an output schema covers the return shape, and the description fills the remaining gaps: undo procedure, TTL windows, and non-error failure behavior. Nothing material is left for the agent to guess.

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 adds real semantics beyond the schema by noting that a foreign or expired upload_id yields deleted:false, which tells the agent how the identifier is validated. It does not add format detail, but the schema already handles that.

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 ('Delete an uploaded document') plus a scope constraint (24h TTL), which separates it from get_uploaded_document and list_uploaded_documents by intent. It does not explicitly name those siblings, but the verb+resource combination makes selection unambiguous.

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 implies when this applies ('before its 24h TTL') and names the undo counterpart restore_deleted, but it never states when NOT to use it or contrasts it with the read-side siblings (get/list_uploaded_documents) or with other deletion tools. Usage is inferred rather than spelled out.

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 flag destructiveHint=true and idempotentHint=true, but the description adds the material detail that destruction is actually a soft delete: data stays readable, the name is released, and repeat calls are safe. It also discloses an auth/tier requirement (sp500+, sample rejected), which no annotation conveys.

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 with the core action and its status effect front-loaded, followed by readability, name reuse, idempotency, and tier gate in descending order of importance. No clause 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?

Output schema exists so return values need no explanation, and annotations plus the description cover safety, idempotency, and side effects. The one missing piece for a destructive operation is the recovery path (restore_deleted), which the agent must infer from the sibling list.

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 already documents case-insensitivity and the 1–80 char bound, so baseline is 3. The description still adds one meaningful clarification beyond the schema: the argument is a name, not an id, which changes how the agent must resolve the value.

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 plus the exact observable effect: status flips to `archived`. The parenthetical "(not id)" distinguishes the identifier convention from the id-based delete_* siblings, and the soft-delete framing separates it from hard deletes like delete_thesis or delete_report.

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 the archived list remains reachable via list_watchlists status=all/archived and that save_watchlist can reuse the name, which gives an agent concrete follow-up routing. It never states when not to use it (e.g. that restore_deleted is the undo path), so the guidance is clear but not complete.

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, non-destructive behavior, and the description adds context beyond them: no data reads are performed because the schema is embedded in the manifest, and it is available on all plans. Return format is left to the 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?

Roughly four sentences, front-loaded with the return payload and what it contains, then usage guidance and cost/availability notes. Nothing is redundant, though "Available on all plans" reads as mild product copy rather than operational guidance.

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 single-parameter, read-only discovery tool with an output schema, the description covers what is returned, why to call it, and that it incurs no data reads. Nothing an agent needs in order 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% and the single `table` parameter is fully documented with an example and the omit-for-all behavior. The description's reference to "all tables" is consistent but adds no syntax or format detail 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 and resource — returns the Parquet schema for all tables in the Valuein SEC data warehouse — and enumerates what that includes (table descriptions, column names, types, PKs, FKs). This clearly separates it from data-reading siblings like get_company_fundamentals or run_workflow.

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?

"Use this tool to understand the data model before querying with other tools" gives clear timing and ordering guidance. It doesn't name a specific alternative or state when-not-to-use, 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 destructiveHint=true and idempotentHint=true, and the description adds real context on top: it is a soft delete that sets `dismissed_at`, the row remains queryable via list_signal_inbox(include_dismissed=true), and it is reversible via restore_deleted with kind `inbox_item`. The tier gating note (sp500+, sample rejected) further explains an error mode an agent may encounter.

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?

Dense and front-loaded — the core action and the id caveat come first, followed by audit, undo, and tier details. 'Idempotent.' largely restates the idempotentHint annotation, the one sentence that does not fully earn 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?

Output schema exists and annotations carry the safety profile, so the description's job is mostly disambiguation and reversibility, which it covers well. The only gap is not distinguishing dismissal from marking read, which matters for an inbox workflow with both tools available.

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 param is already documented, but the description adds meaningful semantics the schema does not: where the id comes from and, critically, that it is an inbox_id rather than a signal id. That disambiguation is the main failure mode for this parameter.

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 ('Soft-delete a single inbox item by its id') and immediately disambiguates the identifier type from a signal id. It also names the source of the id (list_signal_inbox), so an agent can distinguish it from delete_signal and the other delete_* siblings.

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 clear selection context: use this for inbox items, not signals, and use restore_deleted to reverse it. It does not contrast with the closely related mark_inbox_read sibling (read-state vs. dismissal), which is the one remaining ambiguity an agent could hit.

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, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: matching semantics, ranking logic, the provenance rule (never mint a fact_id or compute from text), third-party-content/prompt-injection guidance, PIT refusal semantics, and plan-based coverage. However, the core 'read-only, no mutation' claim is restated at the end, and the return shape is largely delegated to the output schema, so it does not clear the highest bar.

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 grep analogy are front-loaded, and the MATCHING / RANKING / PROVENANCE caps make the long body navigable. The length is largely justified by 12 parameters and intricate matching rules, but it does repeat defaults already in the schema (max_results default 10/max 50, context_chars default 200/max 600), which is redundant.

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, the description need not explain return values, and it covers everything else an agent needs: query semantics, ranking, kind filtering, provenance constraints, PIT behavior, and plan coverage. Nothing material is missing for correct invocation.

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 meaningfully deepens parameter semantics: it explains matching behavior (case-insensitivity, line-break/pipe/punctuation splitting, '&' = 'and', stemming, whole-number matching), '|' alternatives, all_words within 300 characters, whole_word and case_sensitive effects, section keys sourced from list_filing_sections, and the ranking meaning of each kind. That is real added 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?

Opens with a specific verb and resource: 'Find a statement, note, heading or phrase inside a 10-K / 10-Q / 8-K', reinforced by a concrete grep analogy and examples. It explicitly distinguishes itself from read_filing_section (which serves the same text for reading) and from list_filing_sections (source of section keys), so an agent can route correctly 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?

States exactly when to use it (locating text inside a filing), names the alternatives and their roles (read_filing_section to read a hit via key/offset, list_filing_sections for section keys, fact tools for figures), and gives exclusions ('No regular expressions', text is not a Valuein figure). The PIT and plan-coverage notes further bound appropriate use.

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, so the safety profile is covered. The description adds genuinely non-obvious behavior: results are deterministic, the Beneish score is a recoverable subset (SGI + TATA + LVGI) flagged with partial=true, output is a severity-ranked red-flag narrative with filing citations, and access is limited to sp500+. That is real context beyond the structured fields.

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 tight paragraphs; the capability statement and output shape come first, and the limitation caveat follows. The SOP reference is short and earns its place. Minor density cost from the internal-input enumeration (AR / current assets / PPE / SGA), which is useful but slightly noisy.

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 annotations covering safety, the description need only cover method scope and constraints, which it largely does: partial-score semantics, tier eligibility, and citation-backed narrative. The main gap is behavioral detail for out-of-tier tickers or insufficient fundamentals (error vs. degraded result).

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?

There is a single parameter (ticker) with 100% schema description coverage including format examples, so the schema does the work. The description adds nothing about ticker semantics (e.g., whether BRK.B style symbols are normalized, or how unknown symbols are handled), so 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?

Front-loads a specific verb and resource ('deterministic forensic-accounting scores for a single ticker') and enumerates the three components (partial Beneish M-Score, Sloan accruals, solvency snapshot). It does not name a sibling it supersedes, but the composite forensic score is distinctive enough against neighbors like get_financial_ratios or compute_dcf.

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 rather than stated: the description says it is 'used by the forensic_earnings_brief SOP' and restricts tier to 'sp500+', which gives a scope boundary. However it never says when to prefer this over raw ratio tools, and it does not state what happens for a non-sp500 ticker (error, or degraded output).

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 annotations by disclosing the most important behavioral fact: inputs are rendered as-supplied and not re-derived, the workbook carries a visible unverified watermark, and response verification.status = 'unverified'. Also describes the artifact's structure (named Excel Table for one-click charts, subject-row highlight, Summary deltas), which an agent needs to write meaningful feedback about the output.

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, followed by labeled SERVER-TRUST and Pair-with guidance — efficient structure. Slightly padded with rationale prose ('the cleanest workaround for not embedding chart objects server-side') that serves the agent little, and the Tier line is appended without context for how the agent should act on it.

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?

An output schema exists and the description still adds the non-obvious parts the schema can't convey: watermarking, verification status, sheet layout, and the sourcing prerequisite. Nearly complete, though it doesn't say how the workbook is returned to the caller (link vs artifact reference) or whether repeated calls overwrite or create new artifacts, which matters given idempotentHint=false.

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 is 3; the description adds real meaning by explaining that the peer ratio values are treated as caller-supplied figures rather than recomputed, which changes how an agent should populate them. It doesn't say anything further about individual fields (notes placement, min/max peers), 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?

States a concrete verb + resource: render a peer comparables table into an Excel workbook, plus what the artifact contains (Comps sheet, Summary sheet). This clearly distinguishes it from sibling generators like generate_dcf_xlsx / generate_lbo_xlsx and from the data-retrieval sibling get_peer_comparables, which it explicitly names as the upstream.

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 routing guidance: use get_peer_comparables / get_financial_ratios first for authoritative numbers, and 'Pair with get_peer_comparables for a typical flow.' It also states the tier gate (pro+). Missing an explicit 'when not to use me' (e.g. choosing this over an inline table), so it stops 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 disclose that this is a non-read-only, non-destructive, non-idempotent operation, but the description adds substantial behavioral context: the DCF is re-derived in-Worker from inputs_echo, caller-supplied figures are never treated as authoritative, mismatches produce a visible correction banner and verification.status='corrected', and the response contains a 15-minute presigned R2 URL.

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 primary action and return artifact, then adds necessary trust-model details. The server-trust paragraph is dense but earns its place because it explains correction behavior and verification semantics. Overall it is appropriately sized for a complex file-generation 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?

An output schema exists, so the description need not enumerate return fields. It nonetheless covers the key output artifact (presigned URL with expiry), the verification status behavior, the correction banner, and the server-trust model. Combined with the schema and annotations, an agent has enough information to invoke the tool 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 schema already documents all parameters, giving a baseline of 3. The description adds meaningful semantics by explaining that dcf_result is typically the result from compute_dcf and that inputs_echo is used for server-side re-derivation. It does not specifically explain company_name, but the schema covers that.

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 uses a specific verb and resource: render a forward DCF result into an Excel workbook, and it names the workbook contents (Summary, 5x5 sensitivity heatmap, Inputs sheet). It clearly distinguishes materializing a file from computing the DCF via compute_dcf, and from sibling generators like generate_comps_xlsx and generate_lbo_xlsx.

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 describes the typical analyst flow: call compute_dcf, then pass the structured result to generate_dcf_xlsx. The pro+ tier is stated as a prerequisite. It does not explicitly state when not to use it, but the intended context and alternative are 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?

Goes well beyond the annotations: it discloses that the deal is re-derived in-Worker from inputs_echo, that caller-claimed figures are never trusted, that a visible correction banner plus verification.status='corrected' results on mismatch, and that the return is a 15-minute presigned R2 URL. This is exactly the kind of trust/side-effect context the readOnlyHint=false, idempotentHint=false annotations cannot 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 purpose and output, then the trust model and the flow. Dense with useful content and no filler, though the SERVER-TRUST paragraph uses shouted labels and the trailing 'Tier: pro+' is a slightly awkward tail.

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 three-param, deeply nested, non-idempotent tool with an output schema, the description covers what is produced, where it is delivered, how the artifact is validated, and what the verification status can be. Nothing an agent needs in order to call it or interpret the response 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 meaning by identifying that lbo_result is 'typically the result field returned by compute_lbo' and that only inputs_echo drives re-derivation, implying the other fields are informational. That helps an agent populate the nested object correctly, though parameter-level details of the projection block remain schema-only.

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 ('Render an LBO result into a professional Excel workbook') and enumerates the artifact's contents (Summary + Projection + Inputs sheet). The xlsx-generation siblings (generate_dcf_xlsx, generate_comps_xlsx) are implicitly distinguished by the LBO subject, and the pairing sentence makes the boundary with compute_lbo explicit.

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?

'Pair with compute_lbo for a typical flow: agent calls compute_lbo(...), then passes the structured result straight to generate_lbo_xlsx(...)' gives a concrete when-to-use and ordering. It also names the access gate ('Tier: pro+'). Missing an explicit exclusion (e.g. when to prefer compute_lbo alone or generate_dcf_xlsx), which keeps 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?

Annotations only tell the agent this is a non-read-only, non-destructive, non-idempotent, closed-world call. The description adds real behavioral context beyond that: content is rendered as-supplied and unverified, a visible 'figures supplied by caller, not verified by Valuein' watermark is stamped on the document, response `verification.status` is 'unverified', and the tool requires pro+ tier. It stops short of saying whether calls persist an artifact or what happens on repeat invocations.

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 in the first clause and organized into purpose / trust / flow / tier paragraphs, which suits a document-rendering tool. The masthead enumeration ('brand rule, wordmark, EQUITY RESEARCH kicker + date…') is decorative detail that does not help an agent decide or invoke, and is the main thing keeping this 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 an output schema present and 100% schema coverage, the description only needs to supply routing and trust context — and it does: the upstream/downstream call flow, the verification/watermark caveat, chart scope limits, and tier gating. Nothing an agent needs to call this 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 baseline is 3, but the description adds rendering semantics the schema lacks: `title` becomes the hero, `ticker` becomes the eyebrow, `author_name` becomes a 'By {name}' byline, `snapshot` renders as a mono-figure table, and `citations` become a table with clickable SEC EDGAR hyperlinks from `source_url`. It also confirms the `sections`+`citations` shape is interchangeable with create_report's output.

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 artifact: 'Render a structured research brief into a professionally-styled Word document', then enumerates exactly what the output contains (masthead, body, snapshot table, citations table, footer). It also positions itself against siblings — complementary to generate_dcf_xlsx/generate_comps_xlsx, downstream of create_report — so an agent can distinguish it from render_report or save_freeform_report 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 explicit call sequence ('typical flow is two tool calls: create_report → generate_research_brief_docx'), a named prerequisite ('Resolve each citation via verify_fact_lineage before publishing'), an alternative for a missing capability ('No embedded charts in v1; pair with generate_dcf_xlsx / generate_comps_xlsx'), and an entitlement gate ('Tier: pro+').

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 carry the read-only, idempotent, non-destructive profile, but the description adds several non-obvious behaviors: unknown ids and other-customer ids both return found:false rather than an error, and there is deliberately no distinguishing signal between the two cases. It also discloses a tier/entitlement constraint (sp500+, sample rejected), which is authorization context no annotation provides.

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 sentences, front-loaded with the core action and followed by the exception semantics and entitlement note. Dense and mostly waste-free, though the parenthetical '(sample rejected)' is slightly cryptic without additional context.

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?

An output schema exists, so return structure needn't be restated, and the description covers the one genuinely surprising return behavior (found:false as a non-error for two indistinguishable cases) plus the entitlement gate. 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 description coverage is 100% and the schema already states that agent_id comes from save_agent or list_agents. The description reinforces that the id must belong to the caller but adds no format, boundary, or validation 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?

States a specific verb (fetch), resource (one of the caller's own standing agents), and identifier source, with 'full detail' distinguishing it from the list_agents summary view. An agent can tell this apart from list_agents, get_agent_run, and get_agent_memory 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?

The description tells the agent where the id comes from (save_agent/list_agents) and scopes the lookup to the caller's own agents, which implicitly excludes other-customer ids. It does not explicitly contrast with list_agents as a bulk alternative or state when not to use this tool, so it falls short of the top score.

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 readOnly/idempotent/non-destructive, but the description adds materially new behavior: results are newest-first, an absent key yields an empty list rather than an error ('absence is a first-class answer'), and there is an access-tier gate ('sp500+, sample rejected'). That empty-result-not-error contract is exactly the kind of detail that prevents an agent from treating a miss as a failure.

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, then the two modes, then the error contract, then the access tier. No sentence is filler and no restatement of the title.

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 single-optional-parameter read tool with an output schema, all an agent needs is present: what it reads, how to scope it, ordering, empty-result behavior, and the tier requirement. Return-shape detail is correctly left to the output 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% and the schema already explains that null/omit means recall-all, so the description is largely restating it. It still adds the outcome semantics of a non-matching key (empty list, not an error), which is meaning beyond the schema's type constraints.

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 ('Recall this user's durable memory') and immediately defines the two operating modes: omit key for everything, pass key for one entry. Against siblings named set_agent_memory and delete_agent_memory, the read-only scope is 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?

Gives a strong positive trigger ('do this at the START of a task to re-ground yourself') and explains how to choose between the two call modes. It does not explicitly name the write/delete siblings as alternatives or state when not to call, so it falls just short of full routing guidance.

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 substantial context beyond the readOnly/idempotent annotations: unknown ids and ids belonging to another customer both return found:false rather than an error, and this is intentional with no distinguishing signal. It also discloses the sp500+ tier gate with sample rejection — genuinely non-obvious behavior an agent must plan for.

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 verb and the id source before the edge cases. Every clause carries information (fields returned, trigger ambiguity, not-found semantics, tier), though the run-on structure makes the tier note easy to skim past.

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?

An output schema exists, so return format is covered externally, and the description still summarizes the returned fields. Combined with the not-found semantics and tier requirement, an agent has everything needed to call this correctly and interpret the result.

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 schema already documents run_id's provenance, so the baseline is 3. The description earns a bump by explaining the semantic edge cases of that id — that a foreign or unknown id silently yields found:false — which is meaningfully more than the schema states.

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: 'Fetch full detail for one of the caller's own standing-agent runs by id', and enumerates the payload fields (status, goal, tickers, cost, artifact ids, role breakdown, error). It also names the sibling that produces the id (list_agent_runs), so it is distinguishable from list_agent_runs 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 explicit precondition chain ('from list_agent_runs') and clarifies a real ambiguity: the run may have been triggered by this agent or by the customer's Workspace. It does not name a competing sibling or state when-not to use it, but the single-param, single-purpose shape makes that near-moot.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context — and it does: the 'Institutional tier only' entitlement gate and the precise semantics of the going_active 13G→13D flip are non-obvious facts an agent could not infer. It stops short of any volume/latency or pagination notes.

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 sentences, front-loaded with purpose and scope, each carrying distinct information; the 'single most actionable activist signal' aside is slightly promotional but does encode a prioritization hint. A stray double space and the trailing tier note are minor blemishes.

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 and full parameter documentation, the description supplies what structured fields can't: the entitlement tier and the interpretation of the key derived flag. An agent could call this correctly, though a one-line contrast against get_top_holders would close the remaining 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 coverage is 100% (baseline 3), and the description still adds meaning: it explains that latest_only dedupes per filer, that collapse_groups folds multi-person filings into one row, and that the lookback window governs going_active detection — operational consequences the schema's one-liners don't spell out.

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 (returns SC 13D/13G blockholder disclosures, 5%+ stakes) with scope narrowed to US public companies, which naturally separates it from general holder tools like get_top_holders. It never names a sibling explicitly, so the differentiation is inferable 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?

Gives per-parameter guidance (latest_only default, collapse_groups, going_active lookback) and flags the activist signal as the actionable one, but never says when to choose this over get_top_holders or get_institutional_holdings, nor any exclusions.

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 the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it names the data source (annual 10-K filings), discloses PIT semantics via as_of_date, warns about the non-obvious accounting nuance that `total_deployment_pct_ocf` excludes R&D to preserve the cash-flow identity, and enumerates the exact booleans inside `flags`. That is material context an agent cannot get 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?

Purpose is front-loaded, followed by usage triggers, then the accounting caveat, flags, and plan availability — a sensible order. It is dense but nearly every sentence carries information; the enumerated question list is slightly long and the backtick field references partially duplicate the output schema.

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 annotations, a full output schema, and 100% parameter coverage, the description supplies everything else an agent needs: what data underlies the figures, how to avoid look-ahead bias, how R&D is treated in the ratios, and what the flags mean. Nothing required to invoke or interpret the tool 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%, and the schema already documents ticker (including CIK support), as_of_date PIT behavior, and the 1–20 lookback range with its default. The description adds only a restatement that as_of_date makes the call PIT-safe and no additional semantics for lookback_years, so the schema is doing 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?

Opens with a specific verb and resource — 'Get a multi-year capital allocation breakdown for a US public company' — and enumerates the six deployment categories plus derived ratios and flags. The scope is unmistakable, but no sibling tool (e.g., get_financial_ratios, compute_dcf, get_company_fundamentals) is named, so differentiation is inferred 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?

Provides a rich, explicit list of user questions that should route here — 'how does a company allocate capital', 'buyback-vs-dividend mix', 'is the company over-distributing' — including the owner-earnings and reinvestment-rate framings. Strong positive guidance, but no explicit when-not-to-use or named alternative for overlapping ratio 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 declare readOnly/idempotent/non-destructive, but the description adds real behavioral context beyond them: point-in-time semantics with no look-ahead bias, 10-K vs 10-Q sourcing, and a policy constraint against hand-derived arithmetic. It does not cover pagination or rate limits, but the output schema and the `strict`/`_meta.truncation` params carry the truncation story, so a 4 is right.

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 is front-loaded in the first sentence and each subsequent sentence adds a distinct constraint. The final two sentences re-state the 'never substitute your own arithmetic' point already made earlier, which is mild redundancy in an otherwise disciplined block.

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 9-parameter, output-schema-backed tool, the description covers purpose, data sources, point-in-time semantics, and sibling routing — everything needed to select and call it. The remaining gaps (truncation behavior, confidence suppression, response shape) are fully specified in the schema, so nothing critical 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 nine parameters in depth. The description reinforces only `as_of_date` (point-in-time reconstruction) and adds no syntax or interaction detail for `limit`, `strict`, `min_confidence`, or `lineage_detail`. Baseline 3 is appropriate when the schema 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?

States a specific verb and resource — 'Retrieve standardized SEC EDGAR fundamental financial metrics' — and enumerates the exact line items returned. It explicitly carves out territory against siblings (get_valuation_metrics, get_financial_ratios, compute_dcf) so an agent can tell it apart from the derived-metric tools 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 explicit when-to-use ('raw as-reported line items ONLY') and when-not ('Do NOT derive metrics from them yourself'), plus names the three alternative tools by the category of metric each serves. It even supplies a fallback behavior when a sibling is plan-gated, which is unusually complete routing guidance.

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 behavior beyond the readOnly/idempotent annotations: 15-minute expiry, signed URL, tier-bucket scoping, no bucket listing or cross-object reads, and HTTP range-read support. This is exactly the operational context needed to use a pre-signed download URL safely.

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-loads the core return and use case, then spends the remaining words on dataset meanings, the removed valuation table, and security constraints—all decision-relevant. The description is long but dense rather than padded.

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?

An output schema exists, annotations cover safety, and the input schema covers parameters, yet the description still supplies operational and dataset context. For a two-parameter tool with five enum choices, it covers what the agent needs to select dataset_type correctly and understand the returned URL's limits.

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 goes further by explaining what each dataset_type contains, including ratio's valuation category, filing metadata, references universe, and index_membership history. It adds real semantic value, though ticker syntax remains schema-only.

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: returns a short-lived download URL for a bulk Parquet object, and frames its purpose as high-throughput computation beyond the MCP context window. It names concrete destinations (Python/DuckDB/Polars) and distinguishes the removed valuation table path by pointing to compute_dcf.

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 clear when-to-use context (bulk computation exceeding the context window) and a specific alternative for intrinsic valuation (compute_dcf). It also explains dataset selection via dataset_type and the ticker requirement, though it does not broadly contrast with all in-context retrieval siblings.

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 (read-only, idempotent), the description discloses critical behavioral context: data provenance (SEC EDGAR only, no consensus feed), that eps_trend_est is a deterministic estimate from prior reported EPS, not analyst consensus, and that as_of_date enables look-ahead-free backtests. It also notes plan availability ('Available on all plans').

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 what the tool returns, followed by a crucial caveat about the trend estimate. It is slightly longer than strictly necessary but every sentence contributes important context (provenance, caveat, point-in-time use, plan availability) with 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?

Given the output schema exists, return values need not be explained. The description covers all essential aspects: purpose, data provenance, the non-consensus caveat, point-in-time safety, and plan availability. An agent has enough to invoke and interpret the tool 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 three parameters fully. The description reinforces the meaning of as_of_date (point-in-time filter by SEC acceptance for backtests) but adds no syntactic or format details beyond what the schema provides; the limit and ticker parameters are not elaborated in the description.

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 explicitly states the resource and scope: reported earnings results plus a model-derived earnings-trend signal by fiscal period, and lists the exact data points returned (EPS, eps_trend_est, eps_surprise_pct, revenue, YoY growth). This distinguishes it from generic fundamentals tools by focusing on earnings trajectory and the specific trend estimate.

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 guidance: 'Use it to track earnings/revenue trajectory and momentum, not to claim a consensus beat or miss,' and explains the point-in-time use case for backtests. It does not explicitly name alternatives like get_company_fundamentals or compare_periods, so it falls short of the explicit alternative-routing that a 5 would require.

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 annotations: discloses that valuation is LIVE but not strictly PIT (no accepted_at), that category availability varies per ticker and how to recover from DATA_NOT_AVAILABLE_FOR_PERIOD, the is_calendar_aligned join caveat, and that null values carry a reason rather than being real zeros. The recomputed_from_facts basis and derived_id citation behavior are exactly the kind of context annotations cannot express.

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-rich but dense and repetitive: the as_of_date PIT caveat is restated from the schema, the valuation/PIT caveat appears twice, and several sentences are long status-code parentheticals. It is front-loaded with purpose, but a good portion of the middle could be trimmed without losing meaning.

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 a 6-parameter tool with an output schema and read-only annotations, this covers the remaining burdens: category availability, PIT versus live caveats, TTM/FY mixing, calendar alignment, null semantics, lineage pointers, and derived_id citation. Nothing an agent needs to call or interpret 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 already 100%, but the description adds real semantics: omitting `categories` returns whatever the ticker has, `as_of_date` falls back from accepted_at PIT to period_end PIT (pit_safe=false), and `period_end_before` is an alias. `limit` is left to the schema, which already documents it, so it does not fully earn 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?

Opens with a specific verb+resource ('Get pipeline-computed financial ratios from ratio.parquet') and enumerates the served categories, so the agent knows exactly what data comes back. It also names the sibling it differs from (get_valuation_metrics) directly in the 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?

Explicit routing: 'Use this *instead of* get_valuation_metrics when you only need ratios (no DCF wiring); use get_valuation_metrics when you also need DCF/DDM.' It further routes PIT needs to get_company_fundamentals and provenance checks to verify_fact_lineage, so alternatives are named with the exact condition that selects each.

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 readOnly/idempotent/non-destructive, so the description correctly spends its words on what annotations cannot express: the neutralisation rules, the exact cluster threshold (≥3 distinct insiders in any rolling 30-day window), and the access tier restriction. It does not cover degenerate cases (no transactions, single insider, uncovered issuers) or what the score does when data is thin.

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 what the tool returns, then the methodology, then the eligibility constraint. Dense but nearly every clause carries information; the enumerated weight table is the longest block and is arguably justified for reproducibility.

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 annotations covering safety, the definition supplies the missing piece — the scoring methodology — and adds a tier restriction. Remaining gap is minimal coverage of empty/thin-data behavior for a metric that can easily have no qualifying transactions.

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 restates the lookback window and the 30-day cluster window consistently with the schema but adds no new parameter detail beyond what the schema already documents, and never mentions that ticker also accepts 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 computed artifact ('role-weighted insider sentiment score'), its scale ([-100, +100]), its scope (single issuer, lookback window), and the exact computation (weights, P=+1/S=-1, neutralised option exercises/grants/tax withholdings). This clearly separates it from the raw-transaction sibling get_insider_transactions.

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 'Institutional tier only' line is a real eligibility constraint, but the description never says when to pick this over get_insider_transactions (raw events) or get_smart_money_flow / get_top_holders. The distinction is inferable from the word 'composite' rather than stated, so usage is only implied.

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 readOnly/idempotent/non-destructive, so the description correctly spends its words elsewhere: the entitlement failure mode and its error code, the exact row payload, and the as_of_date vs lookback_days precedence. That is real behavioral context beyond structured fields, though rate limits, pagination, and empty-result behavior are unmentioned.

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 dense sentences, front-loaded with what is returned before the filter list and the entitlement caveat. The middle sentence listing filters largely duplicates the schema and could be trimmed, but nothing is padded or vague.

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 read tool with an output schema and full annotation coverage, the description supplies the payload shape, the entitlement constraint, and the as_of_date/lookback interaction — enough to call it correctly. The one gap is guidance on choosing between this and the related insider/holder tools.

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 ticker/CIK, limit, roles_in, as_of_date, min_shares, lookback_days, lineage_detail, and transaction_codes. The description restates the filter set and repeats the code legend (P/S/A/M/F) that the schema already provides, adding no syntax or edge-case detail beyond it — baseline 3.

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 a specific resource and its source documents ('Form 3 / 4 / 5 / 144 line items for a US public company') and enumerates the per-row fields returned, so the agent knows exactly what it retrieves. It does not explicitly contrast itself with adjacent siblings such as get_insider_sentiment, get_top_holders, or get_blockholders, so it stops short of 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?

The tier note ('Institutional tier only — sample / sp500 / pro return ENTITLEMENT_DENIED') is genuinely useful usage context, but it is about access, not selection. There is no statement of when to reach for this tool versus get_insider_sentiment or get_institutional_holdings, and no exclusions beyond the entitlement gate, so usage is implied rather than guided.

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: discloses that HHI is computed over EVERY common-stock 13F holder (not just returned rows), that a 45-day filing window governs period resolution, that in-window quarters are skipped/flagged, and that staleness_warning fires past 90 days. This is exactly the non-obvious operating context an agent would otherwise misread.

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 return statement and dense throughout; nearly every clause carries signal (HHI basis, default period, skip flag, staleness). It runs long as one paragraph with nested parentheticals, which slightly hurts scannability, but nothing 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?

With an output schema present, return-field explanation is unnecessary, and the description still names key output signals (newer_period_in_filing_window, filing_window_open, staleness_warning), so an agent knows what to expect. Combined with source, tier, and default-period behavior, nothing essential to 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 description coverage is 100%, so the schema already documents top_n ranking, as_of_date zero-look-ahead semantics, and period_end as reporting-period-not-cutoff. The description reinforces the default-period (45-day window) resolution but otherwise adds little parameter-level detail beyond the schema, warranting the baseline 3.

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 (top-N institutional holders of a US public company), names the exact source (Form 13F-HR by-issuer partition), and scopes to 'Institutional tier only', which implicitly separates it from block/de minimis holders. However, it never names get_top_holders or get_blockholders, so an agent comparing the near-identical sibling get_top_holders gets no explicit differentiation.

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?

Useful behavioral guidance is embedded (default period is the latest closed 45-day window; a newer in-window quarter is skipped and surfaced in newer_period_in_filing_window), but it never tells the agent when to choose this over a sibling like get_top_holders or get_blockholders. Usage is implied by scope rather than stated as an if/then rule.

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 safety, yet the description adds real behavior: the five QoQ delta buckets returned, the ambiguity error on multi-match names, zero-look-ahead semantics for late filings/amendments, and the include_superseded dedupe rule preventing an original and its 13F-HR/A being double-counted. That is substantive disclosure beyond the structured fields.

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 sentences, all front-loaded: what it returns, how to identify the filer, and the tier constraint. No filler, and the most failure-prone detail (identifier ambiguity) is surfaced early rather than buried.

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 7 optional parameters, an output schema, and full annotations, the description covers defaults, disambiguation, and look-ahead correctly. The remaining gap is what 'Institutional tier only' actually implies for a non-entitled caller — an error code or gating note would close 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 coverage is 100%, so baseline is 3, but the description adds value by ranking the two filer identifiers, explaining the fuzzy-match substring rule and its error, and reinforcing the period_end vs as_of_date trap that the schema states only in the per-parameter prose. It does not add anything on top_n or lineage_detail.

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 and scope: a 13F filer's full portfolio at a given period_end with QoQ delta categories. The filer-centric framing (portfolio of a manager) implicitly separates it from issuer-centric siblings like get_institutional_holdings and get_top_holders, and 'Institutional tier only' adds a scope 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?

Gives explicit selection guidance for the two mutually exclusive identifiers ('filer_cik (preferred) or filer_name') and spells out the failure mode of fuzzy matching. It also preempts the most likely misuse by contrasting period_end with as_of_date ('This is a REPORTING period, NOT a point-in-time cutoff'). It stops short of naming a sibling tool to use instead in any scenario.

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/non-destructive, but the description adds real behavioral context beyond them: 'most recent available' is explicitly not necessarily today's, absence returns `found: false` rather than an error, and there is a subscription-tier precondition. These are exactly the surprises an agent would otherwise mis-handle.

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 sentences, front-loaded with what the brief is, then the two calling modes, then the failure/tier caveats. No sentence is redundant with the name, title, or schema.

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 only one optional parameter, full schema coverage, a populated output schema, and complete annotations, nothing an agent needs is missing. The description still goes beyond the minimum by covering the empty-result and entitlement cases.

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 schema already documents `day` with the YYYY-MM-DD pattern, so the baseline is 3. The description earns an extra point by disambiguating the omitted-parameter case as 'most recent available (not necessarily today's)', which the schema phrasing does not make as pointed.

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 (read) and a precisely defined resource: the caller's Morning Brief, described as a daily AI-generated market digest over the customer's own watchlists and theses. The scope (per-customer, Workspace-produced) distinguishes it from sibling artifacts like get_report or get_research_file without opening either 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 conditional usage is given: omit `day` for the most recent available brief, pass a specific `day` for that day, and a missing brief is normal rather than an error. The tier gate (sp500+, sample rejected) tells the agent when the call will fail. No sibling alternative is named, which keeps it just 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?