Valuein — SEC EDGAR Fundamentals & Smart-Money Data

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

Beyond annotations (idempotentHint=true, destructiveHint=true, etc.), the description provides extensive behavioral context: credential delegation, race-safety, non-re-execution, return fields (executed_now, tool_result), error handling (underlying failure leads to 'failed' state but call succeeds), and ownership privacy. 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 detailed but efficient, with no redundant sentences. It front-loads the core action and then adds important behavior details. Slightly verbose due to thoroughness, but 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 tool's complexity (action approval with side effects, idempotency, error handling), the description covers all critical aspects. It explains return values (executed_now, tool_result, state), ownership privacy, and behavior on failures. The output schema is not provided but referenced; the description sufficiently compensates.

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 description of the single parameter ('Id of the staged action to approve, from stage_action or list_pending_approvals.') aligns with the schema's description. The description adds no additional semantics beyond identifying the parameter's source, so baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: 'Approve a staged action by id and RUN the underlying tool call it proposed'. It specifies the verb (approve/run), resource (staged action), and distinguishes from siblings like stage_action and reject_staged_action by emphasizing execution using caller credentials.

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 implicitly guides when to use the tool by detailing idempotency and race-safety behavior, and mentions access control ('Tier: sp500+'). It does not explicitly list alternatives, but the sibling context and name make it clear. The description could explicitly state 'Use when you want to approve a pending action', but is otherwise effective.

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=false, destructiveHint=true, idempotentHint=true), description adds that only pending tasks are cancellable, idempotent behavior (already cancelled is no-op), and tier/access restriction, providing full behavioral 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?

Two concise sentences, front-loaded with main action, no redundant information.

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

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

Complete for a simple cancellation tool: specifies constraints, idempotency, and has output schema indicated. Covers all necessary behavior.

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

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

Schema description coverage is 100% for parameter 'task_id', and description does not add extra meaning beyond the schema's description. 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?

Description states 'Cancel a pending scheduled task by id', specifying the action and resource. It also clarifies the source of the id (from schedule_task or list_scheduled_tasks), distinguishing the tool's purpose among siblings.

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

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

Clearly states when to use: only 'pending' tasks can be cancelled, and completed tasks cannot. Mentions idempotency. Does not explicitly name alternatives but context suffices.

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 auto-swap behavior with swapped flag, significance classification thresholds (<5%, 5-15%, >15%), and material_changes count. Annotations already indicate readOnly/ idempotent, but description adds rich 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?

Single paragraph covering multiple aspects efficiently. No obvious filler, but could be broken into bullet points for easier scanning. 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?

Covers all aspects: purpose, usage, response structure (significance, material_changes, swapped flag), triage advice, point-in-time safety. Output schema exists but description still provides essential context.

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?

Adds significant meaning beyond the input schema: explains period format explicitly, order convention, auto-swap, and as_of_date function. Schema coverage is 100%, but description still adds 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 compares core financial metrics across two fiscal periods side-by-side, showing absolute and percentage changes with significance classification. It distinguishes itself from siblings by focusing on period comparison, which no other tool in the list explicitly does.

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 format guidance ('FY2024', 'Q1-2024'), order convention (period_a earlier, period_b later), and auto-swap behavior. Offers a triage guideline using material_changes count. Includes point-in-time safety mention and plan availability.

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 explains the source of pulled inputs (R2), the fallback chain for shares resolution, the echo of inputs with source lineage for reproducibility, and the meaning of null value_per_share_cents (degenerate model, not zero) with a reason field. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint).

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 appropriately sized for the tool's complexity. It is front-loaded with the main purpose, followed by behavioral details, usage guidance, and persistence note. Every sentence serves a purpose, 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 tool's complexity (two-stage model, 8 parameters, sensitivity grid, input overrides, fallback chains, null handling) and the presence of an output schema, the description covers all necessary aspects: inputs, outputs, edge cases, alternatives, and persistence. It leaves no ambiguity for an AI 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?

Schema coverage is 100%, so the baseline is 3. The description adds valuable context beyond schema: it defines FCF base and net debt consistently with other tools (get_financial_ratios, get_capital_allocation_profile), explains the shares resolution fallback chain, and mentions the echo behavior. This provides richer meaning for the parameters.

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, specifies inputs (growth, WACC, terminal assumptions) and outputs (per-share intrinsic value in cents and a sensitivity grid). It distinguishes from sibling tools by explicitly naming get_valuation_metrics as an alternative for pre-computed values and create_report for persistence.

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

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

The description provides explicit when-to-use (drive own assumptions) and when-not-to-use (use get_valuation_metrics instead for pre-computed values). It also clarifies that the tool does not persist a report, directing to create_report for that purpose. Alternatives are clearly named.

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 the tool is not read-only, not idempotent, and not destructive. The description elaborates on behavior: it persists an alert, registers it with a firing pipeline that runs every 5 minutes, and supports multiple channel types. 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 appropriately sized for a complex tool, with a clear structure: opening statement, bulleted condition shapes, then delivery channels. It is front-loaded with the main action. Every sentence provides meaningful information, though it could be slightly more concise.

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 required parameters with nested discriminated unions), the description covers all condition types and channels. The presence of an output schema reduces the need to discuss return values. The description is complete enough for an agent to understand 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by providing a narrative summary of condition shapes and channel types that enhances understanding beyond the schema's structured descriptions. For example, it explains delivery channel specifics like HMAC for webhook and slack URL requirements.

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

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

