Valuein — SEC EDGAR Fundamentals & Smart-Money Data

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds auto-swapping with swapped flag, significance thresholds (minor <5%, notable 5-15%, significant >15%), material_changes count as triage scalar, and point-in-time semantics. No contradiction with annotations.

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

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

Four sentences that are front-loaded with main purpose, each sentence adds distinct information (significance, material_changes, period format, auto-swap, point-in-time). 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?

Complete for a comparison tool: covers input parameters, output semantics (significance, material_changes), edge cases (auto-swap on inversion), and safety feature (point-in-time). Output schema exists but description sufficiently explains key return elements.

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 for all 4 parameters. Description adds valuable context: format examples for period_a/b, explanation of auto-swap inversion logic, significance classification for output, and practical use of as_of_date for backtesting. Significantly enhances parameter understanding.

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

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

The description clearly states the tool compares core financial metrics across two periods side-by-side, with verb 'compare' and specific resource 'financial metrics across fiscal periods'. It distinguishes from sibling tools like get_company_fundamentals or get_financial_ratios by focusing on period comparison.

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: period format (FY2024, Q1-2024), order (period_a earlier, period_b later), auto-swap behavior, and point-in-time safety via as_of_date. Does not explicitly state when not to use or list alternatives, but guides correct 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, destructiveHint; description adds model details, input sources, fallback logic for shares, meaning of null value, traceability via inputs_echo, and non-persistence.

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 and well-structured, but slightly lengthy; however, every sentence adds value with 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 (8 parameters, output schema exists), the description covers model type, inputs, outputs, special cases, and alternatives, making it 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 has 100% coverage with descriptions; description adds meaning about model assumptions, relationship between parameters (e.g., WACC vs terminal growth), fallback for shares, and override behavior.

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 a forward DCF valuation using a two-stage Gordon growth model, returns per-share intrinsic value and sensitivity grid, and distinguishes itself from sibling tools like get_valuation_metrics and create_report.

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

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

