Valuein — SEC EDGAR Fundamentals & Smart-Money Data

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

Annotations already mark destructiveHint, idempotentHint, and readOnlyHint, but the description adds substantial behavior beyond them: caller credentials are used instead of proposer credentials, already-decided actions are never re-executed, underlying failures transition to 'failed' without surfacing as tool errors, and cross-tenant IDs are indistinguishable from unknown IDs. This is rich, non-obvious context.

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 dense but every sentence conveys necessary behavioral or security semantics. It opens with the core actionholster, then explains idempotency, return values, failure mode, and tenant isolation without redundant phrasing, and closes with the tier restriction. Length is justified by complexity.

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 one well-documented parameter and an output schema present, the description still supplies the critical operational details an agent needs: credential scoping, concurrency safety, executed_now/tool_result/reason semantics, NOT_FOUND equivalence, and tier gating. 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?

The single parameter is fully documented in the schema, including provenance from stage_action or list_pending_approvals. The description adds the 'by id' invocation and idempotency semantics but does not provide additional parameter-level meaning beyond what the schema already states, 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?

The description states a specific verb and resource: approve a staged action by id and execute the underlying tool call it proposed. It clearly distinguishes this from related transitions like reject_staged_action, and clarifies it is the approval/execution path, not a mere status change.

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 gives strong context on when approval executes the underlying call ablueprint and when it returns current state, but it does not explicitly name reject_staged_action as the alternative for rejection. It covers idempotent and concurrency behavior thoroughly, leaving little ambiguity about when this call is appropriate.

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 mark destructiveHint and idempotentHint, but the description adds specific behavioral detail: only pending tasks are affected, completed tasks are irreversible, and already-cancelled tasks are no-ops. It also discloses the access tier restriction. This meaningfully supplements the structured annotations without contradiction.

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, with the core action first. Every sentence earns its place: source of the id, state constraint, idempotence, and tier restriction. No redundant or vague filler.

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

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

For a single-parameter tool with an output schema and annotations covering destructiveness/idempotence, the description covers all essential operational context: what it cancels, when it applies, how it behaves on already-cancelled/completed tasks, and access limits. No critical information for 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?

The input schema already covers task_id at 100%, so the baseline is 3. The description adds value by specifying where the id comes from ('from schedule_task or list_scheduled_tasks') and that the task must be pending, giving the parameter practical context beyond the schema's generic 'Identifier' 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 clearly states the action: 'Cancel a pending scheduled task by id', naming the specific resource and the distinguishing constraint (pending). It also references sibling tools schedule_task and list_scheduled_tasks for id provenance, which differentiates it from related scheduling 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?

The description provides explicit when-to-use guidance: only pending tasks can be cancelled, and completed tasks cannot be un-woken. It also notes that cancelling an already-cancelled task is a no-op, so the agent knows when the call is unnecessary. It does not name alternative tools for other scenarios, but the conditions are clear enough.

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

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

Annotations already declare read-only/idempotent, and the description adds rich behavioral context beyond them: significance thresholds, material_changes definition, server-side auto-swap with swapped flag, and point-in-time semantics via as_of_date. It also notes availability on all plans. No contradictions.

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?

Long but information-dense; every clause adds new behavior (thresholds, swap flag, triage guidance) not present in structured fields. Slightly heavier than necessary, but no fluff.

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?

Complete for a read-only comparison tool: covers purpose, input requirements, ordering, significance interpretation, point-in-time safety, and availability. Output schema is present so return-structure details are delegated appropriately.

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 already documents all four parameters and formats; the description adds crucial ordering semantics (period_a earlier, period_b later, auto-swap), the meaning of as_of_date for eliminating look-ahead bias, and examples of valid period strings. This goes 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?

The description states a specific verb ('compare') and resource ('core financial metrics across two fiscal periods'), and immediately distinguishes the tool with side-by-side absolute/percentage changes and significance classification. It is clearly differentiated from sibling tools 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?

Provides explicit usage context: use as a quick scalar to triage filings, period format requirements, and ordering instructions. It stops short of naming alternatives or exclusion conditions, but the guidance is substantive and unambiguous.

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?

With readOnlyHint/idempotentHint already covering safety, the description adds meaningful behavior: it pulls net income, shares outstanding, and EOD closes; explains how acquirer price is used to issue new shares and target price only for premium disclosure; and warns that synergy ramp, integration costs, and PPA amortization are excluded, directing agents to result.caveats[].

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 dense but every sentence earns its place: purpose is front-loaded, key inputs are mentioned, and caveats/output semantics are at the end. The formatting uses clear emphasis ('A SINGLE pro-forma-year bridge') to separate scope from mechanics.

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

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

For an 11-parameter tool with an output schema, the description covers what data is fetched, what the caller must set, what is deliberately not modeled, and how to interpret result.accretion_dilution_pct. It also points to result.caveats[] for remaining unknowns, making it complete enough to call correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how cash_pct/cash_financing_source form the consideration mix, describing synergies as annual run-rate, and clarifying the distinct roles of acquirer vs target share prices.

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

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

The opening sentence names a specific verb ('compute') and resource ('M&A accretion/dilution') and defines the metric in plain terms. It further distinguishes itself from multi-year models by stating it is a single pro-forma-year bridge, so an agent can separate it from compute_dcf/compute_lbo 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?

It clearly states when to use this tool: as a standard sell-side/banker quick-screen for first-year EPS impact. It also gives an explicit exclusion ('NOT a multi-year merger model') and lists omitted items, but it never names a specific alternative tool to use for the multi-year case, so it stops short of the 5-level 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?

Even though annotations already mark it readOnly/idempotent/non-destructive, the description adds critical behavior: R2-derived inputs with override semantics, share fallback chain, inputs_echo lineage, degenerate-model null semantics with reason field, and the fcf_source mode behavior. 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?

Dense and logically organized, front-loading the core result and caveats before mode details. Not maximally concise because some points (overrides, echo) are also present in schema descriptions, but every paragraph earns its place given the tool's complexity.

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 nested assumptions and an output schema, this is complete: it explains output fields, null semantics, source lineage, definitions, mode alternatives, and interactions with sibling tools. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it defines FCF base and net debt consistently with sibling tools, explains fcf_source 'trend' vs 'three_statement' behavior, clarifies that stage1_growth_rate is ignored in three_statement mode, and details shares resolution and three_statement_assumptions usage.

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?