The description starts with a specific verb ('Persist an alert and register it with the firing pipeline') and resource, clearly distinguishing what the tool does. It enumerates five distinct condition shapes and delivery channels, setting it apart from siblings like test_alert, list_alerts, and delete_alert.

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 this tool, including a note to verify channels with test_alert before relying on cron. It lists condition types with their requirements and Pro+ restrictions. However, it does not explicitly mention when not to use it or compare to alternative tools beyond test_alert.

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 (which indicate idempotentHint=true, destructiveHint=false, readOnlyHint=false). It explains that reports are per-author state, synchronous generation, and that the tool returns full markdown, JSON, and citation chains. 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 well-structured with bullet points for subtypes and clear separation of concerns. It is slightly lengthy but earns its length by explaining two distinct use cases. The main action is 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?

Given the complexity (6 parameters, two subtypes, nested objects, and an output schema), the description is fairly complete. It explains the purpose of each parameter per subtype and the output format. The mention of 'per-author state' and 'idempotency_key' adds necessary context. The output schema is not described, but that is acceptable since it exists 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 description coverage is 100%, so baseline is 3. The description adds value by grouping parameters by subtype and explaining their roles (e.g., params are for reverse_dcf, thesis_id for thesis). It does not add new syntax or formatting details 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 synchronously generates a research report and persists it under the caller's authorship, with two distinct subtypes (reverse_dcf and thesis) that are thoroughly described. It distinguishes itself from siblings like get_report, update_report, and delete_report by focusing on creation.

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

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

The description explicitly states when to use each subtype and which parameters are required (reverse_dcf requires ticker+params, thesis requires thesis_id). It also notes that edits to a thesis do not propagate to an existing report, implying a new report should be generated. However, it lacks explicit advice on when not to use this tool vs alternatives like compute_dcf.

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

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

Beyond annotations (which only provide hints), the description discloses that some triggers are persisted but not wired to live sources, and that condition_expr is deliberately restricted as an anti-complexity guard. Also mentions the trigger_wiring_status field in the output.

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

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

Well-structured and front-loaded with core purpose, but somewhat lengthy. Every sentence is purposeful, but could be tightened slightly without losing value.

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 of the tool (multiple trigger/action types, condition expression, tier restriction), the description is fully comprehensive. It covers live status, testing workflow, and output field mention, making it 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%, but the description adds substantial meaning: explains condition_expr format with examples, clarifies trigger and action discriminated unions, and provides context for fields like hmac_secret and condition_type_filter.

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: persisting a trigger-action rule and registering it with the evaluator. It lists the exact trigger and action types, and distinguishes from siblings like 'test_rule' by explicitly recommending its use for verification.

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: which trigger types are actually live, that condition_expr is optional and limited to single comparisons, and to avoid general expressions. Recommends using test_rule for verification. Also mentions 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?

Annotations already indicate destructive and idempotent. Description adds soft-delete detail, status flip, cron removal, and tier info. 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, each packed with useful information, front-loaded with key verb and effect. 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?

With output schema present, description doesn't need to cover return. Covers deletion behavior, idempotency, tier, and parameter source. Complete for this simple 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 covers 100% with clear parameter description. Description does not add new semantic 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?

Description clearly states 'Soft-delete an alert by its id', specifies the status change and removal from cron evaluator. Distinguishes from siblings like create_alert and list_alerts.

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

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

Explicitly says when to use (to delete) and when not to use (to change, instead delete then create). Mentions idempotent and tier constraints.

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 (idempotentHint=true, destructiveHint=true), the description adds valuable behavioral details: returning deleted=false for missing overrides and the revert effect on reports. 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 with four short sentences, each adding distinct information: purpose, idempotency, side effects, and tier. Front-loaded with 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?

Given the output schema exists and covers return values, the description sufficiently explains behavior on missing overrides and downstream effects. The tier note adds access context. No gaps are evident.

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 fact_id with length constraints and a helpful description referencing save_citation_override and list_citation_overrides. The tool description adds minimal new parameter information ('by fact_id'), so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Remove') and the resource ('citation correction') identified by fact_id. It distinguishes from siblings like save_citation_override and list_citation_overrides by specifying removal and idempotent behavior.

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 for when to use the tool: it mentions idempotency (safe to call on missing overrides) and the effect on reports. However, it does not explicitly state when not to use or mention alternatives beyond the 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?

The description adds significant context beyond annotations: soft-delete, data preservation for audit, idempotency even if already archived. 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 concise – two sentences plus a tier line – with no unnecessary words. Every sentence adds value.

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

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

Given a single parameter, good annotations, and presence of output schema (implied), the description covers behavior, idempotency, audit trail, and tier restrictions adequately.

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 little beyond confirming 'by id', so baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('soft-delete'), resource ('claim by id'), and distinguishes from other delete tools by explaining the archival behavior and idempotency.

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 the effect on list results but does not explicitly state when to use this tool vs alternatives (e.g., other delete tools). The tier info is present but not usage-specific.

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 goes well beyond annotations by explaining the soft-delete mechanism, preservation of data for 90 days, idempotency details, and the 'Sample tier rejected' constraint. Annotations only provide hints, while the description fully discloses the non-destructive yet state-changing nature of the operation.

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, using only three sentences to cover purpose, behavior, idempotency, audit window, and access notes. All information is front-loaded and necessary, with 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 tool's simplicity (one parameter, no output schema needed due to existing output schema), the description covers the main aspects: what it does, how it behaves, and constraints. However, the 'Sample tier rejected' note is vague and could confuse an agent about whether the tool is available; otherwise, it is 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 the parameter already well-described as an ID from create_report or list_my_reports. The description does not add new parameter semantics beyond that, but the baseline of 3 is appropriate since the schema handles it fully.

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 of a report owned by the caller, specifying exact state changes (status to delisted, visibility to private). It distinguishes itself from sibling delete tools by focusing on reports and ownership, leaving no ambiguity about the resource and action.

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

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