Explicitly says when to use (when caller wants to drive assumptions) and when not (use get_valuation_metrics for pre-computed), explains null value meaning, and notes it does not persist a report.

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 alerts are persisted and registered, cron runs every 5 minutes, and delivery channels behave as described (email via Resend, webhook signed with HMAC-SHA256). Adds behavioral context beyond annotations (which only indicate write 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?

Concise and well-structured: begins with core purpose, then condition shapes, delivery channels, cron cadence, and sibling guidance. 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?

Comprehensively covers condition types, channel types, and cron schedule. References test_alert for verification. Output schema exists for return value, so that gap is acceptable. Missing details about response format but overall complete for a complex tool.

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

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

Schema covers all parameters (100%), but description adds concrete examples and explanations (e.g., 'email (transactional via Resend)', 'HMAC-SHA256-signed POST'). This enriches the schema descriptions with practical 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 clearly states 'Persist an alert and register it with the firing pipeline' and enumerates three condition shapes and delivery channels. Distinguishes from sibling test_alert by referencing it 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 context for when to use (e.g., create alerts with specific conditions) and explicitly advises using test_alert before relying on the cron. Lacks explicit when-not-to-use but gives sufficient guidance for agent choice.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds context: synchronous generation, persisting under caller's authorship, per-author state, and the snapshot behavior of thesis reports (no propagation). Adds meaningful behavior 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?

Well-structured with bullet points, front-loaded purpose, and subtype details. Slightly long but justified by complexity; no fluff. Minor improvement possible in brevity.

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, nested objects, output schema, and complexity, the description is thorough. It covers all necessary context: subtypes, required fields, behavioral nuances (non-propagating), and output format hints. Complete 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?

Input schema has 100% parameter descriptions. The description groups parameters by subtype (e.g., 'Reverse-DCF parameters'), clarifies requirements, and explains idempotency key semantics. Adds context not in 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 generates a research report and persists it under the caller's authorship, and distinguishes two subtypes (reverse_dcf and thesis) with specific details. This effectively differentiates it from siblings like compute_dcf or save_thesis.

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

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

The description provides clear guidance on when to use each subtype: reverse_dcf requires ticker+params, thesis requires thesis_id. It also notes that thesis edits do not propagate, implying when to regenerate. Could be more explicit about when not to use, but adequate.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context: soft-delete behavior, status flip, removal from cron evaluator, and immutability. 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 concise sentences with no fluff. The first sentence front-loads the main action and effect. Every sentence adds essential information.

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

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

With one parameter, good annotations, an output schema (not shown but present), and a description covering soft-delete, immutability, and tier, the tool's behavior is fully documented for agent use.

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

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

The single parameter alert_id is fully described in the input schema. The description reinforces that the ID comes from create_alert/list_alerts and adds behavioral context (soft-delete effect) that goes beyond the schema's parameter description.

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

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

The description clearly states the tool performs a soft-delete on an alert by its ID, flipping status to 'deleted' and removing it from the cron evaluator. It distinguishes itself from create_alert and list_alerts by specifying the source of the ID and the effect.

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 guidance on when to use the tool (to delete an alert) and indirectly explains that to change an alert, one must delete and then create a new one due to immutability. It also notes the tier restriction (sp500+ sample rejected), indicating usage scope.

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 details beyond annotations: idempotency behavior (deleting missing override returns deleted=false) and side effect (reports revert to canonical fact value on regeneration). This enriches the destructiveHint annotation with concrete consequences.

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

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

The description is three efficient sentences, front-loaded with the action, and includes key notes on idempotency and tier without redundancy.

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

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

For a single-parameter tool with full schema coverage, output schema, and annotations, the description covers effects on reports and idempotency, making it complete for an agent's 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%, and the schema already describes the fact_id parameter as returned by related tools. The description adds no additional parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool removes a user-authored citation correction by fact_id, differentiating it from save and list tools. The action and resource 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 implies when to use (to delete an override) but does not explicitly state when not to use or name alternatives like save_citation_override. It includes tier restrictions but lacks direct 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 destructiveHint=true and idempotentHint=true. The description adds context by specifying soft-delete behavior (archived, not erased), audit preservation, and impact on list_claims results. 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 (two sentences plus tier info), front-loaded with the main action, and every sentence adds value. 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?

The tool is simple with one parameter, and the explanation of behavior (soft-delete, idempotent, tier constraints) is complete. An output schema exists, so return values need not be described. The annotations cover safety aspects, making the description fully adequate.

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

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

The schema covers 100% of the single parameter with a clear description. The tool description does not add additional meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the action (soft-delete), the resource (claim), and the identifier (by id). It distinguishes soft-delete from hard delete by explaining that the row and score history are preserved for audit, and the claim drops out of default list_claims results.

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 tier restrictions (all paid + free tiers, sample rejected) and notes idempotency, implying use cases where idempotency is desired. However, it does not explicitly mention when not to use or provide alternatives among 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?

Description adds significant context beyond annotations: soft-delete specifics (delisted status, private visibility, 90-day audit window), idempotency confirmation, and sample tier rejection. Consistent with destructiveHint=true and idempotentHint=true annotations.

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

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

Three sentences front-loaded with core action, followed by idempotency and tier note. No unnecessary words.

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

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

Covers key aspects: soft-delete effect, idempotency, and tier restriction. Missing explanation of sample tier rejection and ownership enforcement, but output schema exists and tool is simple.

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 parameter description, including source of report_id. Description does not add extra parameter meaning beyond schema, achieving baseline for high schema coverage.

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

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

Description clearly states soft-delete for reports owned by caller, specifying effect (status flips to delisted, visibility private) and distinguishing from hard delete. Title reinforces 'Soft' delete, differentiating from sibling delete tools for other resources.

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

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

Implies usage for deleting own reports and mentions idempotency, but does not explicitly state when to use vs. alternatives like update_report or other delete tools. No exclusions or alternative tool names provided.

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

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

Adds context beyond annotations: explains soft-delete behavior (row stays for audit/re-scoring), idempotence, no effect on linked claims, and future expiration plans, complementing the destructiveHint and idempotentHint annotations.

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

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

Three sentences with no fluff, front-loaded with key info (soft-delete, idempotent), each earning 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, good annotations, and presence of output schema, description covers all necessary context: purpose, behavior, idempotence, relationship to other tools, and tier.

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

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

Schema has 100% coverage with description for thesis_id, but description adds value by specifying where the ID comes from (save_thesis or list_theses), aiding correct usage.

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

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

Description clearly states soft-delete with status change to 'archived', distinguishes from hard-delete and delete_claim for claims, providing a specific verb-resource pair with clear scope.

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

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

Explicitly says when to use (archiving theses) and when not (delete claims), mentions idempotence and future behavior, and includes tier info for access control.

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, describes soft-delete vs hard, idempotency, name reuse, and access restrictions. Adds value over annotations' destructiveHint 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?

Two concise sentences with no fluff, front-loaded with main action, secondary behavioral notes follow.

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 output schema and good annotations, description covers behavior, parameter, and post-conditions completely.

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

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

Schema description covers parameter name with case-insensitivity, length constraints, and purpose. Description adds 'by name (not id)' context. 100% schema coverage already strong.

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 a watchlist by name, flips status to archived, frees name for reuse. Verb+resource precise, distinguishes from siblings like 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?

Explains that archived watchlists are still readable via list_watchlists with status=all/archived, and name is freed for save_watchlist. Provides access tier info. Could explicitly 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?

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds that no data reads are required and the schema is embedded in the manifest, clarifying performance and cost implications. Also states availability on all plans.

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

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

Two sentences cover purpose and usage with no unnecessary words. Information is front-loaded and each 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 the presence of an output schema, the description need not detail return values. It covers purpose, usage, behavioral traits, and parameter effects adequately for a read-only schema 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%, but the description adds concrete examples ('fact', 'entity', 'references') and explicitly states behavior when the parameter is omitted. This adds useful context beyond the formal 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 the Parquet schema for all tables in the data warehouse, specifying the resource and action. It is distinct from sibling tools like 'search_filing_text' or 'get_sec_filing_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?

Explicit guidance to use this tool to understand the data model before querying. While no explicit alternatives are listed, the context implies it is the primary schema exploration tool.

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

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

Annotations already provide idempotentHint and destructiveHint. The description adds meaningful behavioral context: soft-delete behavior, setting dismissed_at, remaining queryable via list_alert_inbox(include_dismissed=true) for audit, and idempotency. This significantly enhances understanding 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 highly concise: two sentences covering all key points. Key information is front-loaded, and every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one parameter, no nested objects, annotations present), the description covers soft-delete behavior, auditability, idempotency, and tier. However, it does not mention the relationship to the sibling mark_inbox_read, which could provide additional context about alternate actions.

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

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