Description opens with a specific verb and resource: 'Forward discounted-cash-flow valuation (two-stage Gordon-growth model)' and states it returns per-share intrinsic value plus a sensitivity grid. It clearly differentiates from siblings by naming get_valuation_metrics, compute_lbo, compute_accretion_dilution, and create_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 tells the agent when to use it ('Use this when you want to drive the assumptions yourself') and when not to ('for the pipeline's pre-computed DCF/DDM value ... use get_valuation_metrics instead'). Also clarifies it does not persist a report and routes to create_report with report_type:'reverse_dcf'.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the cash-free/debt-free balance sheet convention with explicit formulas, the 100% FCF-to-debt sweep default, and the bounded-bisection IRR solver with honest converged:false semantics. It also flags the EBITDA-by-operating-income proxy, a material data limitation the 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?

Dense but disciplined: each sentence covers a distinct facet — purpose and mechanics, outputs and numerical method, the EBITDA proxy, failure semantics, and caveats/tier. The key outputs (MOIC, IRR) appear early, with no filler or repetition of schema content.

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

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

For a complex 13-parameter financial model, the description covers model construction, solver behavior on failure, the key data limitation, and directs the caller to result.caveats[] for exhaustive simplifications. Since an output schema exists, return-value documentation is handled elsewhere, making the description complete for correct invocation and 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?

The schema already documents all 13 parameters with 100% coverage, so the baseline is 3. The description adds value by explaining how parameters combine — entry_debt = leverage_multiple × EBITDA and sponsor_equity = entry_enterprise_value + minimum_cash − entry_debt — plus tie-ins such as the EBITDA proxy unless entry_ebitda_override is supplied.

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 analytic ('Leveraged buyout returns analysis'), identifies the outputs (MOIC and IRR), and details the model mechanics. It is clearly distinct from sibling tools like compute_dcf and compute_accretion_dilution, which serve different valuation and M&A analyses.

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 states what the caller must supply (entry/exit multiples, leverage, hold period) and the access restriction (Tier: sp500+), giving a clear picture of the intended call. It does not explicitly route to alternatives such as generate_lbo_xlsx or state exclusions, so a small gap remains.

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 idempotentHint=true, and the description reinforces this with the idempotency_key parameter and 'same key always yields the same report id.' It adds the snapshot semantics (thesis edits do not propagate) and mentions a tier rejection (per-author state), providing behavioral context beyond the annotation 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?

The description is structured with bullet points for the two subtypes, front-loading the primary purpose in the first sentence. While longer than typical, the length is justified by the dual-mode complexity and each sentence contributes meaningful 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?

The description covers the required parameters per subtype, the output format (markdown, JSON, citation chains), idempotency behavior, and the tier restriction. With an output schema present, it provides sufficient context for an agent to call the tool correctly, including the need to reference saved theses.

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 clarifies the dependency between report_type and other parameters (ticker+params vs thesis_id), and notes that thesis_id comes from save_thesis/list_theses, adding contextual value beyond the schema's own descriptions.

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

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

The description clearly states 'Synchronously generate a research report and persist it under the caller's authorship,' naming the specific verb and resource. It further distinguishes two subtypes (reverse_dcf and thesis) with concrete behaviors, making it unambiguous against sibling tools like compute_dcf or generate_dcf_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 explains when to use each subtype: reverse_dcf for solving growth rate with a sensitivity grid, thesis for snapshotting a saved thesis. It notes that thesis edits do not propagate and a new report must be generated. However, it doesn't explicitly contrast with alternative report-generation tools (e.g., compute_dcf), relying on the persistence aspect to imply the distinction.

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?

With only non-informative boolean hints in annotations, the description carries the full burden and delivers rich behavioral detail: accepted triggers that have no live event source are persisted but never fire, trigger_wiring_status is authoritative from the dispatcher registry, test_rule verifies without spending a real dispatch, and condition_expr is intentionally restricted to prevent looping. This is unusually candid.

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 long but front-loaded and logically organized: purpose first, then wiring caveats, expression semantics, verification workflow, and access tier. Some content, such as the full trigger/action type lists, duplicates schema information, but each sentence earns its place because it adds context or warns about non-obvious behavior.

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 tool's complexity — multiple trigger types, a discriminated action union, an optional expression, replacement semantics, and an output schema — the description covers the critical operational knowledge an agent needs: which triggers actually dispatch, how to check wiring status, how to test safely, and the access tier. replaces_rule_id is not in prose, but the schema documents it thoroughly and an output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by identifying which trigger types are live vs not_yet_wired, explaining condition_expr's grammar and limitations, and recommending composing multiple rules for multi-condition logic. Remaining parameters like name, action, and replaces_rule_id are already fully documented in the schema.

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

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

The first sentence states a specific, unambiguous operation: 'Persist a trigger -> action rule and register it with the evaluator.' The description then enumerates the accepted trigger and action types, making the tool's scope immediately clear and distinguishing it from signal-creation and rule-testing 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?

The description gives strong usage direction: use test_rule immediately after creation to verify behavior, avoid relying on price_threshold/manual triggers because they will never fire, and compose multiple rules when more than one condition comparison is needed. It does not explicitly contrast this tool with create_signal or update_signal, but the provided scenarios are specific and actionable.

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 richly discloses behavior: the 5-minute cron evaluator, channel-specific delivery semantics (morning digest at local 7am, one transactional email per UTC day), webhook HMAC signing, and agent_run billing implications. This adds substantial context about side effects and recurring behavior.

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

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

The description is long but efficiently structured with bullet-like condition shapes and channel explanations. It is front-loaded with the core action and every section conveys usable semantics. Some detail repeats schema descriptions, which keeps it from a 5, but it is appropriately sized for a complex tool.

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

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

For a tool with five parameters, a discriminated union of conditions, multiple channel types, and plan gating (Pro+), the description covers the operational behavior, delivery semantics, cron schedule, verification path, and cost implications. An output schema exists, so return-value documentation is not required.

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 adds real meaning with concrete examples ('interest_coverage < 1.5', '1/5/21 trading days') and clarifies channel behavior beyond the schema, such as the morning digest contents and agent_run billing. It does not fully enumerate every parameter, but it enhances conceptual understanding.

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

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

The description opens with 'Persist a signal and register it with the firing pipeline,' which is a specific verb+resource statement. It goes on to enumerate the five condition shapes and delivery channels, making it easy to distinguish from sibling tools like test_signal, update_signal, and delete_signal.

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 gives clear context on when to use the tool, such as the condition types, channel selection, and the explicit pointer 'Use test_signal to verify your channels are wired correctly before relying on the cron.' It does not explicitly contrast with update_signal or delete_signal, though the schema's replaces_signal_id mentions update_signal.

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 readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds useful specifics beyond the annotations: system agents are rejected with a clear message, unknown/already-deleted ids return NOT_FOUND, and there is a tier restriction (sp500+). No contradiction with the 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?

Three dense, purposeful sentences with no filler. The primary action is front-loaded, and the constraints (system agents, idempotency, tier) are each given in compact, scannable clauses.

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?

The description is complete for a simple single-parameter deletion operation: it covers ownership, system-agent restrictions, idempotent behavior, tier gating, and where to find the is_system flag. An output schema exists, so return details are not required here.

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 only parameter, agent_id, already has a clear description. The tool description reinforces 'by id' and mentions how to find agents, but does not add substantially new meaning about the parameter's format or allowed values 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 action ('Delete one of the caller's own standing agents by id') with a clear resource and ownership scope. It also distinguishes itself from related deletion tools by noting system agents cannot be deleted and directing users to get_agent/list_agents for the is_system flag.

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 context for when the tool applies (deleting a caller's own standing agent) and an explicit when-not (system agents are rejected). It does not name an alternative tool for similar actions, but the scope and rejection rule give enough 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?

Even though destructiveHint=true, idempotentHint=true, and readOnlyHint=false already exist in annotations, the description adds significant behavioral context: every memory entry is re-read at the start of each run, so stale entries cause false re-grounding; deleting a missing key returns deleted:false rather than an error; the 200-entry cap; scope limited to YOUR memory note; and tier restriction (sp500+). This goes well beyond the 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?

The description is front-loaded with the core action and use condition, followed by rationale, idempotency, capacity, scope, and tier. Every sentence adds information, though the tier line ('sp500+ (sample rejected)') is a bit cryptic and the whole text is denser than strictly necessary. Still well structured and not 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?

With only one required parameter, a complete schema, an output schema, and annotations already covering destructive/idempotent, the description covers everything else: when to delete, why it matters, idempotent behavior on missing keys, the 200-entry cap, scope safety, and access tier. An agent lacks nothing needed to invoke this 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%, and the schema itself describes the key parameter well ('The memory key to forget. Discover keys with get_agent_memory (no key = list all).'). The tool description adds 'ONE durable' and 'your memory note' but does not materially extend the schema's parameter semantics. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Forget ONE durable memory entry by key.' It also distinguishes from siblings by explicitly saying it never touches a thesis, claim, report, or financial fact, which separates it from delete_claim, delete_report, delete_thesis, etc. An agent can instantly tell this is for memory notes only.

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 conditions for use: when a stored note is wrong, superseded, or was only scratch; when freeing a slot under the 200-entry cap. It also states what this tool does NOT do (never touches thesis/claim/report/financial fact), providing a clear when-not-to-use boundary against sibling tools.

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

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

Annotations already cover destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds the effect on reports (revert to canonical value on regeneration) and the idempotent behavior on missing overrides, which is consistent with annotations and adds value beyond 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?

Three sentences that front-load the purpose, then add idempotency and side-effect details efficiently. No wasted words, though the tier note is minor and not essential.

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?

Complete for a single-parameter delete operation. Output schema exists, annotations cover safety, and the description explains the behavioral consequence on reports. Nothing essential 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?

The schema already fully documents fact_id (including its origin from save_citation_override or list_citation_overrides), so the description adds no extra meaning beyond the schema. Baseline 3 applies given 100% 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 (Remove) and resource (user-authored citation correction) with the key parameter (fact_id). Clearly distinguishes from sibling delete tools by the specific resource type, even without naming an alternative.

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 usage as the delete counterpart to save_citation_override and list_citation_overrides, but does not explicitly state when to use it vs alternatives or when not to use it. No exclusion conditions or alternative tool names are provided.

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 (destructiveHint, idempotentHint), the description explains the concrete semantics: the row and score history stay for audit, the claim disappears from default list results, and repeating the delete on an already-archived claim succeeds. This meaningfully elaborates what 'destructive' and 'idempotent' mean here.

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 most important verb and object are front-loaded in the first sentence, and the remaining sentences each add distinct value: soft-delete effects, idempotency, and tier access. There is no filler or repetition of schema content.

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 mutation tool with an output schema, the description covers what happens to the record, the visibility effect, idempotency, and access eligibility. Nothing needed for correct invocation appears 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?

With one required parameter and 100% schema description coverage ('Id of the claim to archive'), the schema already fully explains the parameter. The description adds only 'by id,' which does not go beyond the schema, 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?

The description opens with 'Soft-delete a claim by id' — a specific verb plus resource and scope. It clarifies that the delete is an archive operation ('archived, not erased') and differentiates the effect from hard deletion and from 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?

The description implies usage: if you want to remove a claim from default list_claims results while preserving it for audit, this is the tool. It also includes a tier restriction ('sample rejected') as access context, but it does not explicitly name alternatives such as restore_deleted or unpublish_claim or give when-not-to-use 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?

The description discloses substantial behavior beyond the annotations: soft-delete semantics, exact status/visibility transitions, preservation of the row and R2 artifact with a 90-day audit window, idempotency, and the sample-tier rejection. This goes far beyond what destructiveHint and idempotentHint already convey, with no contradiction.

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 tight sentences that front-load the core operation and then efficiently add distinctions, idempotency, and a rejection case. Every sentence contributes, with no padding or 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-parameter mutation with an output schema and rich annotations, the description covers the essential context: ownership, soft-delete behavior, audit retention, idempotency, and sample-tier limitation. Nothing critical is missing for an agent to correctly invoke and interpret the operation.

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?

The input schema already describes report_id with provenance (`Id from create_report or list_my_reports`) and has 100% schema coverage. The description adds meaning by constraining the parameter further: only reports owned by the caller are valid, and sample-tier reports are rejected, which directly affects which report_id values are accepted.

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, with concrete effects (status flips to `delisted`, visibility to `private`). It clearly distinguishes itself from a hard delete and from sibling delete tools by scoping to reports owned by the caller.

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 provides useful context: the caller must own the report, sample-tier reports are rejected, and the op is idempotent. However, it does not explicitly name sibling alternatives such as unpublish_report or restore_deleted, nor when one should be chosen over the other. Usage is implied rather than explicitly routed.

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. The description adds value by explaining the mechanism ('removes it from both the catalog and the evaluator's scan index, so it stops firing immediately') and the immutability consequence. It also states idempotency explicitly, which reinforces the annotation. The tier restriction is an additional behavioral constraint not in the annotations. 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?

Three sentences, each earning its place: the action and its effect, the immutability workflow, and the idempotency/tier constraints. The most important information (what it deletes and the immediate effect) is front-loaded. No wasted words.

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 delete tool with full schema coverage, an output schema, and annotations covering destructiveness and idempotency, the description is complete. It covers the source of the id, the effect, the alternative workflow, and the access restriction. 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%, so the schema already documents the single parameter (rule_id). The description adds the provenance of the id ('from create_rule/list_rules'), which is useful context beyond the schema's 'Identifier of the rule to delete.' However, with full schema coverage, the baseline is 3, and the description's added value is modest but real.

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 ('Delete'), a resource ('a rule by id'), and the source of the id ('from create_rule/list_rules'). It also distinguishes itself from other delete_* siblings by naming the exact resource and its provenance. The phrase 'removes it from both the catalog and the evaluator's scan index' further clarifies the scope of the deletion.

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 explicitly says when to use this tool: to delete a rule by id, and it gives the alternative workflow for changing a rule ('Rules are immutable — to change one, delete then create_rule'). It also states the tier restriction ('Tier: sp500+ (sample rejected)'), which is a clear usage constraint. This is explicit when/when-not 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?

Annotations already provide destructiveHint and idempotentHint, but the description adds specific behavioral consequences: status flips to 'deleted', it is removed from the cron evaluator index so it stops firing, and it is idempotent. It also discloses the tier restriction ('sp500+'). 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?

Two sentences pack the action, side effects, immutability guidance, idempotency, and access tier without any redundancy. The core action is front-loaded and each clause earns its place.

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

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

For a single-parameter destructive tool with full schema coverage, annotation coverage, and an output schema, the description provides everything needed: the operation, its effect on the signal and cron index, the mutation strategy, idempotency, and access restrictions. 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 coverage is 100% and the schema's signal_id description already states the source ('as returned by create_signal or list_signals'). The description reinforces this but adds no new semantic detail beyond the schema, so the baseline 3 for high schema coverage 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 opens with the specific action 'Soft-delete a signal by its id', names the resource, and clarifies the effect ('status flips to deleted', 'removed from the cron evaluator index'). It also distinguishes from update_signal by declaring signals immutable, leaving no ambiguity about what this tool does versus 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?

It explicitly states the id source (create_signal/list_signals) and gives a clear directive for the alternative: 'to change one, delete then create_signal.' This tells the agent when to use this tool (deletion) and when not to use it for updates, which is valuable given the presence of update_signal among 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?

The annotations already supply idempotentHint=true and destructiveHint=true, but the description adds meaningful behavioral context: the status flip to archived, row retention for audit/re-scoring, absence of hard-delete, no cascade to claims, and possible future expiration. No contradiction exists with the 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?

The description is compact, front-loaded with the primary behavior, and every sentence earns its place: soft-delete semantics, idempotence, no hard delete, no claim cascade, and tier eligibility. There is no filler or repetition.

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 tool with full schema coverage, an output schema, and useful annotations, the description is complete. It covers behavior, side effects, exclusions, idempotence, and access limits, so an agent has everything needed 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?

The schema already fully documents thesis_id with 100% description coverage, including where the id comes from. The description adds no parameter-level meaning, so the baseline of 3 applies; the schema carries the burden.

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

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

The description opens with a specific verb and resource: 'Soft-delete a saved thesis.' It clearly distinguishes this from hard-delete and from deleting linked claims, so an agent can tell it apart from delete_claim and 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?

The description explicitly says to use delete_claim for claims linked to the thesis, states that hard-delete is not supported, and gives an idempotence rule for already-archived rows. It also communicates the tier restriction, giving clear guidance on when this tool does and does 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses the 24h TTL and that deleting missing/expired/foreign IDs returns deleted:false instead of raising an error. This is valuable behavioral context that annotations alone do not 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?

Two concise sentences with no filler. The primary behavior is front-loaded, and the edge-case handling follows immediately. Every sentence contributes useful information.

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

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

For a single-parameter destructive idempotent tool with an output schema, annotations, and full schema coverage, the description provides all necessary behavioral guidance. Nothing critical is missing for an agent to select and 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?

The single parameter upload_id is already fully described in the schema (returned by POST /v1/uploads), and schema description coverage is 100%. The description adds contextual terms like TTL and foreign id but does not add new parameter-specific meaning 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 action (delete) and resource (uploaded document), and adds a unique scope constraint ('before its 24h TTL') that distinguishes it from other delete_* siblings. An agent can determine what this tool does 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?

The description clearly conveys when to use the tool (to delete an uploaded document before its TTL expires) and explains the behavior for edge cases. It does not explicitly name alternative tools, but the sibling context makes the intended use unambiguous.

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 indicate destructive=true and idempotent=true, but the description adds substantial behavioral context beyond them: this is a soft-delete rather than a hard delete, the status flips to archived, the item remains readable, the name is freed for reuse, and the access tier is sp500+. These details are consistent with the 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?

The main operation is front-loaded, followed by the key behavioral consequences, idempotency, and access tier. Every sentence earns its place, and the description is compact without losing important details.

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 tool with a full output schema and annotations, the description covers the operation, post-delete state, readability, name reuse, idempotency, and access restrictions. Nothing an agent needs to call 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?

The schema covers the name parameter with 100% description coverage, so the baseline is 3. The description adds marginal value by emphasizing that the parameter is the name 'not id', which helps prevent incorrect invocation when other tools use IDs.

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–resource pair, 'Soft-delete a watchlist', and immediately adds the key discriminator 'by its name (not id)'. It clearly distinguishes this from the other delete_* siblings by naming the resource and the exact soft-delete behavior (status flips to archived).

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 conveys when to use the tool: to archive a watchlist and free its name for a future save_watchlist, and it notes that archived watchlists are still readable via list_watchlists with status=all/archived. It does not explicitly mention alternatives such as restore_deleted or state a when-not-to-use condition, so it falls slightly 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 readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful context beyond those: the schema is embedded in the manifest, no data reads are required, and it is available on all plans. This reassures an agent about cost and access without contradicting the 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?

The description is compact, front-loaded with the core purpose, then adds return contents, usage timing, and efficiency context. Every sentence earns its place with no filler or repetition.

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

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

For a read-only, single-parameter schema-inspection tool with an output schema and strong annotations, the description is complete. It tells the agent what it returns, why it is cheap, when to use it, and that it works on all plans — nothing needed for 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 single optional `table` parameter is already well documented in the schema. The description adds context by framing the parameter as a filter over the full-schema return, but it does not need to repeat parameter syntax. Baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Returns'), names the exact resource ('Parquet schema for all tables in the Valuein SEC data warehouse'), and enumerates what is included: table descriptions, columns, types, primary keys, and foreign keys. This makes the tool's purpose unambiguous and distinguishable from the many get_* and list_* 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?

The description explicitly states when to use it: 'Use this tool to understand the data model before querying with other tools.' This provides clear context for invocation, though it does not formally name alternatives or exclusions, so it falls just 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?

Beyond annotations, it discloses the soft-delete behavior, the dismissed_at field, audit queryability, and idempotence. It also adds the access tier constraint (sp500+, sample rejected), which is useful operational context. No contradiction with the destructiveHint or idempotentHint 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?

Three short sentences, front-loaded with the core purpose, then audit behavior, idempotence, and access tier. Every sentence adds information an agent needs and there is no filler.

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

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

The tool is simple: one parameter, with output schema and annotations already provided. The description covers the source of the id, the soft-delete semantics, the audit path, idempotence, and access tier. Nothing necessary for 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?

The schema already documents the single parameter at 100% coverage, so the description does not need to restate it. It adds real value by clarifying that inbox_id comes from list_signal_inbox and is not a signal id, plus noting the idempotent effect.

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

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

The description opens with 'Soft-delete a single inbox item by its id', naming a specific verb and resource. It explicitly says the id comes from list_signal_inbox and is 'not a signal id', which distinguishes it from delete_signal and other delete-type 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?

It gives clear context for use by pointing to list_signal_inbox as the source of ids and to include_dismissed=true as the audit/restoration path. It does not explicitly contrast with mark_inbox_read or restore_deleted, so exclusions are not fully 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?

It discloses substantive behavioral traits beyond the annotations: the tool is deterministic, computes only a recoverable subset of the full Beneish M-Score, flags `partial=true`, and returns a severity-ranked red-flag narrative with citations to source filings. This is genuinely useful context that annotations alone do not 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 tight and front-loaded with the core function, then adds a concise and highly relevant limitation note. Every sentence adds value, and the structure clearly separates main behavior from constraints.

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 one well-documented parameter, an output schema, and annotations covering read-only/idempotent behavior, the description provides all essential additional context: return type, limitation, partialness flag, tier restriction, and intended SOP association. Nothing critical appears 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% for the single `ticker` parameter, including examples and constraints. The description adds only 'single ticker' and 'Tier: sp500+', which are helpful but do not materially enhance understanding of the parameter 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 action and resource: 'Deterministic forensic-accounting scores for a single ticker' covering Beneish M-Score, Sloan accruals, and solvency. It clearly lists outputs, but it does not explicitly differentiate itself from sibling analytical tools or name alternatives, so it stops short of full sibling 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?

The description implies usage through 'Used by the forensic_earnings_brief SOP' and explains the partial computation context. However, it does not explicitly state when to choose this tool over alternatives, nor does it enumerate exclusion conditions or clearly define the expected use case for an autonomous agent.

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 adds substantial behavioral transparency beyond the sparse boolean annotations. It discloses the server-trust model, that ratios are rendered as-supplied, that the workbook carries an 'unverified' watermark, and that response verification.status equals 'unverified'. It also describes output structure (Comps and Summary sheets) without contradicting any annotation.

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 then organized into useful sections, including the SERVER-TRUST callout. It is a bit longer than necessary—some formatting details like 'one-click Insert Chart' and 'Tier: pro+' are helpful but not essential—so it earns a 4 rather than 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?

For a tool with only four params, complete schema coverage, a rich behavioral disclosure, and an output schema, the description is comprehensive. It covers the output format, verification semantics, typical pairing, and data-sourcing expectations, leaving no critical gap for an agent 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?

Input schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some contextual meaning about how values are used (ratios rendered as-supplied, subject vs peer-median deltas) but does not go into parameter-specific behavior, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Render a peer comparables table into an Excel workbook.' It clearly identifies the domain (peer comps) and distinguishes this from sibling workbook generators like generate_dcf_xlsx and generate_lbo_xlsx by naming its unique output features (named Excel table, Summary sheet, subject-row highlight).

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 gives clear usage context: 'Pair with get_peer_comparables for a typical flow' and tells agents to source authoritative numbers from get_peer_comparables / get_financial_ratios first. It does not explicitly enumerate when-not-to-use alternatives, hence not a 5, but the guidance is unambiguous.

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 are all false hints, so the description carries full behavioral disclosure. It richly explains that the DCF is re-derived from inputs_echo, that caller-claimed values are never treated as authoritative, that a correction banner appears on disagreement, and that verification.status may be 'corrected'. It also reveals the presigned URL timeout and native formatting — far 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 longer than minimal but every section earns its place: purpose, trust model, and pairing flow. It is front-loaded with the deliverable and features. The SERVER-TRUST section is clearly labeled and the pairing paragraph is actionable. Slight verbosity in the trust explanation prevents 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?

For a tool with nested objects and an output schema, the description covers all essential agent-facing concerns: deliverable structure, server-side re-derivation, correction behavior, URL expiry, and the canonical pairing with compute_dcf. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema already describes ticker, dcf_result, and company_name, including that dcf_result is typically the result field from compute_dcf. The tool description adds some context (e.g., inputs_echo role in re-derivation) but does not materially extend parameter semantics beyond the schema, so a 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 opens with a specific verb and resource: 'Render a forward DCF result into a professional Excel workbook' and enumerates exact contents (Summary + 5×5 Sensitivity heatmap + Inputs sheet). It clearly distinguishes this from sibling xlsx generators like generate_comps_xlsx and generate_lbo_xlsx by focusing on DCF output.

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 gives an explicit usage flow: 'Pair with compute_dcf for a typical analyst flow: agent calls compute_dcf({ticker, ...}), then passes the structured result straight to generate_dcf_xlsx({ticker, dcf_result, ...})'. This clearly states when to use the tool, though it does not explicitly enumerate when not to use it (e.g., for comps or LBO).

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?

With annotations only indicating non-read-only and non-idempotent, the description carries the full behavioral burden and excels: it discloses server-side re-derivation from inputs_echo, deterministic math, that claimed figures are never trusted, the correction banner, and the verification.status='corrected' response. It also reveals that the URL expires in 15 minutes. 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?

The description is front-loaded with the core purpose and output, then layers in the server-trust behavior, the compute_lbo pairing, and the tier constraint. Each sentence earns its place, and the structure moves from what the tool does to how it behaves to how to use it. 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 richly nested lbo_result schema and the existence of an output schema, the description covers everything an agent needs to invoke correctly: the parameter flow, the server-side verification behavior, the correction mechanism, the URL expiry, and the expected verification status field. 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 ticker, lbo_result, and company_name. The description adds meaningful context beyond the schema by highlighting lbo_result.inputs_echo as the source for re-derivation, which helps an agent understand that the supplied lbo_result is not blindly accepted. This is useful semantic enrichment over the structured field definitions.

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

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

The description opens with a specific verb and resource: 'Render an LBO result into a professional Excel workbook' and enumerates the exact sheets (Summary, year-by-year Projection table, Inputs sheet). It also names the return artifact (15-minute presigned R2 download URL), which clearly distinguishes it from sibling generators like compute_lbo, generate_dcf_xlsx, and generate_comps_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?

The description explicitly provides the typical flow: call compute_lbo first, then pass the structured result to generate_lbo_xlsx to materialize a shareable file. It also notes the pro+ tier constraint. However, it does not mention when to avoid this tool or name alternatives like generate_dcf_xlsx, so the guidance is clear but lacks explicit 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?

The description adds substantial behavior beyond annotations: it details the document layout, the missing-chart limitation in v1, the unverified-content watermark, and the `verification.status`='unverified' response field. This is exactly the kind of context that lets an agent predict side effects and trust boundaries, and it does not contradict the annotations (readOnly=false, destructive=false).

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 long but information-dense, front-loading the purpose, then layout, then usage caveats. Nearly every sentence earns its place, though the 'Tier: pro+' line and the 'SERVER-TRUST' label add minor noise. Not bloated, but slightly more verbose than the most efficient version.

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 tool's complexity (8 parameters, rich output formatting, integration with other tools), the description covers all essential aspects: document structure, integration flow, verification requirements, and limitations. Since an output schema exists, not explaining return values is acceptable. An agent can correctly invoke this tool with no additional research.

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 the schema already describes all 8 parameters, the description enriches their meaning by mapping each to the document's rendering: abstract shown after the masthead, snapshot rows in the snapshot table, citations as clickable SEC EDGAR links, author_name as a byline, and company_name's fallback to ticker. This turns schema definitions into actionable layout decisions.

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

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

The description opens with a specific verb and resource: 'Render a structured research brief into a professionally-styled Word document'. It immediately distinguishes itself from siblings by stating 'No embedded charts in v1; pair with `generate_dcf_xlsx` / `generate_comps_xlsx`', making the tool's unique role in the report-generation pipeline 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?

Provides concrete when-to-use guidance: the typical flow '`create_report` → `generate_research_brief_docx`' and how to combine with `generate_dcf_xlsx`/`generate_comps_xlsx` for charts. It also gives a prerequisite action ('resolve each citation via `verify_fact_lineage` before publishing'), clearly instructing the agent on proper sequencing and alternative 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 mark read-only/idempotent, and the description adds valuable behavior beyond them: unknown ids and other-customer ids both return found:false with no distinguishing signal, by design, and the tier restriction is stated. This is exactly the kind of extra behavioral context 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?

Three sentences, front-loaded with the main behavior, no wasted words. Every clause earns its place: id source, not-found behavior, design rationale, and access tier.

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 read-only tool with full schema coverage and an output schema, the description is complete. It covers the success case, failure semantics, privacy boundary, and access tier, so an agent can call it without surprises.

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 describes agent_id as coming from save_agent/list_agents. The description adds 'caller's own' and 'standing' qualifiers, which clarify ownership and lifetime in a way the schema alone does not.

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?

Description uses specific verb 'fetch full detail' with clear resource: one of the caller's own standing agents by id. It also names the source functions (save_agent/list_agents) and implicitly contrasts with get_agent_run.

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 provides clear context: use this when you already have an agent_id from save_agent/list_agents and need full detail. It does not explicitly list when to prefer a sibling tool, but the ownership and id-source constraints make the intended usage unambiguous.

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 readOnlyHint/idempotentHint annotations, the description discloses ordering ('newest-first'), the empty-list-not-error behavior ('absence is a first-class answer'), and the access tier ('sp500+'). These are meaningful behavioral details an agent needs to interpret results correctly.

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 short, information-dense sentences. The core behavior and usage instruction are front-loaded, and every sentence earns its place — including the empty-list caveat and access-tier 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 simple one-optional-parameter read tool with an output schema and safety annotations, the description covers all relevant behavior: how to request all memory, how to request a specific key, ordering, absence semantics, and access restrictions. Nothing an agent needs to decide whether to call this tool 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 the schema already fully documents it: specific key or omit/null to recall all memory newest-first. The description largely repeats this and adds behavioral context rather than new parameter-level semantics, so the baseline of 3 applies.

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

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

Description states a specific verb ('Recall') and resource ('this user's durable memory'), then distinguishes two invocation modes: omit key for everything versus pass a specific key for one entry. It is immediately clear what the tool does and how it differs from a generic get/list 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?

The description gives explicit when-to-use guidance: 'do this at the START of a task to re-ground yourself,' and explains the keyed versus unkeyed call pattern. It does not name alternatives or exclusions relative to sibling memory tools, but the read-only framing and practical instruction provide clear context.

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

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

Beyond the readOnly/idempotent annotations, it explicitly discloses the important edge behavior: an unknown id or another customer's id returns found: false rather than an error, and there is deliberately no distinguishing signal. This is exactly the kind of behavioral nuance 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?

The description is compact and front-loaded with the core operation, then adds edge behavior and access tier. Every clause earns its place, with no filler or redundant boilerplate.

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 getter with an output schema and strong annotations, the description covers the source of the id, what fields are returned, the not-found behavior, cross-workspace eligibility, and the tier requirement. Nothing necessary for safe 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 coverage is 100% and the schema already describes run_id as the identifier from list_agent_runs. The description adds some context about 'caller's own' runs and the cross-customer found: false behavior, but does not materially extend parameter meaning 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 opens with a precise verb and resource: 'Fetch full detail for one of the caller's own standing-agent runs by id'. It also ties the id to list_agent_runscars, making it easy to distinguish from list_agent_runs and other getters.

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 clearly signals the source of run_id ('from list_agent_runs') and clarifies that it works for runs triggered by the agent or by the customer's Workspace. It lacks an explicit 'use this instead of X' statement, but the usage context 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 already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds valuable behavioral context: the going_active flag semantics (13G→13D flip within the lookback window), the default deduplication behavior, the effect of collapse_groups, and the access tier restriction. These details go beyond what the annotations provide and help the agent predict tool behavior.

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

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

The description is information-dense and well-front-loaded: the purpose appears in the first sentence, key output semantics and the most important flag follow immediately, then parameter usage guidance, then access tier. It is longer than average but every sentence adds substantive context. No filler or repetition is present, though the promotional phrase 'single most actionable activist signal' is slightly extraneous.

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 rich output schema and 100% parameter coverage, the description is complete enough for correct invocation. It covers the core semantics, default behaviors, access restriction, and the headline going_active signal. It does not discuss sorting or pagination, but those are typically conveyed in the output schema, and no critical operational detail is missing for a read-only data retrieval tool.

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 input schema already documents every parameter thoroughly. The description adds framing for the overall query concept and the going_active flag, but it mostly restates parameter effects already present in the schema (e.g., latest_only dedupe, collapse_groups folding). Since the schema carries the load, a baseline of 3 is appropriate; the description does not materially increase per-parameter understanding.

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

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

The description opens with a clear, specific verb-resource pairing: 'Returns SC 13D / SC 13G blockholder disclosures (5%+ stakes) for a US public company.' It names the exact regulatory filings, the ownership threshold, and the issuer scope, which distinguishes it from sibling retrieval tools like get_top_holders and get_institutional_holdings. An agent can immediately understand what data this tool exposes and how it differs from related lookups.

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 clearly communicates the intended use case (blockholder activist/passive ownership data) and provides explicit parameter usage guidance for latest_only, collapse_groups, and the going_active flag. It does not name alternatives directly or state when-not-to-use, but the specificity of the regulatory filing scope and the 'Institutional tier only' access note give clear context. This is slightly below the top tier because no sibling comparison is made.

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 readOnly/idempotent, so the description carries the full behavioral burden and exceeds it: it discloses the 10-K source, PIT-safe semantics via as_of_date, the R&D exclusion from total_deployment_pct_ocf to preserve the cash-flow identity, and the exact meaning of each flag. 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?

The description is long but information-dense and front-loads the core output before use cases and caveats. Some non-essential framing (Buffett/Damodaran labels, 'Available on all plans') could be trimmed, but the structure is otherwise efficient for a tool with this much nuance.

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 handling the return structure, the description covers everything else needed for correct invocation: what the tool returns, what question types it serves, data provenance, PIT behavior, the R&D accounting caveat, and the flag semantics. No material gap remains.

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 three parameters; the baseline is therefore 3. The description reinforces as_of_date's point-in-time role and implies lookback_years via 'multi-year', but it doesn't add meaningful semantics beyond what the schema provides.

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?

Description opens with a specific verb and resource: 'Get a multi-year capital allocation breakdown for a US public company.' It enumerates the six deployment categories, the pre-computed ratios, and the flags, making the tool's scope unmistakable and distinguishing it from financial-data siblings like get_financial_ratios or get_valuation_metrics.

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

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

The description explicitly lists trigger questions ('how does a company allocate capital', 'buyback-vs-dividend mix', 'where does the money go') and the analytical styles it supports. It does not, however, name sibling alternatives or state when not to use this tool, so it stops just short of perfect 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?

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond those annotations by revealing that the response includes supporting/refuting thesis ids and full append-only score history, and clarifies access tiers. 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?

The description is compact and front-loaded: it states the action, the key returned data, the intended use, and access eligibility in three short sentences. There is no filler or repetition of schema fields.

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

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

For a simple one-parameter read-only tool with a full output schema and strong annotations, the description covers everything an agent needs to select and invoke it correctly: what it returns, why to use it, and tier availability.

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 single required parameter claim_id is already documented as coming from save_claim or list_claims. The description adds no new semantic detail about the parameter beyond saying 'by id', so baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Fetch a single claim by id', and immediately specifies what is included (supporting/refuting thesis ids, append-only score history). This distinguishes it clearly from list_claims and list_claims_for_thesis, which retrieve collections rather than a single claim.

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 gives a clear use case: 'inspect a claim's evidence, current status, and how its outcome has evolved.' It does not explicitly name alternatives or exclusion criteria, but the 'single claim by id' phrasing implicitly rules out list-oriented sibling tools. The tier note also clarifies who is allowed 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?

The description discloses rich behavioral detail beyond the annotations: point-in-time no-look-ahead semantics, provenance/fact_id requirements, confidence-score suppression that fails closed, and the guarantee that withheld metrics are never silently dropped. The annotations only cover read-only/idempotent/non-destructive properties, so this added transparency is substantial.

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 long but every sentence earns its place: what the tool returns, data source, point-in-time behavior, provenance constraints, and sibling routing. It is front-loaded with the core purpose and structured logically, with no filler or redundancy.

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 9-parameter schema, output schema, and annotations, the description is complete enough for safe and correct invocation. It covers filing source, period granularity, point-in-time behavior, provenance, confidence suppression, response shapes, and exact alternatives for derived metrics.

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% with detailed parameter descriptions, so the baseline is 3. The description adds further meaning beyond the schema for as_of_date (point-in-time reconstruction), strict (plan-limit failure behavior), min_confidence (penalty model and suppression semantics), and response_format (quote display strings verbatim). This is meaningful added 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?

The description states a specific verb and resource: 'Retrieve standardized SEC EDGAR fundamental financial metrics for a US public company' and lists the exact line items returned. It also differentiates this tool from sibling metric/ratio tools by emphasizing that it returns raw as-reported line items only.

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 tells agents when not to use this tool: 'Do NOT derive metrics from them yourself.' It routes derived metrics to get_valuation_metrics, get_financial_ratios, and compute_dcf, and even specifies what to say if those tools are plan-gated. This gives clear, actionable selection 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?

Annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral detail beyond that: the URL expires in 15 minutes, the stream supports HTTP range reads, access is scoped to the caller's tier bucket, and the signed link cannot list or read other objects. This gives an agent a clear and honest safety model.

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 dense but front-loaded: the first sentence captures the core purpose and usage, followed by practical streaming details, dataset semantics, a deprecation note, and security constraints. Every sentence contributes actionable information, and the structure makes it easy to scan.

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 already covers return shape, the description fills all operational gaps: URL lifetime, range-read support, dataset variations, the deleted valuation table, and access scoping. An agent has enough to invoke the tool correctly and safely without additional research.

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 goes well beyond it by unpacking each dataset enum value: fact is per-entity and requires ticker, ratio includes the valuation category with concrete examples, and the remaining datasets are full-universe. It also clarifies that the standalone valuation table no longer exists, which prevents a likely misuse.

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

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

The description opens with a specific verb and resource: returns a 15-minute download URL for a bulk Parquet object for high-throughput compute. It enumerates the exact datasets and distinguishes the tool's streaming/range-read behavior from ordinary file downloads, making its purpose unmistakable even among many 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?

It clearly frames when to use the tool: for computation that exceeds the MCP context window and when piping into Python/DuckDB/Polars. It also explicitly routes the removed 'valuation' table use case to compute_dcf, providing one concrete alternative. It stops short of naming each sibling it competes with, leaving a small gap in exclusionary 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?

Annotations already mark this as read-only, idempotent, and non-destructive; the description goes well beyond them by explaining the SEC EDGAR-only source, that eps_trend_est is a deterministic estimate rather than analyst consensus, what eps_surprise_pct measures, and the point-in-time semantics of accepted_at. This meaningfully reduces the risk of misinterpretation.

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 purpose and field names before the caveats, and the caveats are substantive rather than filler. It is long but earns its length; only 'Available on all plans' is non-essential.

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

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

With an output schema present, return values don't need explaining in prose. The description covers data source, metric interpretation, the key non-consensus caveat, and backtesting usage, leaving no important decision or invocation context 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?

The schema covers all three parameters with descriptions, so the baseline is 3; the description adds value by explaining the output fields' meaning and by clarifying that as_of_date filters on SEC acceptance for look-ahead-free backtests. The limit and ticker semantics are already fully documented in the schema.

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

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

The description clearly states the tool returns reported earnings results plus a model-derived earnings-trend signal per fiscal period, naming concrete fields (actual EPS, eps_trend_est, eps_surprise_pct, revenue, YoY revenue growth). It also distinguishes the signal from Wall Street consensus, but does not name or differentiate from sibling data-retrieval tools such as get_financial_ratios or get_company_fundamentals.

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

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

Provides explicit guidance: use it to track earnings/revenue trajectory and momentum, not to claim a consensus beat or miss, and pass as_of_date for look-ahead-free backtests. It does not enumerate sibling alternatives or say when another fundamental/valuation tool would be preferred, but the use/no-use guidance 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 already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, and destructiveHint=falseasi. The description adds substantial behavioral context beyond that: valuation is LIVE and not strictly PIT, TTM rows are included alongside annual, is_calendar_aligned semantics are defined, null values carry a reason, and the CATEGORY_NOT_AVAILABLE envelope exposes available_categories. This is far 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 long but every sentence earns its place. It is front-loaded with the core purpose and data source, then flows through categories, caveats, usage guidance, and edge-case handling. No filler or redundancy; the density is justified by the tool's complexity.

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?

The description is thoroughly complete for a complex read-only tool. It covers availability caveats, PIT limitations, calendar alignment, lineage provenance, null handling, plan availability, and sibling differentiation. Combined with the output schema and annotations, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds further meaning: it explains the categories enum values (e.g., profitability sub-metrics), clarifies that omitting categories returns all available categories, details as_of_date PIT behavior (by accepted_at when present, else period_end), and identifies period_end_before as an alias of as_of_date. This enriches the schema without duplication.

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: 'Get pipeline-computed financial ratios from ratio.parquet.' It enumerates the served categories in detail and explicitly contrasts itself with get_valuation_metrics, 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?

It provides explicit routing guidance: use this instead of get_valuation_metrics when only ratios are needed, and use get_valuation_metrics when DCF/DDM is required. It also instructs on filtering to is_calendar_aligned rows for joins and using as_of_date for historical cuts, giving clear when-to-use context.

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, idempotentHint, and non-destructive behavior. The description adds substantial behavioral detail beyond that: the [-100, +100] scale, exact role weights, P=+1/S=-1 handling, neutralization of option exercises/grants/tax withholdings, and the precise cluster_flag trigger condition. This fully explains how the score is computed.

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 dense but every sentence earns its place: main result, scale, weighting logic, transaction direction mapping, neutralization rule, cluster definition, and access tier. The most important information is front-loaded, and there is no filler.

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

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

For a read-only composite scoring tool with an output schema, the description covers all essential behavioral and algorithmic details: scale, weights, neutralization, cluster detection, and access restriction. An agent can correctly select and invoke the tool without additional information.

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 adds contextual meaning for 'lookback' and 'cluster flag', but these largely echo the schema descriptions for lookback_days and cluster_window_days. No parameter gains significant new 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 opens with a specific verb and resource: a role-weighted insider sentiment score on a fixed [-100, +100] scale for a single issuer over a lookback window. It clearly distinguishes this composite scoring tool from raw-data siblings like get_insider_transactions by emphasizing 'composite' and 'score'.

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 to use the tool (when a composite, role-weighted insider sentiment score is needed for a single issuer) and adds the access restriction 'Institutional tier only.' However, it does not explicitly name alternatives or state when not to use it, leaving usage routing somewhat to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds meaningful behavioral context by stating the entitlement requirement (institutional tier only, with ENTITLEMENT_DENIED for lower tiers), which is an auth/access condition not present in annotations. It also clarifies the nature of the returned data (line items with insider details). No contradictions 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?

The description is three sentences with zero redundancy. It front-loads the core purpose, then lists filters and the key entitlement caveat. Every sentence earns its place, and no important information is buried or 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?

Given the rich input schema (all 8 parameters described, 100% coverage) and the existence of an output schema, the description covers the essential purpose, filters, and entitlement behavior. It does not explain error cases (e.g., invalid ticker) or rate limits, but those are minor given the structured schema. The description is complete enough for an agent to call 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 baseline is 3. The description mostly restates what the schema already says: filters by lookback, transaction code, insider role, and minimum share threshold, and it gives the same code meanings (P, S, A, etc.) already in the schema's enum descriptions. It adds little beyond the schema, so a 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 starts with a specific verb and resource: 'Form 3 / 4 / 5 / 144 line items for a US public company.' It enumerates the returned fields and filter dimensions, and the subject matter (insider transactions) clearly distinguishes it from sibling tools like get_insider_sentiment or get_institutional_holdings. An agent can immediately understand what this tool does and how it differs from 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?

The description provides clear context about the institutional tier restriction ('sample / sp500 / pro return ENTITLEMENT_DENIED') and describes the filtering capabilities, but it never explicitly says when to prefer this tool over sibling tools such as get_insider_sentiment or get_sec_filing_links. Usage is implied through purpose clarity rather than stated as explicit when/when-not guidance, so it does not meet the bar for a 4.

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

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

Annotations already cover readOnly, idempotent, non-destructive traits. The description adds meaningful behavioral context: the ~45-day reporting lag and staleness_warning threshold, plus the specific partition and tier. This goes beyond the annotations and helps the agent anticipate data freshness issues.

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 two sentences that pack relevant details (what, data source, lag) without fluff. It front-loads the main return and then adds caveats. It could be slightly tighter but is well-structured and efficient.

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?

The description explains the tool's purpose, data source, lag, and staleness, which covers key behavioral aspects. An output schema exists, so return details are handled there. It does not explain error conditions or how staleness_warning should be handled, but these are minor given the schema and annotations.

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% with detailed parameter descriptions for top_n, ticker, as_of_date, period_end, and lineage_detail. The description does not add significant meaning beyond the schema, only restating that period_end is optional (latest by default). Since the schema carries the burden, baseline 3 is appropriate.

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

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

The description clearly states the tool returns top-N institutional holders with specific aggregates (shares, market value, holder count, HHI) for a US public company, and specifies the data source (Form 13F-HR via by-issuer partition). This is a specific verb+resource and distinguishes it from siblings like get_top_holders or get_blockholders by emphasizing 'institutional tier only'.

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 provides context about the data source and reporting lag, implying it is for institutional holdings, but does not explicitly mention alternatives or when not to use it. It lacks a clear 'use X instead' or exclusion condition, so usage guidance is implied rather than explicit.

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 and idempotentHint=true, lowering the bar. The description adds valuable behavior beyond those flags: fuzzy-match behavior against entity.name, an explicit ambiguity-error condition, 'latest by default', QoQ delta classification, and an 'Institutional tier only' constraint. This is solid supplemental context.

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 with no filler. The primary behavior and default behavior are front-loaded, followed by the disambiguation guidance. Every sentence contributes actionable information for tool selection and invocation.

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 rich annotations, 100% schema parameter coverage, and presence of an output schema, the description is complete enough for an agent to invoke the tool correctly. It covers scope, defaults, delta behavior, disambiguation, and tier restriction; nothing essential for selecting and calling 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. The description adds meaningful parameter semantics beyond the schema by marking filer_cik as preferred, explaining filer_name as a fuzzy match against entity.name, and instructing the agent to disambiguate via CIK on multiple matches. This improves correct parameter selection.

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: 'Returns a 13F filer's full portfolio at a specific period_end', and uniquely distinguishes the tool by mentioning QoQ deltas and the CIK/name selection. This is enough for an agent to separate it from sibling tools like get_institutional_holdings or compare_periods 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?

The description gives clear selection guidance between filer_cik and filer_name, and notes the ambiguity error when multiple names match. However, it does not explicitly state when to prefer this tool over alternatives such as get_institutional_holdings or compare_periods, nor does it give exclusions; usage context is implied but not framed as alternative routing.

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 mark the tool read-only and idempotent, and the description adds valuable behavior beyond that: the returned brief may not be today's, absence of a brief is normal and returns `found: false` rather than an error, and access is restricted by tier. This gives an agent important expectations before invoking.

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, well-organized, and front-loaded with the core purpose, then parameter behavior, then edge-case semantics, then access tier. Every sentence adds useful information and there is no repetition of schema or annotation content.

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 simple tool with one optional parameter, an output schema, and read-only annotations, the description covers everything an agent needs: what the tool does, how to select the day, what absence means, and the tier restriction. Nothing essential 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 `day` well. The description adds nuance beyond the schema, especially that omitting `day` yields the most recent brief 'not necessarily today's,' and that a missing brief is represented as `found: false`. This is helpful but not a radical improvement over an already-good schema.

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

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

The description opens with a specific verb and resource: 'Read the caller's Morning Brief,' and clarifies what the brief contains (daily AI-generated market digest across watchlists and theses). This clearly distinguishes it from the many sibling get_* tools, even without naming an alternative.

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 for the optional `day` parameter: omit it to get the most recent brief, pass a specific YYYY-MM-DD to fetch that day. It also explains the not-an-error `found: false` case. It does not explicitly compare against alternative tools, but no sibling appears to serve the same purpose.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behavioral nuance: TTM ratio preference, point-in-time semantics driven by accepted_at vs period_end, zero look-ahead guarantees, the caveat that peer selection still uses current S&P 500 membership, and plan/sample-bucket behavior. This is exceptional transparency for a read-only 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 dense but every sentence earns its place: purpose, selection method, category list, TTM behavior, as_of_date semantics, PIT caveat, S&P membership caveat, and plan availability. Critical information is front-loaded and the caveats are clearly flagged with 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 tool with five parameters, complex point-in-time semantics, and an output schema, the description is thorough. It covers selection criteria, ratio categories, historical cutoff behavior, look-ahead safety, and a known limitation of peer selection. The output schema removes any need to describe return values.

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 each parameter already has a detailed description, so the baseline is 3. The tool description adds value by explaining PIT semantics for as_of_date, the data-driven pit_safe distinction, and the fact that TTM ratios are preferred when available, which goes beyond the schema's structural definitions.

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

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

The description opens with a specific verb and resource: 'Get ratio-based peer comparison for a company and its closest competitors.' It clearly distinguishes itself from sibling ratio tools by stating peers are selected via 2-digit SIC industry code and that results include the subject company alongside up to 10 peers for benchmarking.

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 provides clear context for when to use the tool — for direct peer benchmarking — and explains the as_of_date usage for historical comparisons. It does not explicitly name alternative sibling tools or state when not to use it, but the peer-comparison framing makes the intended use unambiguous.

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