The description provides clear context for use: only for reports owned by the caller, with idempotent behavior. It implies when to use (soft delete) but does not explicitly compare with other delete tools or state when not to use. The 'Sample tier rejected' note hints at access restrictions, adding some 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 indicate destructiveHint=true and idempotentHint=true. The description adds crucial context: the rule is removed from both the catalog and evaluator's scan index, it stops firing immediately, and it's idempotent. It also mentions the tier restriction, which is 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 extremely concise, with two sentences that front-load the action and key details. Every word adds value, and the structure is clear and easy to parse.

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 deletion tool with a single parameter, the description is complete. It explains the effect, idempotency, tier restriction, and the immutability workaround. The presence of an output schema (not shown but noted) further supports 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 description adds value beyond the input schema by specifying the source of the rule_id ('from create_rule/list_rules'), which helps the agent know where to obtain valid identifiers. The schema already covers the parameter with 100% coverage, so the description enhances usability.

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 a rule by id'), specifies the resource ('rule', sourced from create_rule/list_rules), and describes the effects (removes from catalog and scan index, stops firing). It distinguishes from siblings by mentioning create_rule and list_rules as sources for the id.

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 this tool (to delete a rule) and provides guidance on immutability ('to change one, delete then create_rule'). It also notes the tier restriction (sp500+). While it doesn't explicitly list alternatives, the context is sufficient for decision-making.

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?

Description adds context beyond annotations: soft-delete nature, idempotency, audit trail, no claim deletion, future expiration. Consistent with idempotentHint=true and destructiveHint=true. 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 plus one about tier. Front-loaded with main action. Every sentence adds unique information, no redundancy. Highly 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?

With output schema present, description doesn't need return details. Covers all key aspects: behavior, idempotency, limitations (no hard delete, no claim deletion), future plans, tier. Complete for a single-param mutation 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?

Only one parameter thesis_id with schema coverage 100%. Description adds value by specifying its origin (from save_thesis or list_theses), which helps the agent know valid input sources. Slightly above 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?

Clearly states it soft-deletes (archives) a thesis, using specific verb 'delete_thesis' with resource 'saved thesis'. Distinguishes from hard-delete and specifies behavior (status flips to 'archived'). Sibling contrast (delete_claim) is noted.

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

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

Explicitly says when to use (for archiving) and when not to (hard-delete not supported, use delete_claim for claims). Mentions tier restrictions. Provides clear guidance on 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 declare destructiveHint=true and idempotentHint=true. The description adds context: explains soft-delete mechanics, clarifies that the watchlist remains readable via list_watchlists with specific status filter, and mentions tier restriction. Does not contradict 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?

Extremely concise: two sentences plus a tier note. All information is front-loaded with no fluff. 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 single parameter, full schema coverage, annotations, and presence of output schema, the description is complete. It covers all necessary behavioral aspects like soft-delete, archiving, idempotency, and tier restriction.

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

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

Schema coverage is 100% with detailed parameter description. The description adds value by highlighting the 'by name not id' aspect and 'frees the name for reuse,' which enriches the schema's documentation. Baseline 3, slight improvement.

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 (soft-delete), resource (watchlist), and key behavior (status flips to archived, name freed for reuse). It distinguishes from hard delete and mentions the alternative list_watchlists for reading archived entries.

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 context: when to use (to archive a watchlist), idempotency, tier restriction (sp500+), and what happens after (name reusable). It implicitly advises against using for permanent deletion since it's a soft delete.

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=true, idempotentHint=true, destructiveHint=false, so the safety profile is already clear. The description adds valuable context that 'No data reads required — schema is embedded in the manifest', which explains the read-only nature beyond annotations. 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 at three sentences, front-loaded with the core purpose, followed by details and usage advice. Every sentence adds value with no redundancy or 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?

The tool has one optional parameter and an output schema (context confirms). The description covers the essential: what it returns, when to use, and that it is non-destructive. For a simple read-only schema tool, this is fully adequate and leaves 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 description coverage is 100% (one parameter with schema description). Baseline is 3. The description adds extra meaning by stating 'Omit to return the full schema for all tables', clarifying behavior beyond the schema. This justifies a higher score.

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 verb 'Returns' and the resource 'the Parquet schema for all tables in the Valuein SEC data warehouse'. It lists included elements (table descriptions, column names, types, primary keys, foreign-key references), and distinguishes from siblings by advising to use this tool before querying with others.

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

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

The description explicitly says 'Use this tool to understand the data model before querying with other tools', providing clear context. It also notes that no data reads are required and it's available on all plans. However, it does not explicitly mention when not to use it or name alternative tools, but the guidance is sufficient.

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 crucial behavioral details beyond annotations: explains it is a soft-delete (sets dismissed_at, row remains queryable), idempotency, and tier restrictions. No contradiction with annotations (destructiveHint=true aligns with soft-delete).

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 at ~50 words, front-loaded with the key action. Each sentence adds distinct value (soft-delete, parameter source, audit note, idempotency, tier). Optimal length with no wasted words.

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

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

For a single-parameter tool with good annotations and output schema, the description covers all necessary aspects: purpose, parameter semantics, behavioral details, and access constraints. 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%, so baseline is 3. The description adds extra context by specifying the parameter must come from list_alert_inbox and is not an alert id, which adds meaning beyond the schema's 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?