The single parameter inbox_id is fully described in the schema (100% coverage), but the description adds value by specifying the source (from list_alert_inbox) and clarifying it's not an alert id. This provides useful 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 tool soft-deletes a single inbox item by its id from list_alert_inbox, not an alert id. It specifies the action (soft-delete) and resource (inbox item), and distinguishes from sibling tools by clarifying it's not an alert id. This is specific and differentiates effectively.

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

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

The description implies usage for soft-deleting an inbox item and mentions idempotency and tier constraints. It does not explicitly contrast with siblings like mark_inbox_read, but clarifies the input type (not alert id), providing clear context for appropriate use.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds that it is deterministic, returns a ranked narrative with citations, and flags partial=true due to missing data. This goes 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 front-loaded with the core purpose and adds details about limitations and usage. It is concise but could be slightly tighter; each 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 complexity (forensic accounting), existence of output schema, and single parameter, the description fully covers what the tool does, its limitations (partial flag), and its use case. 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?

The single parameter ticker is well-described in the schema (length constraints, example). The description does not add additional semantic meaning for the parameter beyond the schema, but schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description 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. This is specific and distinguishes from sibling tools.

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

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

The description mentions it is used by the forensic_earnings_brief SOP, providing context. It does not explicitly list alternatives or when not to use, but the context is clear.

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

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

Annotations already indicate it is not readOnly nor destructive. The description adds value by detailing what the tool produces (Excel workbook with specific formatting) and how it achieves clean chart insertion. It does not contradict annotations and provides useful behavioral context beyond the structural fields.

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

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

The description is concise with three focused sentences covering purpose, technical highlight, pairing suggestion, and tier. Every sentence adds value without redundancy.

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

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

Given the presence of an output schema, the description adequately covers what the tool produces and key formatting features. It does not explain error handling or data format expectations, but for a generation tool it is sufficiently 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 all parameters described. The description does not add specific parameter details beyond the schema, aligning with the baseline of 3 for high coverage. It hints at the overall structure but does not enhance parameter understanding further.

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 peer comparables table into an Excel workbook with specific technical details (named Excel Table, subject-row highlight, Summary sheet with deltas). It effectively communicates the tool's core function and distinguishes it from siblings by mentioning pairing with get_peer_comparables for a typical flow.

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 suggests pairing with get_peer_comparables for a typical flow, providing clear context on when to use it. However, it does not explicitly state when not to use this tool or list 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?

Discloses key behaviors: native formatting, no chart images, returns a 15-minute presigned R2 URL. Annotations indicate it is not read-only or destructive. No contradiction, but could mention potential side effects like temporary storage or permissions.

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 two-paragraph structure: first paragraph states core function and features, second paragraph gives usage flow. No wasted words, front-loaded with key 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?

Covers main aspects: tool purpose, output format, typical pairing. With output schema present, no need to detail return values. Could mention error handling or prerequisites for dcf_result validity, but overall sufficient.

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 description adds workflow context by noting dcf_result typically comes from compute_dcf and explaining the optional company_name. Enhances understanding 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?

Description clearly states it renders a DCF result into a professional Excel workbook with specific sheets (Summary, Sensitivity heatmap, Inputs). It mentions native conditional formatting and returns a presigned URL, distinguishing it from sibling tools like compute_dcf and generate_comps_xlsx.

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

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

Explicitly pairs with compute_dcf and outlines a typical analyst flow, providing clear use context. Does not include negative guidance or alternatives for similar tasks, but the practical pairing is well explained.

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

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

Adds value beyond annotations by disclosing limitations (no charts, v1) and providing context about the output format (clickable SEC EDGAR links). Annotations already indicate non-destructive, non-idempotent behavior 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?

Three concise, front-loaded sentences that cover purpose, key constraints, and typical usage. Every sentence adds value; 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 7 parameters and an output schema, the description provides sufficient context about the tool's role in a workflow, its limitations, and what outputs to expect. It is complete for an agent to understand when and how to use it.

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

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

Schema coverage is 100%, but description adds meaning by explaining how parameters map to document sections (cover, abstract, snapshot, body, citations) and notes the compatibility with create_report output. This reduces cognitive load for agents.

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 renders a structured research brief into a Word document with specific components (cover, abstract, snapshot, body, citations). Distinguishes from siblings by mentioning pairing with generate_dcf_xlsx/generate_comps_xlsx for visuals.

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

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

Explicitly describes the typical flow (create_report → generate_research_brief_docx) and when to use alternatives (for visuals). Also notes limitations ('No embedded charts in v1'), guiding appropriate tool selection.

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

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

Annotations already indicate readOnlyHint=true. The description adds substantial behavioral detail: explains the going_active flag as an activist signal, mentions dedup logic for latest_only, and clarifies group handling with collapse_groups. 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 a single, dense paragraph of 4-5 sentences. It front-loads the purpose, then efficiently covers key parameters and the most notable feature (going_active). Every sentence adds value with no filler.

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

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

Given 7 parameters, 100% schema coverage, and an existing output schema, the description is complete. It covers the data source, key output fields, the most important flag (going_active), and parameter usage. 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 description coverage is 100%, but the description adds significant business context beyond the schema. It explains the importance of the 'going_active' detection, defines 'schedule_filter' values meaningfully (13D=activist, 13G=passive), and clarifies the effect of 'collapse_groups'. Exceeds baseline.

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

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

