Valuein — SEC EDGAR Fundamentals & Smart-Money Data

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

The description adds significant behavioral context beyond the annotations: it explains that the call uses the caller's credentials, not the proposer's, and details the return states (executed_now, tool_result, failed with reason). It also covers ownership leakage protection. No contradictions with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true, openWorldHint=true are all consistent).

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

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

The description is a single paragraph dense with essential information, front-loaded with the core purpose. Every sentence adds value, though it is slightly lengthy. It could be split for readability, but overall it is efficient and clear.

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 (approval + execution, idempotent, multi-tenant), the description is comprehensive. It covers all important behaviors: return values (executed_now, tool_result, reason), error handling, access restrictions, and output schema existence obviates the need for return value explanation.

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's explanation of the parameter ('Id of the staged action to approve, from stage_action or list_pending_approvals') matches the schema description and does not add new semantic information. Hence a score 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 clearly states the tool's purpose: 'Approve a staged action by id and RUN the underlying tool call it proposed'. It distinguishes itself from siblings like 'reject_staged_action' and 'stage_action', and provides specific details about the action (using caller's credentials, idempotence).

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 guidance on when to use and not to use: it explains idempotency ('an action already decided ... is NEVER re-executed'), race-safety, and the handling of underlying tool failures. It also notes that a failed underlying tool is a normal outcome, not a tool error, and mentions the access tier (sp500+).

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

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

Adds value beyond annotations by explaining that only pending tasks can be cancelled and that completed tasks cannot be undone. Reinforces idempotent and destructive hints with concrete examples. 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 plus a tier note, all essential. Front-loaded with the main action, followed by constraints and idempotency. 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?

Given the simple tool (one parameter, good annotations, output schema present), the description covers all necessary aspects: what it does, when to use, constraints (pending only), idempotency, and tier. Sufficient for an agent to use correctly.

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

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

Schema coverage is 100% and the schema already describes the parameter. The description adds minimal extra context by mentioning the id source ('from schedule_task or list_scheduled_tasks'), which is helpful but not essential.

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 cancels a pending scheduled task by id, specifying the verb 'Cancel' and the resource 'pending scheduled task'. It distinguishes from sibling tools like 'schedule_task' and 'list_scheduled_tasks' by mentioning where the id comes from.

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 states when to use: only for pending tasks, not for completed ones. Also notes idempotency (cancelling an already-cancelled task is a no-op) and a tier restriction (sp500+ sample rejected), providing clear guidance on usage 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?

The description adds significant context beyond annotations: auto-swap on inverted periods, point-in-time safety via as_of_date, and availability on all plans. This aligns with readOnlyHint and idempotentHint, providing full transparency.

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 concise (5 sentences), front-loaded with the core purpose, and every sentence adds essential information. No fluff 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 tool's complexity (comparison metrics, significance classification, period handling) and the presence of an output schema, the description covers all key aspects: purpose, usage, behavior, parameters, and output interpretation. It is fully complete.

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

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

Although schema coverage is 100%, the description adds valuable semantics: period ordering, auto-swap behavior, and the use of material_changes for triage. This gives the agent richer understanding beyond parameter names and schema 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 the tool compares core financial metrics across two fiscal periods side-by-side, with absolute and percentage changes and significance classification. This distinguishes it from sibling tools like get_financial_ratios or compute_dcf, which have different purposes.

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 on period format, ordering, and the material_changes count for triage. It implicitly distinguishes from sibling tools by focusing on period-over-period comparison, but does not explicitly state when not to use it or list alternatives.

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 behavioral traits beyond the annotations: it pulls net income, shares outstanding, and prices; the caller sets consideration mix, synergies, and interest rate; it is NOT a multi-year merger model. It also references result.caveats for excluded items. 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 dense and front-loaded with the acronym explanation, but includes all necessary information in a single paragraph. It is efficient with no wasted words, though minor structural improvements could enhance readability.

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

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

Given 11 parameters (4 required), an output schema, and high complexity, the description covers input, methodology, output, and limitations (caveats). There are no gaps for an AI agent to properly invoke the 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 coverage is 100%, so baseline is 3. The description adds meaning beyond the schema, e.g., explaining that cash_pct fraction determines stock consideration, that as_of_date is a point-in-time cutoff, and that price overrides replace the latest R2-derived 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 description clearly states the tool computes M&A accretion/dilution, a specific financial quick-screen. It uses precise terms like 'accretive' and 'dilutive' and differentiates from sibling tools such as compute_dcf and compute_lbo by noting it's a single pro-forma-year bridge.

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 explains it is for a sell-side/banker quick-screen, models a single year, and explicitly lists what it does NOT model (synergy ramp, integration costs, PPA amortization). However, it does not explicitly state when not to use it or name alternatives.

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 readOnlyHint and destructiveHint; the description adds substantial beyond: null value means degenerate model not zero, detailed 'fcf_source' parameter behavior, and echoed inputs for reproducibility. 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?

Well-structured with front-loaded purpose and output, followed by parameter details and usage guidance. Slightly verbose, as some details on 'fcf_source' appear in both description and schema, but overall appropriate for 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?

Given the tool's complexity (10 parameters, nested objects, output schema exists), the description covers the model, inputs, outputs, edge cases, parameter behavior, and interactions with other tools. It is fully sufficient for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, providing baseline of 3. The description adds significant value: explains formulas for FCF base and net debt, shares resolution fallback, and details the 'fcf_source' parameter with the 'trend' vs 'three_statement' distinction, all beyond the schema's brief 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 the tool computes a forward DCF valuation using a two-stage Gordon growth model and specifies the output: per-share intrinsic value and a sensitivity grid. It distinguishes from the sibling 'get_valuation_metrics' by noting that this tool lets the user drive assumptions, while the sibling provides pre-computed values.

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 advises when to use this tool ('when you want to drive the assumptions yourself') and when to use the alternative ('get_valuation_metrics'). Also clarifies that this tool does not persist a report, and directs the user to 'create_report' for that 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?

Annotations indicate readOnly, idempotent, and non-destructive behavior. The description adds significant behavioral context: EBITDA proxied by operating income, FCF-to-debt paydown sweep, IRR solving method, convergence flag, and caveats array. 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?

The description is detailed but every sentence adds value. It is front-loaded with the main purpose and then explains key behaviors. It could be slightly more concise, but the richness of information justifies the length.

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

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

Given the tool's complexity (13 parameters, linked three-statement model, multiple caveats), the description thoroughly covers inputs, outputs, assumptions (e.g., EBITDA proxy), and edge cases (convergence flag). The presence of an output schema further enhances completeness.

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 has 100% description coverage. The tool description adds critical meaning beyond the schema by explaining how parameters like leverage_multiple, entry_multiple, and minimum_cash are used in formulas (e.g., entry_debt = leverage_multiple * EBITDA, sponsor_equity = entry_enterprise_value + minimum_cash - entry_debt).

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 computes LBO returns (IRR and MOIC) and provides a detailed explanation of the analysis. It distinguishes itself from sibling tools like project_three_statement by referencing the same engine but with different focus.

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 explains the inputs needed and the workflow (pro-forma balance sheet, three-statement projection). It implicitly sets expectations for when to use this tool over similar ones like project_three_statement, but does not explicitly mention when not 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?

Annotations indicate idempotentHint=true and non-destructive. Description adds that generation is synchronous, persisted under caller's authorship, idempotency key provides at-most-once semantics, and output includes markdown, JSON, and citation chains. No contradictions; adds useful context beyond 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?

Description is well-structured with bullet points for subtypes, front-loaded with main purpose, and each sentence adds value. The 'Tier: sample tier rejected' line is slightly unclear but not detrimental. Concise enough for a tool with two complex subtypes.

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 (6 params, nested objects, output schema exists), the description covers subtypes, output format, and idempotency. It lacks some error handling details but is sufficiently complete for an agent to accurately select and invoke the 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 coverage is 100%, so baseline is 3. Description adds value by grouping parameters per subtype, explaining conditional requirements (e.g., params only for reverse_dcf), and noting that idempotency_key ensures idempotency. This enhances understanding beyond the schema alone.

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 clearly states the tool creates a research report and persists it under the caller's authorship. It distinguishes two subtypes (reverse_dcf and thesis) with specific behaviors, and the purpose is distinct from sibling tools like get_report, update_report, or save_thesis.

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 explains when to use each subtype: reverse_dcf requires ticker and params, thesis requires thesis_id from save_thesis. It notes that thesis reports are frozen snapshots that do not update with edits, implying when to generate a new one. Explicit mention of alternatives could be stronger, but it provides 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?

With only neutral annotation flags (readOnlyHint=false, destructiveHint=false), the description carries the full burden and excels. It discloses that non-live trigger types are 'saved as enabled:true and simply never fires', introduces the authoritative `trigger_wiring_status` field, and clarifies the anti-loop/anti-complexity rationale behind condition_expr limitations. It even acknowledges its own potential staleness, which is a high degree of transparency.

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

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

The description is a dense single paragraph, but every sentence earns its place: it covers purpose, type inventories, live-status caveats, condition_expr syntax, a testing pointer, and tier restriction. It is front-loaded with the core action. Slightly less organized than a bulleted structure, but given the complexity, the length is justified and there is 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?

For a tool with a complex discriminated-union schema, the description covers all critical operational caveats: the non-wired triggers, the need to check trigger_wiring_status, the condition_expr limitation, the test_rule recommendation, and the tier gate. Since an output schema exists, the description wisely points to the returned rule's trigger_wiring_status field rather than explaining all return fields. No important context is missing for an agent to invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful value beyond the schema. It specifies the exact operators for condition_expr (gt/gte/lt/lte/eq), explicitly forbids AND/OR/loops, and highlights which trigger types are live versus not_yet_wired, which is critical for choosing among trigger variants. While the schema already documents each variant well, the description's high-level synthesis earns extra points.

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: 'Persist a trigger -> action rule and register it with the evaluator.' It then enumerates the 7 trigger types and 6 action types, making the tool's scope unambiguous and clearly distinguishing it from sibling tools like create_signal and test_rule.

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 and when-not-to-use guidance. It warns that price_threshold and manual triggers have no live event source and 'simply never fires', and it explicitly directs the agent to 'Use test_rule immediately after creating to verify it fires as expected WITHOUT spending a real dispatch.' It also provides a tier restriction ('Tier: sp500+') and a fallback for complex conditions ('compose multiple rules').

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 behavioral details beyond the minimal annotations: webhook delivery is HMAC-SHA256-signed, slack must be a hooks.slack.com URL, agent_run delivers to inbox, and Pro+ requires specific condition types. The crate creation timeline (cron every 5 minutes) and the tip to test before relying on cron also add transparency. It does not contradict 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 front-loads the core purpose and uses scannable bullets for condition shapes and delivery channels. At roughly 180 words, it is longer than minimal, but the complexity of the tool justifies the detail; every sentence serves a purpose (conditions, channels, cron cadence, testing advice) with no filler.

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

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

The description covers the essential operational context: all condition shapes (except watchlist_restatement), all channel types, Pro+ restrictions, cron frequency, and the test_signal relationship. The missing sixth condition type is a notable gap, but the output schema and the variant's own description in the schema fill that void, so the overall context is strong.

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% (all three parameters have descriptions), so the baseline is 3. The description adds helpful examples like 'interest_coverage < 1.5' and explains the webhook HMAC secret, but it incorrectly states 'Five condition shapes' while the schema actually supports six (missing watchlist_restatement). This omission misleads an agent about the available condition variants, undermining the 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 opening sentence, 'Persist a signal and register it with the firing pipeline,' clearly states the verb and resource. The description then enumerates condition shapes and delivery channels, distinguishing it from sibling tools like delete_signal, test_signal, and list_signals. It also references test_signal as a verification step, reinforcing its unique role.

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 operational context: it mentions the 5-minute cron evaluator, Pro+ gating for certain condition types, and advises using test_signal before relying on the cron to verify channel wiring. However, it does not explicitly state when not to use this tool (e.g., alternatives for one-off alerts vs standing signals), so it falls short of explicit when-not/alternatives 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 significantly adds to the annotations by explaining that system agents are rejected with a clear message, idempotent deletion of unknown IDs returns NOT_FOUND, and the tier restriction (sp500+). It also tells users how to identify system agents via is_system on get_agent/list_agents. This is rich behavioral context beyond the destructive/idempotent 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 compact and front-loaded: first sentence states the core action, the second adds exceptions, and the third covers idempotency and tiering. Every sentence carries unique information without 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?

For a simple delete operation with one parameter and an output schema, the description covers purpose, ownership, system-agent exclusions, idempotent behavior, and access tiering. It is fully self-contained and leaves no significant gaps for an agent to invoke the tool correctly.

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

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

The schema already fully documents agent_id (identifier of the agent to delete), so the description adds no new parameter-specific syntax. It does reinforce that the ID refers to a caller-owned standing agent, but this is more of a behavior note than parameter semantics. Baseline 3 applies due to 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?

The description uses a specific verb ('Delete') and resource ('standing agents by id'), clearly distinguishing it from sibling tools like delete_agent_memory and delete_alert. It also specifies ownership ('caller's own') and agent type, making the tool's scope unambiguous.

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

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

The description provides clear context on when to use this tool (for deleting caller-owned agents) and when not to (system agents, listed as rejected). It references get_agent/list_agents for checking is_system and mentions the tier restriction. However, it does not explicitly name alternatives for other deletion scenarios, though the context is strong.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=true. Description adds valuable details: idempotent behavior (deleted:false for missing key), scope limitation (only your memory, not theses/claims), and the re-reading of entries into context. 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?

Description is slightly long but every sentence carries essential information: purpose, usage guidelines, idempotency, scope, and access tier. Well organized and front-loaded, though could be trimmed slightly without losing clarity.

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 single parameter, existence of output schema, and comprehensive annotations, the description provides everything needed: behavior, side effects, error handling, and limitations. No gaps remain for effective agent usage.

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?

Only one parameter 'key' with complete schema coverage (100%). Description adds value beyond schema by explaining how to discover keys via get_agent_memory. Baseline 3 for full coverage, extra point for actionable guidance.

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 specific verb 'Forget' and resource 'durable memory entry by key', clearly distinguishing it from siblings like delete_claim and set_agent_memory. It also clarifies the scope ('your memory note only'), making purpose unambiguous.

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

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

Explicitly states when to use: 'when a note you stored is now wrong, superseded, or was only ever scratch'. Explains consequences of stale entries and mentions idempotency and the 200-entry cap. Provides clear context for choosing this tool over alternatives.

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=true and idempotentHint=true. Description adds value by detailing the idempotent behavior (returning deleted=false) and the effect on report regeneration. Also mentions tier restrictions.

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, no redundancy. Front-loaded with core action, followed by key behaviors. 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?

Covers all essential aspects: action, idempotency, side effects, tier info. Output schema exists to cover return structure. No gaps.

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

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

Schema coverage is 100%, baseline 3. Description adds beyond schema by specifying the fact_id source: 'as returned by save_citation_override or list_citation_overrides', which aids correct 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?

Clearly states action 'Remove a user-authored citation correction' and resource 'by fact_id'. Differentiates from siblings like save_citation_override and list_citation_overrides.

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 context on idempotency and side effects (reversion to canonical value). Implicitly tells when to use (to delete an override), but no explicit when-not or alternatives beyond listing 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?

Beyond annotations (destructiveHint: true, idempotentHint: true), the description reveals key traits: soft-delete (archival, not erasure), preservation of score history for audit, and idempotency. These details add significant value beyond the structured fields.

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

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

The description is extremely concise: two sentences and a tier note. Every sentence provides essential information without redundancy. It is front-loaded with the primary purpose.

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 simple parameter set, high annotation coverage, and presence of an output schema, the description fully covers purpose, behavioral traits, idempotency, and tier restrictions. No gaps are apparent.

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 has 100% coverage with a clear description for 'claim_id' ('Id of the claim to archive.'). The description does not add additional parameter semantics beyond the schema, but given full schema coverage, a score 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 clearly states 'Soft-delete a claim by id', specifying the verb and resource. It distinguishes from sibling delete tools (e.g., delete_alert) by specifying claim. The explanation of archival behavior further clarifies the scope.

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

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

The description mentions idempotency and tier restrictions ('all paid + free tiers (sample rejected)'). While it doesn't explicitly state when not to use this tool vs alternatives, the context of sibling tools makes the purpose clear. Some guidance on when to use other delete tools would be beneficial, but the current info is adequate.

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 significant behavioral context beyond annotations: it specifies the soft-delete nature, audit window (90 days), ownership requirement, and idempotency (deleting already-delisted succeeds). No contradiction with annotations (destructiveHint=true, idempotentHint=true are confirmed).

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 with dense information, front-loading the key effect. However, the inclusion of 'Sample tier rejected' is somewhat confusing and could be removed or explained, slightly reducing clarity.

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 (soft delete with audit window), the description covers ownership, state changes, preservation, and idempotency. Output schema exists but not shown. Minor gap: does not explain error cases or the 'Sample tier rejected' reference. Overall very complete.

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 a clear description for report_id ('Id from create_report or list_my_reports'). The description adds no further parameter details beyond the schema, meeting the baseline. No extra 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 clearly states it performs a soft delete, specifying exact state changes (status to delisted, visibility to private) and distinguishing from a hard delete by noting preservation of row and R2 artifact for 90 days. It also mentions idempotency, which differentiates it from other delete 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 clearly states that the tool soft-deletes a report owned by the caller and that it is not a hard delete, providing context for when to use it (temporary removal). However, it does not explicitly mention alternatives like restore_deleted or when not to use it, so it misses 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?

Describes side effects (removal from catalog and scan index, immediate stop firing) and idempotency, adding value beyond annotations (destructiveHint, idempotentHint). 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 sentences, front-loaded with action and resource, each sentence provides unique value (action, effect, usage advice). No 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?

Covers purpose, behavioral details, parameter source, idempotency, and authorization tier. Simple tool but fully specified 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?

Single parameter with full schema coverage; description adds crucial context that rule_id comes from create_rule/list_rules, aiding agent in sourcing the ID.

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

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

Explicitly states 'Delete a rule by id', specifies resource (rule), and references sibling tools (create_rule/list_rules) to distinguish inputs.

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 guidance: use for deletion, mentions idempotency, and instructs to delete then create_rule for modifications. Also notes tier restriction.

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 key behaviors beyond annotations: soft-delete (not hard delete), removal from cron evaluator index, and that it stops firing. This adds meaningful context to the destructiveHint and idempotentHint 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 every sentence contributing value: action, effect, immutability workflow, idempotency, and access scope. 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?

For a single-parameter delete tool, the description is thorough: it explains the soft-delete behavior, idempotency, immutability constraint, and id source. With an output schema available, no further return-value detail is necessary.

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 a clear description for signal_id. The tool description adds provenance guidance ('from create_signal/list_signals'), reinforcing where to obtain the id, which goes slightly 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 clearly states the tool performs a soft-delete on a signal by id, explaining the effect ('status flips to deleted', 'removed from cron evaluator index'). It distinguishes from other delete tools by specifying the resource and the soft-delete mechanism.

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 on when to use the tool: signals are immutable, so to change one you must delete then create. Also notes the id source (create_signal/list_signals) and access tier (sp500+), giving clear context and exclusion.

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 idempotent and destructive. The description adds valuable context: soft-delete semantics, audit trail retention, idempotency guarantee, and lack of hard-delete support. 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?

Four sentences, each adding value. Front-loaded with core action and key traits (soft-delete, idempotent). No fluff, concise and well-organized.

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 single parameter, presence of output schema, and rich annotations, the description covers all necessary behavioral details (audit, idempotency, claim linkage, tier) completely.

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?

Only one parameter with 100% schema coverage. Schema already describes thesis_id as returned by save_thesis/list_theses. Description doesn't add meaning beyond schema, so baseline 3.

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

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

The description clearly states that the tool soft-deletes a thesis by flipping status to 'archived'. It distinguishes from hard-delete and from deleting linked claims, which is precise and differentiates from sibling tools like delete_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?

Explicitly states when to use (soft-delete a thesis) and when not to (use delete_claim for claims). Also mentions tier restrictions ('paid + free (sample rejected)'), providing clear context for invocation.

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 value beyond annotations by explaining the idempotent behavior (returning false for missing/expired documents instead of error) and the TTL constraint. Annotations already indicate destructive and idempotent, but the description elaborates on the specific failure mode.

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 are highly efficient, conveying the core action, constraint, and edge case behavior without redundancy or filler. Every sentence 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?

Given the simple parameter set, annotations, and existence of an output schema, the description covers the key behavioral aspects (TTL, idempotency) sufficiently. Minor gap: no mention of authorization or irreversibility, but destructive hint covers safety.

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 the upload_id parameter. The description does not add additional semantics for the parameter beyond the TTL context, which is about the document rather than the parameter itself. 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 clearly states the action (delete) and resource (uploaded document) with a specific constraint (before 24h TTL). It distinguishes itself from sibling delete tools by specifying the resource type and the TTL context.

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 for documents within their TTL but does not provide explicit guidance on when not to use this tool or compare it to alternatives like delete_report. The edge case behavior is noted but not the decision criteria.

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

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

Adds significant context beyond annotations: explains soft-delete mechanism, still readable via list_watchlists with status=all/archived, name freed for reuse, idempotency, and tier restriction. 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?

Four sentences, no redundant information. Front-loaded with action and key constraints. Every sentence provides essential behavioral or usage 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?

Given low complexity (1 parameter, soft-delete), the description fully covers behavior, side effects, and usage context. Output schema exists but is not needed for completeness.

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 has 100% description coverage, so baseline is 3. The description adds 'case-insensitive, 1–80 chars' and 'frees the name for reuse', which adds meaningful context beyond the schema's parameter 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 tool soft-deletes a watchlist by name, distinguishing it from save_watchlist (create/update) and list_watchlists (read). The verb 'soft-delete' and resource 'watchlist' are specific.

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 mentions using name instead of id, idempotent behavior, and tier restriction. Could be improved by stating when to avoid this tool (e.g., for permanent deletion), but it is 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description explains that the schema is embedded in the manifest and available on all plans, adding value about the tool's behavior and availability. 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?

The description is two sentences with no wasted words. It efficiently conveys purpose, usage guidance, and a key behavioral 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?

Given the annotations, input schema (1 optional parameter, 100% coverage), and existence of an output schema, the description is complete. It explains what to expect and when to use it.

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

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

Schema coverage is 100% and the parameter has a description. The tool description adds context by giving example table names ('fact', 'entity', 'references') and clarifying that omitting the parameter returns full schema, which enriches the schema information.

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

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

The description clearly states it returns the Parquet schema for all tables, including column details and keys. It also explicitly distinguishes the tool's purpose as a data model exploration tool before querying, which differentiates it from sibling tools that perform data analysis or actions.

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 advises using this tool to understand the data model before querying with other tools, and notes that no data reads are required. While it doesn't explicitly mention when not to use it, the context is clear and helpful.

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 significant context beyond the annotations: it explains the soft-delete mechanism ('sets `dismissed_at`'), that the row remains queryable for audit ('list_signal_inbox(include_dismissed=true)'), and that it is idempotent. It also clarifies the input is not a signal id. These details disclose the behavioral effects and constraints, going well 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 a tight, front-loaded sentence that covers the action, input source, effect, audit behavior, idempotence, and tier. No word is wasted; every 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 mutation tool with an output schema, the description is complete. It explains the purpose, the critical input distinction, the side effect, the audit trail behavior, idempotence, and access tier. No important context is missing.

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

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

Schema coverage is 100% and the schema already describes inbox_id as 'Identifier of the inbox item to dismiss (soft-delete), as returned by list_signal_inbox.' The description adds further disambiguation with 'not a signal id', which reinforces but adds marginal value. This exceeds the baseline of 3 for high schema coverage.

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

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

The description clearly specifies the action: 'Soft-delete a single inbox item by its id', with the resource (inbox item) and the source (from list_signal_inbox). It also explicitly distinguishes from a signal id, preventing confusion with sibling tools. This is a specific verb+resource+scope.

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

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

The description provides clear context: it is for soft-deleting an inbox item, is idempotent, and is restricted to Tier sp500+. It mentions the audit use case via include_dismissed=true. However, it does not explicitly contrast with alternatives like mark_inbox_read or restore_deleted, so it lacks explicit 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 mark the tool as read-only and idempotent. The description adds further transparency by confirming deterministic behavior, explaining the partial result flag, detailing the output (narrative with severity and citations), and disclosing 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?

The description is concise and well-structured, front-loading the primary purpose and then providing supplementary details in a logical order. Every sentence adds value without 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 existence of an output schema (not shown), the description adequately covers the return value nature and usage context. It could be slightly more complete by mentioning the specific financial statement items used, but it remains informative for agent decision-making.

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

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

With 100% schema coverage, the parameter description in the schema is sufficient. The tool description does not add additional semantic value beyond what is already in the schema, meeting the baseline expectation.

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 computes deterministic forensic-accounting scores for a single ticker, listing specific metrics (partial Beneish M-Score, Sloan accruals, solvency snapshot). It distinguishes from siblings by being a specialized forensic audit, with no other tool offering this combination.

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 by noting it is used by the 'forensic_earnings_brief' SOP and explains the limitation of partial computation. However, it does not explicitly state when not to use the tool or suggest alternatives, leaving some guidance gaps.

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 that ratios are rendered as-supplied without re-derivation, resulting in an 'unverified' watermark via verification.status. This goes beyond the annotations (which only indicate non-destructive, non-idempotent behavior) by explaining the server's trust model and output implications.

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 well-structured with a clear front-loaded purpose, technical details, and a pairing note. It is fairly concise for the amount of information, though the server-trust section could be slightly tightened. Still, every sentence serves a purpose.

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

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

Given the complexity (array parameter with many properties, output schema exists), the description covers output structure (sheets, named table, summary deltas) and response details (verification.status). It also addresses usage context and caveats, making it fully informative for an agent to decide 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?

Schema coverage is 100%, so the description adds only marginal value over the schema. It mentions that notes appear on the Summary sheet and subject_company_name falls back to ticker, but these are minor clarifications. No deeper parameter semantics are added beyond what the schema already 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?

The description clearly states the tool renders peer comparables into an Excel workbook with Comps and Summary sheets. It mentions key features like the named table and subject-row highlight, distinguishing it from generic file generation tools. However, it does not explicitly differentiate from sibling tools like generate_dcf_xlsx or generate_lbo_xlsx, aside from the specific document type.

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: pairing with get_peer_comparables for authoritative numbers, sourcing ratios from specific tools, and noting the pro+ tier requirement. Also gives a clear warning about the watermark for caller-supplied figures, telling the agent when to use this vs. data-fetching 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?

Discloses server re-derivation, correction banner, verification status, and presigned URL. Annotations are minimal (readOnlyHint=false), so description carries full burden and does so comprehensively.

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?

Well-structured with front-loaded purpose, then details. Slightly long but every sentence adds value; no tautology.

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

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

Covers workbook contents, trust mechanism, output format (presigned URL), and partner tool. Missing output schema is compensated by detailed description of return value.

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. Description adds context for dcf_result (typically from compute_dcf) and mentions output nature, enhancing parameter understanding beyond 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 renders a DCF result into an Excel workbook with specific sheets (Summary, Sensitivity heatmap, Inputs). It distinguishes from sibling tools like generate_comps_xlsx and generate_lbo_xlsx by focusing on 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?

Explicitly pairs with compute_dcf for a typical flow, explaining how to pass the structured result. While it doesn't list when not to use, the context is clear and includes trust/verification details.

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 a critical behavioral trait: the workbook is re-derived in-worker from inputs_echo, with a correction banner if figures disagree. This adds significant context beyond the annotations, which only indicate non-readonly and non-destructive, but do not cover the re-derivation and verification 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 well-structured: it starts with the core purpose, then details the server-trust behavior, then the typical pairing flow. Every sentence adds value, though the tier mention is less essential. It is appropriately sized for the 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 explains the output (download URL), the behavioral correction, and typical usage. Given the existence of an output schema, it doesn't need to detail return fields. It covers all necessary context for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% and parameters are well-described. The description adds context that lbo_result is typically from compute_lbo and that company_name is optional. It also hints at the verification.status field, which is not in the schema, adding extra semantic 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 clearly states the tool's purpose: 'Render an LBO result into a professional Excel workbook' with specific sheets (Summary, Projection, Inputs). It distinguishes itself from sibling tools like generate_comps_xlsx and generate_dcf_xlsx by focusing on LBO 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 explicitly pairs this tool with compute_lbo, describing the typical flow: 'call compute_lbo, then pass the result to generate_lbo_xlsx'. This provides clear when-to-use guidance and references a specific sibling tool, making it easy for the agent to decide.

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, so description carries full burden. It discloses unverified rendering ('figures supplied by caller, not verified by Valuein' watermark), no charts in v1, and repeated footer details. These are meaningful behavioral traits.

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?

Description is long but well-structured with clear sections (masthead, body, footer, trust, workflow). Every sentence adds relevant detail; front-loads the core action.

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

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

Covers output type, workflow, trust/verification model, tier, and integration with sibling tools. Output schema handles return specifics. No significant gaps.

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 covers 100% of params, so baseline is 3. Description adds value by explaining that sections/citations share create_report's shape and describing how params map to document sections (masthead, snapshot table, citations table).

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 'Render a structured research brief into a professionally-styled Word document' – a specific verb and resource. It distinguishes from siblings by explicitly noting 'No embedded charts in v1; pair with generate_dcf_xlsx / generate_comps_xlsx for visuals.'

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?

Clearly states typical flow: 'create_report → generate_research_brief_docx' and names alternatives for visuals. Also instructs to 'Resolve each citation via verify_fact_lineage before publishing,' providing prerequisite 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 annotations (readOnlyHint=true, destructiveHint=false), the description discloses critical behavior: returns found:false for unknown ids or other customers' ids without a distinguishing signal, and mentions the access tier restriction (sp500+, sample rejected). This is valuable context not captured in 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 convey a complete picture: what the tool does, how ids are sourced, the not-found behavior, the security posture, and access tier. Every sentence earns its place without 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?

The description covers all essential non-schema aspects: ownership, unknown-id handling, absence of distinguishing signal, and tier restriction. An output schema exists, so return structure need not be described. No gaps remain for a well-scoped read-only 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 coverage is 100%, and the schema already describes agent_id as 'Agent identifier, from save_agent or list_agents.' The tool description repeats this source info but adds no additional parameter semantics, meeting the baseline for high schema coverage.

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

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

The description uses a specific verb ('Fetch') and resource ('full detail for one of the caller's own standing agents by id'), clearly distinguishing from siblings like list_agents (listing vs full detail) and get_agent_run (different agent type). It also clarifies ownership scope ('caller's own').

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 on when to use: fetching a single agent's full detail by id, with source ids from save_agent/list_agents. It does not explicitly name alternatives to avoid, but the instruction to use ids from save_agent/list_agents implies the flow and differentiates from listing operations.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that an absent key returns an empty list (never error) and that retrieval is newest-first, adding value beyond 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, front-loaded with core purpose, followed by actionable guidance and behavioral clarification. 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?

Given the presence of an output schema (not shown but known), the description adequately covers interpretation of results (empty list for absent key) and provides tier info. Complete for a simple read tool with rich 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 description of key parameter. The description adds usage semantics: omitting key reads all, newest-first, and passing a key fetches one entry. This enhances the schema's purely structural definition.

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 retrieves durable memory for a user, specifying two modes: omit key to read everything newest-first, or pass a specific key for one entry. It distinguishes from siblings like set_agent_memory and delete_agent_memory.

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 recommends omitting key at the start of a task to re-ground, and provides context for both modes. Does not explicitly state when not to use, but the use case 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), description adds that unknown ids and others' ids both return found:false by design, and lists returned fields (status, goal, tickers, etc.). 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?

Description is four sentences, well-organized: main purpose first, then details on scope, return info, and design note. Slightly verbose but 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?

For a simple read tool with one parameter and existing output schema, description covers input source, returned fields, error behavior, and access tier. No significant gaps.

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?

Only one parameter (run_id) with 100% schema coverage. Description in tool repeats schema's description ('from list_agent_runs'). Adds no new constraint beyond schema, 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?

Clearly states 'Fetch full detail for one of the caller's own standing-agent runs by id', specifying verb (fetch), resource (agent runs), and source of id. Distinguishes from sibling 'list_agent_runs' by focusing on single-run detail.

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?

Tells agent id comes from list_agent_runs and explains behavior for unknown/inaccessible ids ('returns found: false'). Mentions tier restriction. Doesn't explicitly say when not to use or list alternatives, but context is clear and helpful.

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?

Given that annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description goes beyond by detailing the fields returned (percent_owned, voting splits, going_active) and behavior of parameters like lookback_days. 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 four sentences long, front-loading the core purpose, then explaining key features and usage tips. Every sentence serves a purpose with no redundancy or filler.

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

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

With an output schema present and comprehensive annotations, the description still adds necessary context: the institutional tier restriction, the meaning of the going_active flag, and how to control deduplication and grouping. It is complete for this complex 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?

While the input schema has 100% coverage, the description adds significant value by explaining the going_active flag, the effect of latest_only (dedup to most recent per filer), and what collapse_groups does. This clarifies the semantics beyond the schema's parameter 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 explicitly states that the tool returns SC 13D/13G blockholder disclosures for US public companies, with a specific focus on the going_active flag. It clearly distinguishes from sibling tools like get_insider_transactions or get_institutional_holdings by specializing in 5%+ stake filings.

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

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

The description mentions that the tool is 'Institutional tier only' and provides usage tips for latest_only and collapse_groups parameters. It highlights the going_active flag as the key activist signal, implying when to use this tool. However, it lacks explicit exclusions or comparisons to 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 declare readOnlyHint and idempotentHint. The description adds detailed behavioral context: data sourced from SEC 10-K filings, PIT-safe via as_of_date, explains R&D inclusion (informational, excluded from total to preserve cash-flow identity), and describes pre-computed flags (buybacks_exceed_fcf, total_returns_exceed_fcf, debt_funded_distribution). 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?

The description is front-loaded with the core purpose and key features. While it is long (nearly 300 words), each section contributes value: use case list, R&D nuance, and flag details. No fluff, but slight verbosity prevents a top score.

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 three parameters, an output schema, and annotations providing safety hints, the description covers all necessary aspects: purpose, usage, data source, behavioral details, parameter context, and output shape (via flags). It is fully complete and leaves no major gaps.

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 covers all three parameters with descriptions (100% coverage). The description adds meaning by explaining the lookback_years default rationale ('full capital allocation cycle'), the as_of_date point-in-time safety, and how ticker identifies the company. It goes beyond baseline but not extensively.

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 provides a multi-year capital allocation breakdown across six categories (capex, R&D, M&A, dividends, buybacks, debt) with pre-computed ratios and over-distribution flags. It distinguishes itself from sibling tools like get_financial_ratios by focusing specifically on cash deployment and management decisions.

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 user queries that should invoke this tool, such as 'how does a company allocate capital', 'what's the buyback-vs-dividend mix', 'is the company over-distributing', and 'where does the money go' questions. It provides clear when-to-use guidance without needing alternative tool references.

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 signal readOnlyHint and idempotentHint. The description adds behavioral context by specifying that it returns 'ids of theses it supports/refutes' and 'full append-only score history', which explains the nature of the returned data.

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 plus a tier line, with no wasted words. The core function is stated first, followed by usage guidance, making it efficient and front-loaded.

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 read tool with one parameter and an output schema, the description covers what it returns and when to use it. No additional context is needed given the tool's low complexity.

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 provides a clear description for the only parameter (claim_id). The description does not add further parameter details but explains what the tool returns, which indirectly adds context. Schema coverage is 100%, 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 ('Fetch') and clearly identifies the resource ('claim by id'). It also lists what additional data is returned (thesis ids, score history), distinguishing it from sibling tools like list_claims or delete_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 states when to use the tool ('to inspect a claim's evidence, current status, and how its outcome has evolved') and includes tier restrictions. However, it does not explicitly mention alternatives or when not 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?

Beyond the readOnly/idempotent annotations, the description discloses that results are raw as-reported line items only, sourced from 10-K/10-Q filings, and point-in-time with no look-ahead bias. It also reveals provenance behavior, confidence-based suppression, and plan-gating handling, all of which add meaningful behavioral context beyond 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 dense and front-loaded with the main purpose, followed by important caveats and alternative routing. It is longer than a minimal description, but given 9 parameters and the need to prevent manual derivation, most sentences earn their place; a small amount of repetition around 'raw only' and 'never substitute your own arithmetic' keeps it from a 5.

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

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

For a 9-parameter tool with an output schema, the description covers the core semantics, data source, point-in-time behavior, raw-only contract, and sibling-tool routing. The output schema handles return-value details, so the description is fully sufficient 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?

All nine parameters already have rich schema descriptions (100% coverage), so the baseline is 3. The description references as_of_date and mentions 10-K/10-Q sourcing, but it does not materially add semantics beyond what the schema already 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?

The description opens with a specific verb and resource: 'Retrieve standardized SEC EDGAR fundamental financial metrics for a US public company.' It enumerates the exact metrics returned and explicitly distinguishes itself from sibling tools such as get_valuation_metrics, get_financial_ratios, and compute_dcf by clarifying that it serves 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?

The description gives explicit when-to-use guidance by naming alternatives: derived metrics come from get_valuation_metrics, the ratio table from get_financial_ratios, and intrinsic value from compute_dcf. It also instructs the agent to say so and offer the upgrade if those are plan-gated, rather than substituting manual arithmetic.

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 and idempotentHint, so the description's job is to add details. It discloses the 15-minute URL lifetime, HTTP range read support, and security scoping (signed link, cannot list bucket). These add value beyond annotations, though missing details like error handling or rate limits.

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

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

The description is a single dense paragraph front-loading the main purpose. It contains no filler, but could be slightly more structured (e.g., separate sentences for security vs dataset listing). Still efficient given the amount of 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?

Given the tool's complexity (2 params, 6 dataset types, output schema exists), the description covers all key aspects: return value, usage patterns, constraints, dataset descriptions, and security. The presence of an output schema means return format need not be detailed 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% with descriptions for both parameters. The description adds context by explaining each dataset type (e.g., 'fact requires ticker', 'ratio all computed ratios'), which provides meaning beyond the schema's brief 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 the tool returns a short-lived download URL for a bulk Parquet object, specifying the verb 'returns' and resource. It distinguishes from sibling tools by highlighting high-throughput streaming capability beyond MCP context window, and mentions specific use cases (Python/DuckDB/Polars).

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 this tool ('high-throughput computation that exceeds the MCP context window') and explains dataset scoping (fact requires ticker, others full-universe). However, it does not explicitly mention alternatives or when not to use it, which prevents a perfect score.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds that the tool is point-in-time safe for backtesting and explains that eps_trend_est is a deterministic estimate from SEC filings, not consensus. This provides behavioral context beyond 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 a single paragraph that is information-dense but well-structured, front-loading the purpose and then detailing nuances. While slightly long, every sentence adds value, though bullet points could improve scanability.

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 (3 parameters, output schema exists), the description adequately covers usage context, including point-in-time safety and the nature of the estimate. It does not explain the output schema, but that is likely covered elsewhere.

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%. The description adds value by explaining the meaning of eps_trend_est and eps_surprise_pct, which are not fully defined in parameter descriptions. It also clarifies the default and behavior of limit, and the purpose of as_of_date for backtesting.

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 and a model-derived earnings-trend signal for a company by fiscal period. It specifies key fields (actual EPS, eps_trend_est, eps_surprise_pct, revenue, yoy growth), and distinguishes itself from Wall Street consensus tools, adding clarity.

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 advises using the tool to track earnings/revenue trajectory and momentum, not to claim consensus beats or misses. It also explains the nature of eps_trend_est and provides backtesting guidance with as_of_date. Though it doesn't list alternatives, it gives clear contextual usage 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: explains that each ratio entry contains value, unit, category, reason, and that missing values have a reason (not zero). It details that valuation is live and not strictly PIT, explains the as_of_date PIT logic, and mentions lineage provenance. 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 relatively long but front-loaded with the core purpose and key differentiator. Every sentence serves a purpose, but some details (e.g., is_calendar_aligned, specific join advice) could be condensed without losing clarity. Overall well-structured.

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

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

Given the complexity (6 parameters, 100% schema coverage, output schema exists), the description thoroughly explains the return format (value, unit, category, reason), missing data handling, lineage provenance, and usage nuances like live vs. PIT data. It covers all necessary context for correct tool invocation.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds extra context: for categories, it explains valuation is LIVE and ticker-specific; for as_of_date, it details PIT behavior; for period_end_before, it notes it's an alias. This adds value beyond the schema, though the schema already captures the basic meaning.

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 it retrieves pipeline-computed financial ratios from a specific data source and lists all served categories. It explicitly distinguishes itself from the sibling tool get_valuation_metrics by specifying when to use each, providing strong 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?

Explicit guidance is given on when to use this tool versus get_valuation_metrics. It also advises omitting categories to get all available data and how to handle CategoryNotAvailable envelopes. Instructions for is_calendar_aligned when joining ratio results are provided, making usage clear.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint, already indicating safe, idempotent behavior. The description adds significant context: the scale range, role weights, transaction type handling (P=+1, S=-1, neutralized items), and cluster flag logic. 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?

The description is concise and well-structured, covering key aspects in a few sentences. It avoids unnecessary words but could be slightly more streamlined. Still highly effective.

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 presence of an output schema, the description does not need to detail return values. It explains the scale, weights, transaction handling, cluster flag, and the required tier. It covers major functional aspects, though edge cases (e.g., no transactions) are not mentioned.

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 all parameters described. The description does not add parameter-specific details beyond the schema; it explains the overall algorithm but not syntax or constraints. 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 computes a role-weighted insider sentiment score on a fixed scale for a single issuer over a lookback window. It distinguishes from sibling like get_insider_transactions by focusing on a composite sentiment score rather than raw transaction data.

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?

No explicit guidance on when to use this tool versus alternatives such as get_insider_transactions or other sentiment indicators. The description details the computation but does not provide context for selection, exclusion criteria, or prerequisites.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context, such as the as_of_date eliminating look-ahead bias, interaction between as_of_date and lookback_days, and the fact that certain tiers get a permission error.

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 consists of two well-structured sentences. The first sentence establishes the core purpose and return fields. The second efficiently lists filters and the tier restriction. No unnecessary 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?

Given the tool's complexity (8 parameters, 1 required) and the existence of an output schema, the description covers essential behavioral aspects, filter constraints, and tier restrictions. It does not detail the output schema but that is handled separately.

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 goes beyond by explaining the relationship between as_of_date and lookback_days (as_of_date overrides) and briefly describing the lineage_detail options. It compensates for what the schema alone does not provide.

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 clearly identifies the tool's purpose: retrieving Form 3/4/5/144 insider transaction line items for a US public company. It specifies the verb (get) and resource (insider transactions) and distinguishes itself from sibling tools like 'get_insider_sentiment' by detailing the exact data returned.

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?

Description explicitly states the tier restriction ('Institutional tier only') and the error response ('ENTITLEMENT_DENIED' with upgrade link). It does not directly compare to alternative tools or give when-to-use guidance, but the context of insider transactions is well-defined.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context beyond these: data source (Form 13F-HR via by-issuer partition), staleness warning (45-day lag, fires if older than 90 days), and what the output contains (HHI concentration calculation). 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 no wasted words. The first sentence immediately states the core function, followed by specific details (source, lag) in subsequent sentences. It is front-loaded 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?

Given that an output schema exists, the description does not need to detail return fields. It covers data source, reporting lag, staleness condition, and the computation of HHI. For a tool with five parameters (one required) and moderate complexity, the description is complete and adds necessary context for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. However, the description adds meaning beyond the schema by explaining the overall output (aggregate shares, market value, HHI) and the staleness context, which helps the agent understand the tool's purpose and data quality. This justifies a 4.

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 specifies the action ('Returns top-N institutional holders') and the resource ('US public company'), with details on what is included (aggregate shares, market value, holder count, HHI concentration). It distinguishes from siblings by stating 'Institutional tier only' and referencing the by-issuer partition, which differentiates it from tools like get_blockholders or get_top_holders.

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 on when to use the tool (e.g., for institutional holdings data from 13F filings) and includes a staleness warning about reporting lag. However, it does not explicitly exclude alternatives or provide 'when not to use' guidance, leaving the agent to infer from sibling tool names.

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 readonly and idempotent. Description adds context: explains as_of_date is point-in-time cutoff with no look-ahead, period_end is reporting period, and the QoQ delta logic. 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 moderately concise; each sentence contributes useful information. It is front-loaded with the main purpose and then details. Could be slightly more streamlined, but no 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 presence of a full output schema and thorough parameter descriptions, the description covers all necessary context: how to identify the filer, date options, and error handling. No missing critical details.

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 description adds extra meaning: explains the interaction between as_of_date and period_end, preferred identification method, and the effect of multiple name matches. This goes well beyond the schema 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 clearly states it returns a 13F filer's full portfolio with QoQ deltas, using specific verb 'Returns' and resource '13F filer's portfolio'. It distinguishes from siblings like get_institutional_holdings by focusing on a single filer and quarter-over-quarter changes.

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 on how to specify the filer (CIK preferred, name fallback), and notes that multiple name matches raise an error for disambiguation. Also mentions 'Institutional tier only', but does not explicitly contrast with 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 indicate read-only, idempotent, non-destructive. Description adds that no brief exists returns 'found: false' and mentions tier restriction. No contradictions, adds valuable 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?

Concise, well-structured description with no wasted words. Clearly front-loads the purpose and follows with parameter details and edge cases.

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 simplicity and the presence of an output schema, the description fully explains input behavior, edge cases, and tier constraints. Complete for an AI agent to invoke correctly.

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

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

Single parameter 'day' has 100% schema coverage. Description adds behavior for omitting versus specifying a date, enhancing the schema's pattern and 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?

Clearly states the tool reads the caller's Morning Brief, a daily market digest. The specific verb 'Read' and resource 'Morning Brief' are explicit. Distinguishes from siblings by its unique purpose.

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

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

Explains when to omit or include the 'day' parameter, and that omitting returns the most recent brief. Clarifies that missing brief returns 'found: false', not an error. Also mentions tier restriction. Lacks explicit when-not-to-use or alternatives, but the 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 mark the tool as read-only and idempotent. The description adds significant behavioral details: PIT semantics for as_of_date, peer selection methodology, TTM ratio usage, and plan availability. It even flags a known limitation (W3-G2). No contradiction with annotations. The description enhances transparency beyond the structured fields.

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

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

The description is longer than ideal but well-structured. It front-loads the purpose, then provides details on peer selection, categories, date semantics, and availability. Each sentence adds value, though the PIT semantics paragraph could be slightly compressed. Overall, it's efficient for the 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?

Given the complexity (multiple parameters, output schema exists, annotations provided), the description covers all necessary aspects: purpose, methodology, date handling, plan access, and a notable caveat. The output schema handles return values, so no need to describe them. The description is complete for an AI agent to correctly invoke the 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 coverage is 100%, so baseline is 3. The description adds extra semantics: it explains that as_of_date is preferred over period_end_before, and clarifies the PIT behavior for as_of_date. It also notes the default categories. This additional context elevates the score to 4.

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's purpose: 'Get ratio-based peer comparison for a company and its closest competitors.' It specifies the selection method (matching 2-digit SIC code) and the output (pipeline-computed ratios). This distinguishes it from siblings like get_financial_ratios, which provide raw ratios without peer comparison. The verb 'get' and resource 'peer comparables' are precise.

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 on when to use the tool: for ratio-based peer benchmarking. It explains peer selection and gives a caveat about S&P 500 membership being current regardless of as_of_date. However, it does not explicitly state when not to use it or mention alternative tools for similar purposes, such as get_financial_ratios for raw data. Slight lack of exclusions.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds essential behavioral details: survivorship-free construction, index membership interval semantics, confidence levels, the `_meta.pit_safe` field, and a warning about `is_active` causing survivorship bias. 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 dense but well-organized, front-loading the purpose and usage. Every sentence adds value. However, it could be slightly restructured (e.g., bullet points or separate sections) for easier scanning.

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

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

Given the complexity (8 parameters, output schema exists), the description covers all necessary aspects: purpose, alternatives, parameter semantics, return fields, confidence handling, survivorship bias warnings, and integration with other tools. No gaps identified.

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 enriches each parameter with practical context: explains enum values for `index`, paging mechanism for `offset`, the case-insensitive substring behavior for `sector`, the historical vs current usage for `as_of_date`, the differences between `effective` and `announcement` basis, and the dedup vs multi‑share-class behavior of `include_share_classes`. Goes well beyond the schema.

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