Description clearly states the tool soft-deletes a single inbox item, specifies the parameter source (from list_alert_inbox), and distinguishes it from an alert id. It also notes the effect (sets dismissed_at) and idempotency, making the purpose highly specific and distinct from siblings.

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

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

Provides clear context on what the tool does and how to use it (parameter from list_alert_inbox, not alert id). However, it does not explicitly compare to sibling 'mark_inbox_read' or state when not to use it, so slightly lacking in exclusion 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 indicate readOnlyHint=true and idempotentHint=true. The description adds that the tool is deterministic, returns red-flag narratives with citations to source filings, and discloses limitations (partial Beneish due to missing data). This provides useful 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 concise with three sentences that quickly convey purpose, output, and limitations. No redundant information; every sentence adds value.

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

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

The tool has an output schema (not shown but noted), so description does not need to detail return values. It covers purpose, limitations, and usage context (SOP). However, it could mention that the output includes a narrative with citations, which it does. Nearly complete 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?

Schema coverage is 100% for the single parameter (ticker). The description does not add new semantic details beyond the schema, but confirms it is for a single ticker. Baseline 3 is appropriate since schema already documents the parameter well.

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 computes deterministic forensic-accounting scores (partial Beneish M-Score, Sloan accruals, solvency snapshot) for a single ticker, and returns a red-flag narrative with severity and citations. This is specific and distinct from sibling tools like get_earnings_signals or get_company_fundamentals.

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

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

The description mentions it is used by the forensic_earnings_brief SOP, providing context, but does not explicitly state when to use this tool vs alternatives or when not to use it. No direct comparison to siblings is given.

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 that ratios are rendered as-supplied without server-side verification, resulting in 'unverified' watermark. Explains Excel table feature and subject-row highlight. No contradiction with annotations (readOnlyHint: false, destructiveHint: false).

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

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

Concise yet informative: first sentence states purpose, then key features, then trust note, then pairing. No wasted words; good structure with section headers.

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, output format, behavioral nuances, workflow integration, and limitations. Complete given 4 parameters and output schema existence.

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 has 100% parameter description coverage, so baseline is 3. Description adds context like optional notes on Summary sheet and fallback for subject_company_name, but does not significantly enhance 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?

States verb 'Render' with resource 'peer comparables table into an Excel workbook'. Specifies output format, subject-highlight, and pairing with get_peer_comparables, distinguishing it from siblings.

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

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

Explicitly advises pairing with get_peer_comparables for authoritative figures, and warns about watermark for unverified data. Provides clear when-to-use and when-not-to-use guidance.

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

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

Adds significant context beyond annotations: re-derivation in-worker, correction banner for discrepancies, 15-minute presigned URL, and that fabricated values cannot appear. Annotations are non-contradictory (not read-only, not destructive).

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 comprehensive but slightly long; each sentence adds value. Could be trimmed slightly, but front-loaded with key verbs and details. 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 complex nested input schema, the description covers purpose, output, trust model, correction behavior, and pairing. With output schema existing, it need not detail return structure. Fully adequate 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%, so description adds marginal value. It notes dcf_result comes from compute_dcf and company_name appears on cover row, but these are minor. 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 it renders a DCF result into an Excel workbook with specific sheets (Summary, Sensitivity heatmap, Inputs). It names the output format and distinguishes from sibling compute_dcf, which computes the 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 analyst flow, describing the sequential call pattern. Also explains behavior when claimed figures disagree (correction banner) and re-derivation in-worker, guiding appropriate usage.

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 clearly discloses that content is not verified by Valuein, resulting in a watermark and unverified status in the response. This goes beyond the annotations (readOnlyHint/destructiveHint) to inform the agent of trust 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 clear sections, front-loaded with the main purpose. It is slightly verbose (e.g., repeating 'cover, abstract...' from parameter descriptions), but every sentence adds value. Could trim redundant references to the same content.

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

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

Given the tool has an output schema (not shown), the description adequately covers purpose, usage, behavioral notes, and integration with other tools. It explains the watermark and verification status, and the typical workflow with create_report. 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?

All 7 parameters have schema descriptions covering length, defaults, and roles. The description adds context about how parameters map to document sections (cover, snapshot, citations) and integration with create_report, but does not significantly enhance parameter meaning 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 precisely states the tool renders a structured research brief into a Word document with specific components (cover, abstract, snapshot table, body sections, citations). It distinguishes itself by specifying no embedded charts and referencing sibling tools for visuals, leaving no ambiguity.

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

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

The description provides explicit when-to-use guidance (pair with generate_dcf_xlsx/generate_comps_xlsx for charts), a typical flow (create_report then this tool), and a prerequisite (resolve citations via verify_fact_lineage before publishing). It also notes the tool is tier pro+.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds valuable behavioral info: returns 'found: false' for unknown ids or ids belonging to another customer by design (no distinguishing signal), and mentions 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?

Three sentences with no redundancy. First sentence front-loads purpose and returned fields. Second sentence clarifies scope. Third sentence covers error cases and access tier. Every sentence adds value.

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

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

For a single-parameter tool with an output schema (not shown but implied by field listing), the description covers all necessary aspects: what it returns, edge cases, access control. 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 covers 100% of parameters with description 'Run identifier, from list_agent_runs.' Description adds context about where the id comes from and edge-case behavior (found:false). Baseline 3 is exceeded due to extra usage-derived context.

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

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