The title and first sentence clearly state it returns SC 13D/13G blockholder disclosures for US public companies. It distinguishes from sibling tools like get_insider_transactions or get_top_holders by specifying the 5%+ stake reporting and the unique 'going_active' flag.

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

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

Explicitly advises 'Institutional tier only' and explains when to use 'latest_only' and 'collapse_groups' parameters. Does not explicitly state when not to use this tool versus alternatives, but the sibling context and parameter descriptions provide implicit guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds crucial context: point-in-time safety via as_of_date, R&D semantics (informational, not double-counted), explanation of total_deployment_pct_ocf exclusion, and flag interpretations. No contradiction with annotations.

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

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

The description is front-loaded with the purpose, then systematically covers use cases, source, parameter semantics, R&D details, flags, and exclusions. While lengthy, every sentence adds value given the tool's complexity. Could be slightly tighter but appropriate.

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

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

The description covers use cases, data sources, parameter semantics, behavioral notes, flag interpretations, and limitations. With an output schema present, the description provides sufficient context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of as_of_date (eliminates look-ahead bias) and lookback_years default (full capital allocation cycle). It does not repeat schema descriptions.

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

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

The description clearly states 'Get a multi-year capital allocation breakdown for a US public company' and lists specific categories (capex, R&D, M&A, etc.) and ratios. It explicitly distinguishes from siblings by detailing its unique scope and use cases.

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 scenarios: 'how does a company allocate capital', 'buyback-vs-dividend mix', 'owner-earnings analysis', etc. It also mentions what is not yet included and suggests alternatives (e.g., 'request other_investing_outflows if needed').

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

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

Annotations already indicate readOnly and idempotent. The description adds valuable behavioral context about the returned data (theses IDs, append-only score history) and tier availability, without contradicting annotations.

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

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

Two focused sentences plus tier info. The first sentence captures the core functionality, the second explains usage. No extraneous content; every sentence serves a purpose.

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

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

Given the tool's simplicity (single parameter, output schema present, robust annotations), the description covers the essential aspects: what it fetches, what additional data it includes, and when to use it. No obvious 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% and the schema description for claim_id is adequate ('Id returned by save_claim or list_claims'). The description adds no additional parameter details, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool fetches a single claim by ID and specifies the additional data returned (theses IDs and score history), distinguishing it from sibling tools like list_claims and get_thesis.

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

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

The description provides a clear use case: 'inspect a claim's evidence, current status, and how its outcome has evolved.' It does not explicitly mention alternatives but the context 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying data source (SEC EDGAR 10-K/10-Q), point-in-time behavior, and that it returns raw line items. No contradictions.

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

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

Four concise sentences front-loaded with purpose, followed by metrics list, data source, and usage guidance. No wasted words; every sentence is informative.

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 complexity (8 params, output schema exists), the description covers purpose, data source, point-in-time, and sibling differentiation. Lacks mention of pagination or error cases, but overall sufficient for effective tool selection.

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 mentions as_of_date briefly but does not add new parameter information beyond what the schema already provides.

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

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

The description clearly states it retrieves standardized SEC EDGAR fundamental financial metrics for a US public company, lists specific metrics returned, and distinguishes itself from sibling tools like get_financial_ratios and get_valuation_metrics.

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

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

Explicitly guides when to use this tool versus alternatives: raw as-reported line items vs. ratios vs. valuation metrics. Also explains the point-in-time feature with as_of_date for backtesting, providing clear context.

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

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

Provides extensive behavioral context beyond annotations: current 501 response, private beta status, 15-minute URL expiry, and dataset-specific ticker requirements. Annotations already indicate read-only and idempotent, and the description adds significant operational detail.

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 somewhat lengthy but well-structured: status, future behavior, dataset list, expiry, and alternative. The critical information (current unavailability) is front-loaded, and every sentence serves a purpose.

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

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

Given the tool's current pending status and simple parameters, the description thoroughly covers behavior, dataset semantics, and a concrete workaround. The output schema exists, so return value details are appropriately delegated.

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 informative parameter descriptions. The description adds value by elaborating on each dataset type's content (e.g., 'ratio (all computed ratios)'), complementing the schema's enum definitions without contradicting them.

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 pre-signed Cloudflare R2 URL for bulk Parquet access, emphasizing high-throughput computation beyond MCP context window. It distinguishes from sibling get_* tools by highlighting bulk dataset access and explicit dataset types.

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 the current unavailability ('Calls return 501 FEATURE_NOT_AVAILABLE today') and provides a concrete alternative ('use the Python SDK...'). For future use, the description implicitly guides when to use this tool for bulk data processing.

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 idempotent and readOnly, which the description supports. The description adds critical context about the estimate's source and meaning, and confirms safety for backtesting. No contradictions with annotations.

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

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

The description is moderately long but front-loaded with key information. It uses 'IMPORTANT' to highlight a critical distinction. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (3 parameters, output schema exists), the description covers return fields, usage guidance, backtesting, and important caveats. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so parameters are already well-described. The description adds context about the output fields, but not much per-parameter detail beyond what's in the schema. A score of 3 reflects adequate but not exceptional added value.

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

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

The description clearly states the tool reports earnings results and a model-derived earnings-trend signal for a company by fiscal period. It distinguishes itself from siblings by focusing on earnings-specific data with a unique estimate.

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

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

The description clarifies that eps_trend_est is not analyst consensus but a model estimate from EDGAR, and advises using the tool to track trajectory/momentum rather than claim consensus beats. It also mentions point-in-time backtesting with as_of_date. However, it doesn't explicitly state when to avoid using this tool versus specific siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description goes far beyond by detailing point-in-time semantics (as_of_date behavior with accepted_at vs. period_end, _meta.pit_safe flags), pipeline recomputation (ON CONFLICT DO UPDATE), null value handling (reason field), and the CATEGORY_NOT_AVAILABLE envelope for missing categories. 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 long but well-organized: it starts with purpose, lists categories, adds caveats, then discusses filters, PIT, and sibling comparisons. Every sentence adds value, but some redundancy (e.g., repeated mention of 'valuation' not populated) could be trimmed. Front-loaded with the primary 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 tool's complexity (6 parameters, output schema exists, multiple edge cases), the description covers everything: available categories, missing category handling (CATEGORY_NOT_AVAILABLE), calendar alignment, point-in-time semantics, null reasons, lineage, and plan availability. 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 description coverage is 100%, but the description adds substantial extra meaning: it explains that `categories` must exclude 'valuation' because it is not yet populated, clarifies `as_of_date` PIT semantics, and identifies `period_end_before` as an alias. This enhances the agent's understanding 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 'Get pipeline-computed financial ratios from ratio.parquet,' clearly stating the verb and resource. It enumerates specific categories and distinguishes itself from siblings like 'get_valuation_metrics' (which includes DCF/DDM) and 'get_company_fundamentals' (for guaranteed accepted_at PIT). This provides unambiguous purpose and differentiation.

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

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

The description explicitly tells the AI when to use this tool vs. alternatives: 'Use this *instead of* `get_valuation_metrics` when you only need ratios (no DCF wiring); use `get_valuation_metrics` when you also need DCF/DDM.' It also advises using `get_company_fundamentals` for guaranteed accepted_at-based PIT. Additionally, it provides guidance on filtering `is_calendar_aligned` for joining with fact tables.

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 behavioral details: role weights, transaction neutralization, and cluster flag logic, which are 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 a concise paragraph that front-loads the main purpose (score on a fixed scale) and uses each subsequent sentence to add necessary detail without 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?

Given the output schema exists, the description sufficiently covers the tool's behavior: scale, weights, neutralization, and cluster flag. No major gaps remain for its intended use as a composite sentiment 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?

The input schema has 100% description coverage, but the description adds meaning by explaining how lookback_days and cluster_window_days are used in the sentiment calculation (e.g., lookback window for scanning, sliding window for cluster flag).

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

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

The description clearly states the tool computes a role-weighted insider sentiment score on a fixed [-100, +100] scale for a single issuer over a lookback window. It distinguishes itself from siblings like get_insider_transactions by being a composite score rather than raw 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 specifies 'Institutional tier only,' which is a usage constraint. It implies use for sentiment analysis, but lacks explicit when-not-to-use or alternative tools beyond what sibling names suggest.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds context about tier limitations and the effect of lineage_detail parameter, going 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 (3 sentences) with key information front-loaded (what the tool does, returns, and filters). No unnecessary words.

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

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

With 8 parameters, 100% schema coverage, and an output schema, the description fully covers necessary context including tier restrictions and filter 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 coverage is 100% with good descriptions. The tool description repeats some code explanations but does not add new meaning 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?

The description clearly states the tool returns Form 3/4/5/144 line items for US companies, specifying the included fields (insider name, role, transaction code, etc.). It distinguishes from siblings like get_insider_sentiment by focusing on raw transaction data.

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

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

Explicitly notes the institutional tier restriction and that lower tiers get ENTITLEMENT_DENIED. However, it does not directly tell when to use this tool versus related tools like get_insider_sentiment.

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: staleness_warning fires when data is older than 90 days, source (Form 13F-HR), ~45-day reporting lag, and partition details. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description enriches transparency.

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

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

The description is extremely concise: three sentences that front-load the core purpose, then add data source and staleness information. Every sentence adds value without redundancy.

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

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

Given the complexity (5 parameters, output schema exists), the description covers all necessary context: purpose, data source, parameter nuances, staleness warning, and reporting lag. It is sufficient for an agent to understand when and how to use the tool.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds meaningful context for parameters: it explains HHI concentration, the distinction between as_of_date and period_end, and the usage of as_of_date for backtests. This exceeds the baseline.

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

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

The description clearly states it returns top-N institutional holders of a US public company with aggregate metrics, sourced from Form 13F-HR via the by-issuer partition. It distinguishes from siblings like get_blockholders and get_top_holders by specifying 'institutional tier only' and the data source.

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 on when to use this tool (e.g., for institutional holdings data, with staleness_warning for old data) and explains the reporting lag. However, it does not explicitly state when not to use it or mention alternatives, though sibling names provide 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds detailed behavioral context: QoQ deltas, as_of_date as a point-in-time cutoff excluding amendments after that date, and error handling for ambiguous filer_name. 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 two sentences with clear structure: first sentence states core functionality, second provides parameter details. Every sentence adds value, no wasted words. Front-loaded with key purpose.

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

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

Given the tool's complexity (6 parameters, QoQ deltas, two date semantics, output schema exists), the description covers all necessary context: identifier options, date behaviors, error cases, and access restrictions. It is complete for an AI agent to understand when and how to invoke it.

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

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