Description uses specific verb 'Fetch full detail' and clearly identifies the resource 'standing-agent runs by id'. It distinguishes from sibling tool 'list_agent_runs' by referencing it as the source of ids and detailing the returned fields (status, goal, tickers, cost, artifact ids, role breakdown, error).

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 states when to use: to get detail for a run from list_agent_runs. It clarifies both agent-triggered and workspace-triggered runs are supported. It does not explicitly mention when not to use or name alternatives, but the context is clear enough given the sibling list.

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 valuable context about the going_active flag, default parameter behaviors (latest_only, collapse_groups), and the institutional tier restriction, which enhances transparency beyond the structured 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 (about 6 sentences) with no wasted words. It uses code formatting for emphasis and is front-loaded with the core purpose. Every sentence adds value, including direct usage hints and explanation of the most important flag.

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 has an output schema (so no need to detail return values), the description covers the key data fields, parameter defaults, and the unique going_active detection. It explains the dedup and group collapse options, making it complete for an analyst to understand the tool's functionality.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning for key parameters like latest_only (dedup logic) and collapse_groups (folding multi-person filings), and explains the going_active flag and its significance, which is not fully covered in the schema.

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

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

Description clearly states it returns SC 13D/13G blockholder disclosures for US public companies with specific data fields. It is specific about the resource and verb but does not explicitly differentiate from sibling tools like get_institutional_holdings 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 implies usage context (US public companies, blockholder filings) and mentions 'Institutional tier only' as a restriction, but it does not provide explicit guidance on when to use this tool versus 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?

Annotations (readOnlyHint=true, idempotentHint=true) are complemented by detailed behavioral context: data source (10-K filings), PIT-safety via as_of_date, R&D treatment rationale, and flag definitions. 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 somewhat lengthy but well-structured: purpose first, then use cases, then technical details. Every sentence adds value given the tool's complexity. Could be slightly more concise but is 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 output schema exists (not shown but noted), the description covers all needed context: data source, scope (US public companies), annual frequency, and special handling of R&D. Complete for a data retrieval tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds minor context (e.g., 'PIT-safe', 'Defaults to 5 years') but these are already in the schema. 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 'Get a multi-year capital allocation breakdown for a US public company' with a specific verb and resource. It distinguishes from sibling tools by listing exactly which user questions trigger this tool, making it 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?

Description provides explicit when-to-use guidance with example questions ('how does a company allocate capital', 'what's the buyback-vs-dividend mix', etc.) and mentions specific analysis styles. Lacks explicit 'do not use' or alternatives, but the use-case list is sufficiently clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context about the append-only score history and inclusion of thesis IDs, confirming non-destructive behavior. 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?

Two sentences: first states action and result, second gives usage guidance. Concise and front-loaded with 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 output schema exists, the description adequately covers purpose, usage, and parameter source. The tool is simple with a single parameter, and the description is 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?

Only one parameter, claim_id, with description 'Id returned by save_claim or list_claims.' Schema coverage is 100%. The description adds meaningful origin context 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 verb 'Fetch' and the resource 'claim by id', and specifies what additional data is returned (thesis IDs, score history). It distinguishes from siblings like list_claims and save_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 'Use this to inspect a claim's evidence, current status, and how its outcome has evolved.' Provides clear context for when to use, though no explicit 'when not to use' is given.

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 explains the lack of look-ahead bias with as_of_date, the behavior when strict is false (return available data and explain truncation), and the data source (10-K/10-Q). It does not contradict the annotations (readOnlyHint, idempotentHint, destructiveHint).

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 (4 sentences) and front-loaded with the primary purpose. Every sentence adds value: purpose, metrics, data source, point-in-time feature, and sibling differentiation. No redundant information.

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

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

Given the tool's complexity (8 parameters, output schema exists), the description covers all essential aspects: what it returns, data source, point-in-time ability, behavior of strict parameter, and alternatives. The output schema documents return values, so no need to repeat them.

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 covers all 8 parameters with descriptions. The description adds context like 'no look-ahead bias' for as_of_date and the meaning of strict parameter behavior. While the schema is complete, the description enhances understanding of usage scenarios.

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 'Retrieve' and clearly identifies the resource: 'standardized SEC EDGAR fundamental financial metrics for a US public company.' It lists specific metrics and distinguishes from sibling tools (get_financial_ratios, get_valuation_metrics), making the 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?

The description explicitly states when to use this tool versus alternatives: 'for pipeline-computed ratios... use get_financial_ratios, and for margins combined with DCF/DDM model inputs use get_valuation_metrics.' It also explains the point-in-time usage for backtesting, providing clear 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 goes beyond annotations by disclosing the 15-minute URL expiration, HTTP range read support, scope to caller's tier bucket, and security constraints (signed link prevents listing or reading other objects). It also explains dataset-specific behavior (ticker required for 'fact'). 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 a single, information-dense paragraph that front-loads the core action (returns a short-lived URL) and then efficiently covers all relevant details. Every sentence earns its place, with 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?

Given 2 parameters, 100% schema coverage, and an output schema (implied by the URL return), the description covers the tool's purpose, usage, behavioral details, dataset options, and prerequisites. It is sufficiently complete for an 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?

With 100% schema coverage, the description adds significant value by explaining that 'ticker' is required only for dataset_type='fact' and resolves to per-entity partitions, while other datasets are full-universe tables. It also clarifies the partition naming convention, which is absent from the schema.

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

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

The description clearly states the tool returns a short-lived download URL for bulk Parquet objects, specifying the exact use case (high-throughput computation beyond MCP context). It lists the available datasets, making the resource unambiguous and distinguishing it from sibling tools like 'get_company_fundamentals' which return structured data directly.

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 high-throughput computation exceeding context window) and how it works (streams from storage, supports range reads). However, it does not explicitly mention when not to use it or list alternative tools for smaller data.

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, destructiveHint, and the description aligns, adding that the tool is safe for point-in-time use. It transparently explains that eps_trend_est is not consensus but a deterministic estimate from the company's own prior data, and that eps_surprise_pct measures deviation from the company's trend. This adds valuable context beyond the annotations.

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

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