Schema description coverage is 100%, and the description adds meaning beyond schema by explaining preferred identifier (filer_cik), fuzzy matching behavior of filer_name, and clarifying the role of as_of_date vs period_end. The description does not redundantly list parameter defaults.

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 portfolio at a specific period_end with QoQ deltas, specifying the resource, verb, and scope. It distinguishes from siblings like get_institutional_holdings by focusing on a single manager's portfolio with quarter-over-quarter changes.

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

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

The description provides usage guidance: prefers filer_cik over filer_name, explains that multiple filer_name matches raise an error, and notes the 'Institutional tier only' access restriction. However, it does not explicitly state when to use this tool versus alternatives like get_institutional_holdings.

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

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

Despite strong annotations (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral context: PIT semantics for as_of_date, the _meta.pit_safe flag explanation, and the note about peer selection being current regardless of date. No contradictions with annotations.

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

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

The description is relatively long but well-structured, front-loading the core purpose and then detailing method, categories, date behavior, and caveats. Every sentence adds value, though some details could be 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 (peer selection logic, PIT semantics, multiple categories), the description covers all necessary aspects. An output schema exists, so return values are not needed. The description is comprehensive and leaves no obvious 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 cross-tool context (as_of_date is canonical across time-series tools) and clarifies the period_end_before alias, enhancing understanding beyond the schema alone.

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

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

The description clearly states the tool retrieves ratio-based peer comparison for a company and its closest competitors, selected by 2-digit SIC code and S&P 500 membership. This distinguishes it from sibling tools like get_financial_ratios (single company) or get_company_fundamentals (fundamental data).

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

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

The description explains when to use this tool (benchmarking against peers) and includes limitations (peer selection uses current S&P 500 membership, not historical). It implies when not to use it (e.g., single-company ratios) but does not explicitly list alternatives, though context from sibling tool names 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?

Disclosures include survivorship-free construction, confidence levels, pit_safe meta, sector mapping caveats, and empty array on error. These add significant context beyond the annotations, which only declare readOnly/idempotent/destructive hints.

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

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

The description is thorough and well-structured, with front-loaded usage and detailed caveats. While not excessively long, there is minor redundancy (e.g., repeating 'survivorship-free'), but every sentence serves a purpose.

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

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

Given 7 optional parameters, no required params, full schema coverage, output schema, and rich annotations, the description fully covers edge cases (date out of range, low confidence, sample tier limits) and integrates with related tools.

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

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

Adds meaning beyond the 100% covered schema: explains index values in context, as_of_date semantics (join/leave intervals), as_of_basis (effective vs announcement with NULL handling), and include_share_classes (CIK dedup vs per-share-class). No parameter lacks explanation.

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: answering historical index membership questions, with specific examples like 'Was Company X in the S&P 500 on date Y?'. It distinguishes itself from the sibling tool 'search_companies' by noting that the latter only returns current snapshots.

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

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

Explicit guidance is provided: 'Use this INSTEAD OF `search_companies` when the question involves a specific historical date'. It also advises using it as the first step before `get_compute_ready_stream` and warns against setting `is_active=true` on historical queries due to survivorship bias.

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), description details format behaviors (markdown, json, preview) and access restrictions, adding significant 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 sentences, front-loaded with core purpose and format details, then access rules and disambiguation. No redundant 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 all aspects: purpose, parameter formats, access control, disambiguation, and behavior. Output schema exists, but description still adds value on return shapes.

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% coverage, but description adds meaning for format parameter by explaining exact return for each enum value, going beyond the schema's brief description.

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

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

The description starts with 'Fetch the current HEAD of a report by id,' which is a specific verb and resource. It clearly distinguishes itself from sibling get_report_version for archived 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 alternative tool ('For an archived prior version use get_report_version') and describes access control rules for authors vs non-authors and sample-tier downgrade.

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 beyond annotations by specifying 'Author-only' auth requirement and that returns metadata plus full payload for rendering diffs. Annotations already indicate readOnly=true and destructive=false, so the description complements well.

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, no filler, front-loaded with the core action. Every sentence adds essential 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 output schema is present, the description covers usage context, auth, return content, and sequential relationship to sibling tools. Fully complete for this tool's 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%, so baseline is 3. Description does not add substantial new parameter details beyond what schema provides, though it reinforces the integer constraint and linkage to list_report_versions.

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 fetches a specific archived version of a report, using a positive-integer version number. It distinguishes from siblings by noting it is for archived versions only, and contrasts with get_report for the current HEAD.

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 instructs to use after list_report_versions to get the version number, and to use get_report instead for the current HEAD. This 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?

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond annotations, such as PIT-safe filtering ('filings are filtered by accepted_at, never by report_date alone') and the distinction between sec_url and viewer_url. 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?

The description is relatively long but well-structured. It front-loads the main purpose, then sequentially covers links, supported forms, exclusions, filtering, PIT-safety, and usage guidance. Every sentence provides value, though minor consolidation could be achieved.

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

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

Given the tool's complexity (6 parameters, output schema present), the description is comprehensive. It covers supported forms, filtering options, what is not supported, and links to other tools. Since an output schema exists, return value details are unnecessary.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds extra meaning: it explains the difference between sec_url and viewer_url, lists supported form types, clarifies event_types filtering for 8-K, and notes default values. This enhances understanding, though baseline is already high.

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 function: 'Get direct links to original SEC EDGAR filings for any US public company.' It specifies what is returned (sec_url and viewer_url), lists supported form types, and explicitly excludes other forms, distinguishing it from siblings like verify_fact_lineage.

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 vs. alternatives: '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 advises confirming form availability via describe_schema.

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

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

Despite annotations already indicating read-only and non-destructive behavior, the description adds significant behavioral detail: composite score range, normalization and weighting per component, per-component attribution, the institutional component's matched top-5 basis, coverage confidence impact, and that the score is unitless. 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 thorough but efficient, with the main purpose front-loaded. Every sentence adds necessary context (methodology, limitations, coverage). Could be slightly more structured, but it avoids verbosity 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 composite nature, configurable weights, coverage metrics, and presence of an output schema, the description covers all essential aspects: score range, components, weighting, attribution, limitations, and coverage confidence. An agent can reliably understand the tool's behavior and constraints.

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

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

Schema coverage is 100% (baseline 3). The description adds value by explaining the default weights, the lookback window's scope (insider+blockholder), and the as_of_date's purpose (point-in-time cutoff). It also clarifies the institutional component's behavior beyond schema types.

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 a composite flow score on [-100, +100] aggregating insider transactions, institutional changes, and blockholder changes. It distinguishes itself from siblings like get_insider_transactions, get_institutional_holdings, and get_blockholders by being a composite. The verb 'get' and resource 'smart money flow' are specific.

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

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

The description explains when to use (to get a composite smart money score) and provides important caveats (directional signal, not exact flow, institutional limitation). However, it does not explicitly state when not to use or list alternatives for individual components, though it implies them by naming the sub-signals.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds specific error behavior (NOT_FOUND if id unknown or belongs to another user) and tier constraint, which is valuable beyond annotations.

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

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

Three sentences, each serving a distinct purpose: function, sibling guidance, and tier info. No extraneous words.

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

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

Given the simple one-parameter read-only tool with an output schema, the description covers purpose, error handling, and related tools. It is self-contained and sufficient for correct invocation.

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

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

Schema coverage is 100% with a clear description for thesis_id. The tool description adds context by specifying that the id is returned by save_thesis or list_theses, which helps the agent understand how to obtain the parameter value.

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

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

The description clearly states it fetches a single saved thesis by id, specifies the return content (full record with outcome if scored) and error case (NOT_FOUND). It also distinguishes from siblings like list_claims_for_thesis and get_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 provides when to use this tool versus alternatives: 'For the claims composing a thesis use list_claims_for_thesis; for an individual claim use get_claim.' Also mentions tier restrictions, guiding the agent on accessibility.

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 the annotations (readOnlyHint, idempotentHint, destructiveHint). It explains deduplication precedence (13D > 13G > institutional > insider), point-in-time cutoff semantics for as_of_date, and distinguishes period_end as a 13F reporting period parameter.

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

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

The description is two sentences, front-loaded with the core purpose. The first sentence defines the composite nature, the second adds deduplication and comparison to Bloomberg. Every sentence earns its place 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 rich annotations (readOnlyHint, idempotentHint), 100% schema coverage, and presence of an output schema, the description is complete. It covers the tool's purpose, parameters, and key behavioral nuances, enabling an AI agent to use it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the as_of_date parameter's point-in-time behavior across all sources, that omitting it gives the latest knowable cap table, and the distinction between as_of_date and period_end. This enriches the schema descriptions.

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

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

The description clearly states that the tool returns a 'classification-aware UNION across insider transactions, 13F institutional holdings, and SC 13D / 13G blockholder filings for one issuer.' It uses specific verbs and resources, and distinguishes itself from siblings by noting it consolidates data that Bloomberg charges separately for.

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

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

The description implies when to use this tool (when a consolidated cap table with holder classifications is needed) and contrasts it with Bloomberg's separate screens. However, it does not explicitly mention alternatives among sibling tools like get_blockholders or get_insider_transactions, nor does it state when not to use this tool.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint, but the description goes beyond by explaining data sources (fact.parquet vs valuation.parquet), null handling with null_reasons, and the non-PIT-safe nature of DCF fields. 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 and front-loaded: main purpose, data sources, null handling, and usage alternatives. Every sentence adds value without redundancy. Length is appropriate for the tool's complexity.

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

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

Given the tool's complexity, the presence of an output schema, and annotations, the description is complete. It covers data source reliability, null value interpretation, and provides fallback guidance. No gaps for an agent to misuse 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 description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema's parameter descriptions. While it mentions that DCF fields are often null, this is behavioral context rather than parameter-specific; overall, the schema already adequately documents 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 starts with 'Get comprehensive valuation and profitability metrics for a US public company,' clearly stating the verb (get), resource (metrics), and scope (US public company). It explicitly differentiates from sibling tool get_financial_ratios by specifying 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?

The description provides explicit guidance: use this tool instead of get_financial_ratios when DCF/intrinsic value matters, and use get_financial_ratios for ratio-only needs. It also advises using the SDK or get_company_fundamentals for strict PIT DCF reasoning, offering clear 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 readOnlyHint=true and destructiveHint=false. Description adds that it returns full ticker set+criteria, specifies NOT_FOUND error, and tier restriction. Provides additional behavioral context: case-insensitive lookup and name-based retrieval. Could also mention if it returns anything else.

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, no filler. Front-loaded with purpose, then error and tier info. Each clause adds essential detail.

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

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

For a simple read tool with one parameter, description covers purpose, method, error behavior, and access restrictions. Could mention if output schema is paginated or has limits, but not necessary. Annotations and schema cover the rest. Nearly 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 covers parameter fully with description. Description in tool description also reiterates 'by its name (case-insensitive)'. No new semantic info beyond schema, but consistent. 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 'Fetch a single watchlist' by name (not id), case-insensitive, with error behavior and tier restriction. Differentiates from list_watchlists and save_watchlist implicitly.

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

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