The description is relatively long but each sentence provides important information, such as the caveats about consensus and point-in-time safety. It front-loads the purpose and key outputs. While slightly verbose, it remains focused and 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 tool's complexity (earnings signals with derived estimates), the description adequately covers the return values, key usage caveats, and data source. An output schema exists to handle the return format. The description is complete enough for an agent to understand the tool's behavior and limitations.

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 description adds meaning by explaining the significance of eps_trend_est and eps_surprise_pct, and the default limit covers 2 years. The as_of_date parameter is reinforced for backtesting. This adds value 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 the tool reports earnings results and a model-derived earnings-trend signal, specifying actual EPS, trailing-trend estimate, surprise percentage, revenue, and growth. It uniquely identifies the resource (company earnings by fiscal period) and distinguishes itself from siblings by highlighting its deterministic estimation from SEC EDGAR rather than analyst consensus.

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 the tool (track earnings/revenue trajectory and momentum) and warns against using it to claim consensus beats or misses. It also notes point-in-time safety for backtesting with as_of_date. However, it does not explicitly compare to sibling tools or state when not to use it, but the context from the sibling list shows no direct competitors.

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. Description adds rich behavioral context: return structure with value/unit/category/reason, lineage pointing to get_company_fundamentals, null value handling with reasons, PIT behavior for as_of_date, and LIVE nature of valuation categories. 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 long but front-loads core purpose and sibling differentiation. Every sentence adds necessary nuance. Could be slightly trimmed but remains focused.

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 6 parameters, output schema exists, and tool complexity, description is comprehensive: covers return format, missing values, lineage, PIT behavior, category handling, alignment field, plan availability. Leaves minimal 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% with descriptions for all 6 parameters. Description adds extra meaning: explains categories behavior in detail (availability, omission), as_of_date PIT logic, period_end_before as alias, limit range. Adds value 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 retrieves pipeline-computed financial ratios and lists categories. It distinguishes from sibling tool get_valuation_metrics with explicit guidance on when to use each.

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 when-to-use and when-not-to-use advice, including differentiation from get_valuation_metrics. Explains category availability and suggests omitting categories to get all available. Discusses as_of_date behavior and is_calendar_aligned for joins.

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 (readOnlyHint, idempotentHint, destructiveHint) already indicate safe read behavior. The description adds significant algorithmic detail: role weights, P/S coding with neutralization of certain transaction types, and cluster detection logic, providing 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 a single paragraph that efficiently conveys the core purpose first, then algorithmic details. It is front-loaded and reasonably concise, though could be slightly shorter.

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 and annotations, the description fully covers the tool's behavior including formula details, constraints (institutional tier), and cluster flag logic. No gaps remain for agent 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 each parameter. The description adds context on lookback window and cluster detection but does not add new meaning beyond what the schema already provides, thus baseline score 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 explicitly states the tool computes a role-weighted insider sentiment score on a fixed [-100, +100] scale for a single issuer over a lookback window. It details role weights, transaction coding, and cluster flag, clearly distinguishing it from siblings like get_insider_transactions.

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

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

The description does not explicitly state when to use this tool vs. alternatives like get_insider_transactions. It mentions 'Institutional tier only' implying access restrictions, but lacks exclusions or comparative 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 indicate read-only and idempotent behavior. Description adds important behavioral details: ENTITLEMENT_DENIED for insufficient tier, as_of_date eliminating look-ahead bias, and lineage_detail options. 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?

Single dense paragraph with front-loaded purpose sentence. Every sentence adds value: core function, returned fields, filters, tier restriction. 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 8 parameters with full schema coverage and an output schema, the description covers all necessary aspects: purpose, filters, behavior, tier constraints. Agent has sufficient information to correctly 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 has 100% description coverage, so baseline is 3. Description adds meaningful context beyond schema, such as explaining that as_of_date overrides lookback_days and clarifying transaction code meanings. It does not duplicate 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?

Description clearly states tool returns insider transactions (Form 3/4/5/144 line items) for a US public company. It specifies the data fields and filtering options, distinguishing it from sibling tools like get_insider_sentiment.

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 mentions tier restriction (Institutional tier only) and explains that lower tiers return ENTITLEMENT_DENIED. Provides filtering guidance but does not directly compare with alternatives or state when not to use.

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

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

Discloses important behavioral traits beyond annotations: ~45-day reporting lag, staleness_warning at 90 days, use of as_of_date for backtesting with zero look-ahead, and data sourcing from 'by-issuer partition'. 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?

Three sentences, front-loaded with the main output, followed by source, tier, and lag details. 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?

Covers all key aspects: what is returned, data source, lag, tier, and staleness warning. Output schema handles return details, so description is complete for selection and 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 detailed descriptions for each parameter. The description adds context such as 'latest by default' for period_end and the meaning of as_of_date for backtesting, which enhances understanding beyond what the schema provides.

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

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

Clearly states the tool returns top-N institutional holders for a US public company with specific metrics (aggregate shares, market value, holder count, HHI concentration). Distinguishes from siblings by specifying 'Institutional tier only' and 'Form 13F-HR via the by-issuer partition', making its scope unique among related 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?

Provides clear context for use by describing data source (13F filings) and the staleness warning. Implicitly differentiates from other holdings tools (e.g., insider, blockholders) but does not explicitly name alternatives or provide when-not-to-use guidance.

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

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

Aligns with annotations (readOnly, idempotent, non-destructive) and adds details about fuzzy matching, error handling, and the role of as_of_date vs period_end, which annotations do not cover.

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 covering purpose and key parameter guidance. Front-loaded with primary action. No redundancy, but could be slightly more structured with bullet points or separated sections.

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 output schema, the description adequately covers input parameters and constraints. Additional context like 'Institutional tier only' is useful. No missing critical information for a 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?

Despite 100% schema coverage, the description adds value by explaining preferred parameter usage, fuzzy match behavior, and the distinction between as_of_date and period_end.

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. It distinguishes from siblings like get_institutional_holdings by specifying 'by filer' and including deltas.

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 on specifying filer via CIK or name, disambiguation, and parameter defaults. Lacks explicit when-not-to-use or alternatives, but the context is sufficient for correct 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?

Adds context beyond annotations: explains that omitting day returns most recent (not necessarily today's), that no brief returns found:false (not error), and mentions tier restriction. Annotations already indicate idempotent/read-only, so this adds value 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?

Two sentences with clear structure. Front-loaded with purpose, then parameter logic, then edge cases. 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?

Covers purpose, parameter behavior, expected output for edge case, and access tier. With output schema present, return values need not be detailed. Complete for a read-only retrieval tool.

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

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

Schema coverage is 100% with parameter description, but the tool description adds nuance: explains the behavior of omitting vs providing day, and clarifies that no brief is a normal state. This extends the schema's 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 the tool reads the caller's Morning Brief, a daily market digest. It specifies the content (overnight moves across watchlists and theses) and distinguishes it from other read/get tools like get_report or get_company_fundamentals.

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

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

Provides explicit guidance on parameter usage: omit day for most recent, pass specific day with format. Also explains expected behavior when no brief exists. Does not explicitly compare to alternative tools but covers the primary use case well.

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 detailed behavioral traits beyond annotations: peer selection methodology (SIC code, S&P 500 proxy), TTM ratios preference, PIT semantics with pit_safe flags, and as_of_date impact. Annotations already declare read-only, but description adds critical nuance.

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 paragraph of ~100 words with front-loaded purpose. Every sentence adds non-redundant information: peer selection, categories, TTM, as_of_date behavior, PIT semantics, and plan availability. No waste.

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

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

Comprehensive for a read-only comparison tool with 5 parameters and output schema. Covers peer count, ratio categories, historical option, data freshness methodology, and a notable limitation (S&P 500 membership). Output schema handles return structure.

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, baseline is 3. Description adds meaning by explaining as_of_date's dual role (PIT for figure leg, but not for peer selection), listing ratio categories, and noting limit bounds. Does not fully cover period_end_before alias nuance but adds 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?

Description clearly states 'Get ratio-based peer comparison for a company and its closest competitors', with specific verb and resource. Explains peer selection via SIC code, distinguishing from sibling tools like get_financial_ratios which focus on single company ratios.

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

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

Provides clear context for usage: when to use (benchmarking with peers), how to set historical date via as_of_date, and availability mention. Lacks explicit exclusions or direct alternative naming, but 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 indicate readOnlyHint=true and destructiveHint=false, which align with the read-only nature. The description adds substantial behavioral detail: it returns a survivorship-free universe with accurate join/leave dates using `[)` interval semantics, provides per-row confidence and `_meta.pit_safe` flag, explains sector is SIC-derived (not licensed GICS), and documents edge cases like out-of-range dates returning empty arrays. 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 quite long but well-structured and front-loaded with the main use case. Every sentence adds value, and the information is logically organized (use case, behavioral details, parameter caveats, integration hints). Could be slightly more concise, but it remains efficient given the tool's complexity.

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

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

Given the tool has 8 optional parameters, a output schema exists, and the topic is complex (PIT universe with survivorship-free indexing, multiple indices, and hidden bias risks), the description covers all critical aspects: what is returned, how to use, caveats (survivorship bias with `is_active`, date range limitations), and integration with other tools. Nothing important is omitted.

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

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

Schema description coverage is 100%, but the description adds meaningful context beyond the schema. For example, it explains the survivorship bias introduced by setting `is_active=true` on historical queries, the difference between 'effective' and 'announcement' for `as_of_basis`, and the rationale for `include_share_classes` defaulting to false. These enrich the understanding of parameters, though the schema already covers basic 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 answers historical index membership questions with specific examples (e.g., 'Was Company X in the S&P 500 on date Y?'). It distinguishes itself from the sibling tool `search_companies` by explicitly noting that `search_companies` only returns current membership. The verb 'answer questions about historical index membership' and additional use cases are specific and 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 explicitly instructs when to use this tool ('Use this INSTEAD OF `search_companies` when the question involves a specific historical date') and provides clear exclusions (e.g., 'WARNING: setting this to true on a HISTORICAL query reintroduces survivorship bias'). It also states its role as a first step in a quantitative backtest before `get_compute_ready_stream`, giving clear context and 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 goes well beyond annotations by explaining the zero look-ahead bias, data sourcing (stock_price_daily.parquet and SEC filings filtered by accepted_at), TTM computation method, and the resulting output. It adds significant behavioral context beyond readOnlyHint and idempotentHint.

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, starting with the main function, then methodology, then detailed returns, then use cases, and finally plan coverage. It is front-loaded with the most important information. Every sentence is informative and no redundant verbosity.

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 includes all necessary context: purpose, methodology, output details, use cases, and plan-dependent coverage. Given the presence of an output schema, the description sufficiently explains what the tool returns without needing to document return values.

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

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

Schema coverage is 100%, but the description adds meaningful context to the 'as_of_date' parameter, explaining how the EOD close is determined (nearest prior trading day) and the history range. 'ticker' has examples. This adds value 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 returns a full snapshot of valuation multiples for a company on a specific historical date with zero look-ahead bias. It distinguishes itself from sibling tools like get_valuation_metrics by emphasizing the point-in-time nature and lack of bias.

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 use cases (historical valuation screens, backtesting, forensic audit) and mentions plan coverage. It does not explicitly state when not to use the tool or list alternatives, but the use cases are clear and contextual.

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 readOnly and idempotent. Description adds crucial behavioral details: adjusted_close is retroactively restated (NOT PIT-immutable), returns oldest-first, limit behavior when range exceeds limit. 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 well-structured, front-loaded with key information, uses bullet points for return fields. Every sentence adds value without unnecessary verbosity.

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 necessary aspects: return values, edge cases for omitted dates, coverage tiers, and includes an output schema. Complete for a tool of moderate 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?

Schema coverage is 100% with detailed parameter descriptions. Description adds value with extra context (e.g., tie-breaking for limit, default date resolution) that goes beyond schema, justifying 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 states the tool returns daily EOD bar series (OHLCV + adjusted_close) over a date range. It distinguishes from siblings like get_stock_price (single point) and get_pit_universe, making the 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?

Provides clear usage context: omit start_date for trailing year, omit end_date for latest close, explains coverage tiers. Lacks explicit alternatives for when not to use, but the description sufficiently guides typical usage.

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: the permission model (authors vs non-authors, sample-tier downgrades), which is crucial and not covered by 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 with information but every sentence serves a purpose. It is front-loaded with the core action, and no unnecessary words are present.

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

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

Despite the complexity of the tool (multiple format modes and permission rules), the description covers all necessary details: what it does, when to use alternatives, parameter semantics, and behavioral constraints. An output schema exists, so return values need not be described further.

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 meaning: it explains each format enum value ('rendered body', 'full structured payload', 'abstract-only') and specifies the origin of `report_id` (from `create_report` or `list_my_reports`). This goes 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 opens with 'Fetch the current HEAD of a report by id' – a clear verb+resource statement. It distinguishes itself from sibling `get_report_version` by explicitly noting that this tool is for the current version only.

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

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

The description provides explicit guidance on when to use this tool versus `get_report_version` for archived versions. It also details permission rules, making it easy for the agent to decide when this tool is appropriate.

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

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

Adds context beyond annotations: 'Author-only' (auth requirement), 'Returns metadata + the full payload... to render a diff'. Annotations already provide readOnlyHint, idempotentHint, destructiveHint.

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, zero waste. Front-loaded with purpose, then usage guidance, then return value. 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?

Complete for a 2-param tool with output schema. Covers purpose, usage sequence, auth, and return contents. 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 description coverage is 100% with good descriptions. Description adds minimal extra: 'by positive-integer version' and 'from list_report_versions', but 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?

Clear verb+resource: 'fetch of a specific archived version of one of your reports'. Distinguishes from siblings: 'for the current HEAD use get_report instead' and mentions list_report_versions.

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: 'Use after list_report_versions identifies the version number you want', and when not to: 'for the current HEAD use get_report instead'.

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 provides extensive behavioral details beyond annotations: it explains the four returned links with null conditions, the preference order for links, and that the tool is PIT-safe. It does not contradict any 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 well-structured and front-loaded with the core purpose. Every sentence adds value, covering return types, fallback logic, supported forms, and usage notes, 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 tool's complexity (multiple parameters, output schema), the description is complete: it explains return values, fallback logic, PIT-safety, and unsupported forms. The output schema exists but the description enriches understanding.

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 context beyond schema: it explains the preference order for URLs, enumerates form_types with notes, and clarifies event_types usage. This adds meaningful 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 starts with a clear verb+resource: 'Get direct links to original SEC EDGAR filings for any US public company.' It explicitly distinguishes from sibling tools like verify_fact_lineage, and provides specific details on the output links.

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: 'Use this *instead of* verify_fact_lineage when you want a list of filings; use verify_fact_lineage when you want one specific fact-to-filing trace.' It also notes unsupported form types and suggests alternative approaches.

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 (readOnly, idempotent, not destructive), the description reveals how each component is normalized and weighted, the lookback window, and crucially warns about the institutional component being top-5 matched filers. It also explains coverage confidence and staleness, adding significant behavioral context.

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

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

The description is dense but well-structured, starting with the core purpose and then drilling into details. Every sentence adds necessary information; however, the note about institutional component is quite long but essential.

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

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

For a composite tool with output schema present, the description covers the score range, component attribution, coverage metrics (confidence, staleness), limitations (directional rather than exact), and unitless nature. It is complete and self-contained.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds value by explaining the role of weights (defaults) and the interplay of aspects like lookback_days applying only to insider and blockholder components. Some redundancy exists but overall enriches understanding.

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

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

The description clearly states it produces a composite flow score within [-100, +100] by aggregating insider, institutional, and blockholder data. It explicitly lists the three components and their normalization, distinguishing it from sibling tools like get_insider_sentiment, get_institutional_holdings, etc.

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 this composite (e.g., for a holistic smart money flow signal) and notes critical caveats (e.g., directional signal, not exact flow, institutional component limitations). It lacks explicit 'when not to use' or direct alternatives, but the context is clear enough.

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