Gives explicit usage by name (case-insensitive), error behavior, and tier restriction. Lacks explicit mention of alternatives like list_watchlists but implicitly distinguishes. Could be improved with direct reference to list_watchlists for name discovery.

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, the description adds valuable behavioral details: idempotency details (re-linking updates role), independence of scoring, and tier restrictions ('paid + free (sample rejected)'). 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: three sentences covering purpose, idempotency, role semantics, and scoring independence, plus a final sentence on tier. 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?

For a tool with 3 parameters, simple operation, and existing output schema, the description fully covers behavior, idempotency, role meaning, scoring context, and tier. 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% with basic descriptions. The description enriches the 'role' parameter by explaining each enum option ('supports', 'refutes', 'context') with behavioral semantics. Does not add detail for claim_id and thesis_id beyond schema, but role explanation 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 action: 'Attach a claim to a thesis with a role'. It specifies three possible roles and explains their meanings, distinguishing from sibling tools like unlink_claim_from_thesis and score_thesis by noting idempotency and independence of scoring.

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 usage, such as idempotency (re-linking updates role) and the independence of claim and thesis scoring. It does not explicitly list alternatives but implies when to use via differentiation from scoring tools. No explicit when-not scenarios, but the context 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?

Annotations already indicate readOnly, idempotent, non-destructive. The description adds transparency about cursor-pagination by fired_at, default filter behavior, and paid-tier restriction. No contradictions. Adds value beyond annotations, though could mention rate limits or auth scope.

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 concise sentences: first defines core purpose and scope, second adds differentiation and pagination details, third notes tier restriction. No wasted words, efficiently 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?

Covers purpose, usage, parameters, pagination, default filters, sibling comparison, and tier restriction. Output schema exists, so return values are handled. Complete for a read-only paginated list tool with good annotations.

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

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

Schema coverage is 100% with all parameters described. The description does not add meaning beyond the schema except implicitly confirming cursor relates to fired_at. Baseline 3 is appropriate as schema already fully defines 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 it lists the caller's in-app alert inbox in newest-first order, specifies each item is a single FIRE of an alert with a 'dashboard' channel, and distinguishes from list_alerts which returns alert definitions. This provides a specific verb and resource, effectively differentiating 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 tells when to use list_alerts instead (for alert definitions), notes default behavior (dismissed hidden, read included), mentions cursor-pagination by fired_at, and that alerts are a paid-tier feature. Provides clear usage 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?

Discloses pagination, newest-first ordering, filterable status, and returned fields. Annotations already indicate read-only, idempotent, non-destructive; description adds no contradictions and complements well.

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-loading key information. No redundant filler.

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

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

Given full input schema and output schema present, description covers pagination, filtering, and downstream usage. No missing context for correct 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 covers 100% of parameters. Description adds value by explaining how cursor ties to pagination and that 'all' includes soft-deleted. Reinforces status filter but doesn't add 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?

Clearly states it lists the caller's alerts with pagination, newest-first, and specific fields. Distinguishes from sibling tools like delete_alert, test_alert by mentioning returned id usage.

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 filter by status and directs to use returned id with delete/severity operations. Mentions tier restriction (sp500+) but lacks explicit when-not-to-use scenarios.

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 that listing is author-only and newest-first, and that fact_id returns 0 or 1 row, providing useful context beyond annotations.

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

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

Two paragraphs with front-loaded purpose and filter info. The phrase 'Sample tier rejected' is cryptic but not misleading. Overall efficient and well-structured.

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

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

Given output schema exists and annotations cover safety, the description covers listing, filters, pagination (via cursor), pairing with other tools, and a practical agent use case. No gaps.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning by noting ordering (newest-first), case-insensitive ticker filter, and fact_id returning at most one row, plus a concrete use case for the ticker parameter.

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

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

The description clearly states 'Author-only newest-first listing of the caller's citation corrections' with filter options by ticker or fact_id. It distinguishes from siblings by mentioning pairing with save and delete overrides.

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

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

Description provides a specific use case: 'call with ticker to introspect what corrections the user has previously applied on that ticker'. It also pairs with save/delete tools but doesn't explicitly exclude other scenarios.

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, non-destructive), description discloses critical behavior: sorting order, AND-composed filters, cursor pagination, archived exclusion logic, and tier access. 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 dense sentences with no redundant words; front-loads the core action and filters. Tier note is succinctly appended.

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 7 parameters, output schema exists, and annotations cover safety, the description sufficiently covers purpose, filtering, pagination, and tier constraints. No gaps for typical 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 already describes all parameters (100% coverage). Description adds overarching context about AND-composition and the default exclusion of archived claims, providing slight extra value.

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

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

Clearly states action (list), resource (caller's saved claims), and key features (most-recent-first, AND-composed filters, cursor pagination). Distinguishes from siblings like list_claims_for_thesis and list_public_claims_by_user by specifying ownership.

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?

Describes filtering capabilities and tier restrictions, which guide when it's applicable. However, lacks explicit 'when to use vs not use' statements or alternatives, leaving the agent to infer from context.

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

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

Beyond annotations (readOnlyHint=true, destructiveHint=false), the description adds that archived claims are omitted and mentions a tier restriction. 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.