Valuein — SEC EDGAR Fundamentals & Smart-Money Data

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

The description elaborates on annotations (idempotent, destructive, open-world) with specific behaviors: never re-executes an action already decided, returns executed_now flag, tool_result structure, failure handling, and ownership non-leakage. 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. Every sentence provides essential information without redundancy. It efficiently covers purpose, behavior, edge cases, and security.

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

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

Given the tool's complexity (approval with execution, idempotent, destructive), the description covers all necessary aspects: return values, error handling, security, and tier restriction. It is complete 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?

The single parameter staged_action_id is fully described in schema with source references. The description adds context about ownership security and usage, enhancing understanding beyond schema.

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

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

The description clearly states that the tool approves a staged action and executes the underlying tool call using the caller's credentials. It distinguishes from siblings like stage_action and reject_staged_action by specifying the approval and execution behavior.

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

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

The description provides comprehensive guidelines: when to use (to approve and execute), idempotency and race-safety, handling of already decided actions, failure of underlying tool, ownership privacy, and tier restriction. It implicitly suggests not to use when the action is already decided.

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 idempotency (cancelling an already-cancelled task is a no-op) and the condition that completed tasks cannot be cancelled. This adds context beyond the idempotentHint and destructiveHint annotations. Also mentions tier restriction, which is extra behavioral context.

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

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

Three concise sentences covering purpose, constraint, and behavioral traits. No unnecessary words, and the most critical information is front-loaded.

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

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

For a simple tool with one parameter and an output schema, the description covers purpose, constraint, idempotency, and access tier. It is complete and well-aligned with the tool's simplicity.

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 parameter 'task_id' is described in the schema as 'Identifier of the scheduled task to cancel.' The tool description adds that it comes from schedule_task or list_scheduled_tasks, providing source context that enhances the schema definition. Since schema coverage is 100%, baseline is 3; the added value raises it to 4.

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

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

The description clearly states 'Cancel a pending scheduled task by id', specifying the verb (cancel), resource (scheduled task), and scope (pending). It also distinguishes from sibling tools like schedule_task and list_scheduled_tasks by indicating the source of the ID.

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

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

Explicitly states that only a 'pending' task can be cancelled, providing context on when it's applicable. However, it does not explicitly mention when not to use it or give alternatives, though the constraint 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?

The description adds significant behavioral context beyond annotations: auto-swapping periods when inverted, significance thresholds (minor <5%, notable 5-15%, significant >15%), and the material_changes scalar for triaging. Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description aligns with these.

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, starting with the main purpose and then providing detailed usage instructions. Every sentence adds value, though a slight trimming could improve conciseness.

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 and the presence of an output schema (stated in context), the description fully explains return values (material_changes, significance, auto-swap flag) and point-in-time execution. It covers all necessary aspects 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 coverage is 100% with parameter descriptions. The description adds extra semantics: auto-swap behavior if periods are inverted, significance classification, and how to interpret material_changes. These go beyond the schema's basic format requirements.

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

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

The description clearly states the tool compares core financial metrics across two fiscal periods side-by-side, with absolute and percentage changes and significance classification. It distinguishes itself from siblings like get_financial_ratios by focusing on period comparison rather than static ratios.

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

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

The description provides explicit usage guidance: period format ('FY2024' or 'Q1-2024'), ordering (earlier period first), and triaging via material_changes count. It also mentions point-in-time safety but does not explicitly state when not to use this tool or list alternatives.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, but the description adds significant context: what data it pulls (net income, shares outstanding, prices), how consideration mix works, and what is excluded. There is no contradiction, and the description enriches the agent's 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 concise yet packed with essential details. It front-loads the core purpose, uses formatting (CAPS for emphasis) to highlight key limitations, 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 complexity (11 parameters, output schema present), the description is comprehensive. It explains inputs, outputs (accretion_dilution_pct), caveats, and limitations. The output schema covers return values, so additional detail is 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 coverage is 100%, but the description adds meaning beyond the schema by explaining how each parameter is used (e.g., price converts stock consideration, target price for premium disclosure). It clarifies defaults and dependencies, making parameter semantics clearer.

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 M&A accretion/dilution for a single pro-forma year, distinguishing it from multi-year merger models. It uses specific verbs and resources (quickscreen, EPS impact) and explicitly contrasts with more complex tools.

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

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

The description provides explicit guidance on when to use (standard sell-side/banker quickscreen) and what not to model (synergy ramp, integration costs, PPA amortization). It also points to caveats in the result, helping the agent decide when this tool is appropriate.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds critical details: null value_per_share_cents means degenerate model (not zero), shares source fallback chain, fcf_source behavior (ignores stage1_growth_rate in three_statement mode), and that inputs are echoed with lineage for reproducibility.

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 lengthy but well-structured: core purpose first, then parameter details, then usage guidelines. Every sentence adds information. Could be slightly more concise, but no wasted words.

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

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

Given the tool's complexity (10 parameters, nested objects, two modes), the description covers key aspects: fcf_source behavior, share fallback, null output meaning, and references to related tools. Output schema exists (implied), so return values are presumably documented. Lacks explicit tie to project_three_statement's defaults.

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 behavioral semantics beyond schema: explains fcf_source modes in detail, notes that stage1_growth_rate is ignored in three_statement mode, and clarifies three_statement_assumptions object overrides. This adds significant 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 computes a forward DCF valuation using a two-stage Gordon-growth model, returns per-share intrinsic value and sensitivity grid. It distinguishes from sibling tools like get_valuation_metrics and create_report, specifying when each should be used.

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 this tool: when you want to drive assumptions yourself. Provides clear alternatives: use get_valuation_metrics for pre-computed DCF, use create_report to persist a reverse DCF report. Also explains when not to use it.

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

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

The description extensively discloses behavioral traits beyond annotations: it explains that EBITDA is proxied by operating income unless overridden, describes the IRR convergence process, notes the cash sweep default, and lists caveats in the result. This adds significant value beyond the readOnlyHint 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?

The description is well-organized and front-loaded with the core purpose. Every sentence contributes meaningful detail, though it is longer than strictly necessary. It balances completeness with readability.

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

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

Given the tool's 13 parameters, complexity, and the presence of an output schema (implied by result fields mentioned), the description is remarkably thorough. It covers edge cases (e.g., convergence failure, EBITDA proxy), making the tool's behavior fully predictable without external references.

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 baseline 3. The description adds extra meaning by explaining relationships between parameters (e.g., entry_debt = leverage_multiple × EBITDA) and the EBITDA proxy mechanism, which is not detailed in the schema. This enhances understanding beyond the parameter descriptions.

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

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

The description clearly states the tool computes LBO returns (IRR and MOIC) by building a pro-forma balance sheet and projecting financials. It distinguishes itself from siblings like compute_dcf and project_three_statement through its specific focus on leveraged buyout analysis.

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 what the tool does and how to invoke it but does not explicitly state when to use it over alternatives such as compute_dcf or generate_lbo_xlsx. Usage context is implied but lacks direct guidance on tool selection.

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

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

Beyond annotations (readOnlyHint=false), the description adds context about the cron evaluator running every 5 minutes, condition types, and delivery channels. No contradictions detected.

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

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

The description is well-structured, starting with purpose, then listing condition shapes and delivery channels in a clear, scannable format. Every sentence adds value, and it is appropriately sized for the complexity.

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

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

Given the tool's complexity (multiple condition types, channels, Pro+ features), the description covers all necessary aspects, including cron timing and testing suggestions, making it fully informative for an agent.

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 high-level context and examples (e.g., 'interest_coverage < 1.5') and mentions the cron interval, providing additional meaning beyond the schema.

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

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

The description clearly states the purpose with 'Persist an alert and register it with the firing pipeline.' It then enumerates condition shapes and delivery channels, distinguishing it from sibling tools like test_alert and list_alerts.

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

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

The description explicitly suggests using test_alert to verify channel wiring before relying on cron, providing a clear usage guideline. However, it does not explicitly state when not to use this tool (e.g., for updating alerts), 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?

Beyond annotations (idempotentHint=true, readOnlyHint=false), the description adds significant behavioral context: synchronous generation, persistence, author attribution, and the fact that thesis reports are frozen snapshots. It also describes the idempotency_key for at-most-once semantics.

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

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

The description is well-structured with bullet points for subtypes and front-loaded with the core purpose. It is fairly concise, though some phrases like 'per-author state' and 'caller's authorship' overlap slightly. Overall, it is efficient and easy to scan.

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

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

Given the complexity (6 parameters, 2 subtypes, nested objects) and the presence of an output schema, the description covers all necessary aspects: it explains both subtypes, their required inputs, output characteristics (markdown + JSON + citation chain), and behavior regarding thesis updates. The absence of output schema details is justified by the existence of a separate output schema.

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

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

Schema coverage is 100%, and the schema already provides descriptions. The tool description adds value by explaining how report_type determines which parameters are required and by clarifying the purpose of the nested params object. However, the description could further detail constraints like max length or allowed values.

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 synchronously generates and persists a research report under the caller's authorship. It distinguishes two subtypes ('reverse_dcf' and 'thesis') with detailed explanations, making the tool's purpose specific and distinguishable from siblings like 'save_freeform_report' or 'render_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?

The description provides explicit when-to-use guidance for each subtype, listing required parameters. It mentions that edits to a saved thesis do not propagate and recommends generating a new report to capture changes, implying when not to reuse. However, it does not directly contrast with sibling tools like 'compute_dcf' or 'save_freeform_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?

The description discloses significant behavioral traits beyond annotations: it explains that certain triggers are persisted but don't fire due to no live source, specifies that condition_expr is purposely not a general expression language (anti-complexity/anti-loop guard), and mentions the trigger_wiring_status field in the response. Annotations only show readOnlyHint=false, so the description adds critical context.

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

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

The description is dense with information but slightly lengthy; it could be structured with bullet points for readability. However, every sentence provides value, and it is front-loaded with the main purpose. Minor improvement could enhance scanability, but it is not overly verbose.

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 (4 parameters with many subtypes), the description covers edge cases (non-wired triggers, condition_expr limitations), suggests testing, and mentions the trigger_wiring_status output field. It also includes tier information. With an output schema present, the description adequately covers what the agent needs to know.

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: it explains the condition_expr format ('field op value', ops list), clarifies that it's optional, and elaborates on the action and trigger unions by listing all type combinations and highlighting working triggers. This goes beyond the schema's enum constraints.

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

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

The description clearly states the tool's purpose: 'Persist a trigger -> action rule and register it with the evaluator.' It enumerates all 7 trigger types and 6 action types, and distinguishes itself from sibling 'test_rule' by mentioning it for verification. The verb 'create' and resource 'rule' are explicitly defined.

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: it warns that only four trigger types actually dispatch today and advises using 'test_rule' to verify firing without real dispatch. It also flags that price_threshold, filing_event, and manual triggers are accepted but have no live event source, and suggests checking trigger_wiring_status. This covers when-not-to-use 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?

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds that it is a soft-delete (not permanent), flips status, removes from index, and that alerts are immutable. The tier note is unclear but does not contradict. Overall adds meaningful 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?

Three sentences, no fluff. The first sentence front-loads the core action and effect. Every sentence serves a purpose: action, modification pattern, and idempotency/tier.

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

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

For a simple tool with one parameter and annotations, the description covers the action, behavioral details, and usage pattern. It does not explain return values or error cases, but an output schema exists (not shown) which likely covers that. The tier note is cryptic but does not detract from completeness.

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

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

Schema coverage is 100% and the schema parameter description already states 'Identifier of the alert to soft-delete, as returned by create_alert or list_alerts.' The description's mention 'by its id (from create_alert/list_alerts)' adds little new semantic meaning beyond the schema.

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

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

The description clearly states 'Soft-delete an alert by its id' and explains the effect (status flips to deleted, removed from cron evaluator). It distinguishes from siblings like create_alert, list_alerts, and test_alert by specifying the action and providing an alternative for modification.

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

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

The description explicitly states the tool is for soft-deleting alerts using an id from create_alert or list_alerts, and provides an alternative usage pattern for modification: 'to change one, delete then create_alert'. It also notes idempotency, guiding safe usage.

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

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

The description explains the idempotent behavior and the consequence of deletion on reports, which adds significant value beyond the annotations. Annotations declare destructiveHint=true and idempotentHint=true, and the description elaborates on these.

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

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

The description is two sentences plus a tier note, all informative and non-redundant. It is front-loaded with the main action and quickly covers behavior and constraints.

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

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

Given the simplicity of the tool (1 parameter, output schema present, annotations provided), the description covers all necessary aspects: purpose, idempotency, side effects, and access 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 coverage is 100% with a clear description for fact_id. The tool description does not add additional parameter context, but given high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the action ('Remove') and the resource ('user-authored citation correction') and specifies the identifier field ('fact_id'). It distinguishes this from sibling tools like save_citation_override and list_citation_overrides.

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

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

The description provides usage-relevant details such as idempotency and the tier restriction ('paid + free (sample rejected)'). While it doesn't explicitly state when to use this tool over alternatives, the context is clear given the sibling tools.

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

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

Description adds important behavioral context beyond annotations: it explains soft-delete semantics, audit preservation, idempotency, and default visibility change, all aligning with 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?

Three sentences, front-loaded with the key action, and no unnecessary words. Every sentence adds value.

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

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

Given the output schema exists, the description covers all necessary behavioral aspects: idempotency, audit preservation, visibility changes, and tier restrictions. It is complete for guiding appropriate 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?

Schema coverage is 100% and the parameter description is already clear. The tool description does not add additional meaning to the parameter beyond what the schema provides.

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

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

Description clearly states the tool soft-deletes a claim by ID, explaining what that means (archived, not erased, drops from default results). It distinguishes from hard deletes and sibling tools 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?

Description explains when to use (to soft-delete a claim) and includes tier restrictions. However, it does not explicitly state when not to use or mention alternatives for permanent deletion.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description adds specific details: soft-delete mechanism, 90-day audit window, and the fact that the row and R2 artifact are preserved. This provides valuable context for the agent's decision-making.

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 long, front-loaded with the key action and effects, and every phrase contributes useful information. No redundant or vague language.

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

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

With an output schema present, the description focuses on behavior rather than return values. It covers idempotency, preservation window, and ownership requirement. It could mention error conditions (e.g., if report not owned) but overall is sufficient for the complexity.

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

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

The schema already provides 100% coverage of the single parameter 'report_id', including its source (from create_report or list_my_reports). The description does not add additional semantic meaning beyond what the schema offers, 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 performs a soft delete, specifying the exact status and visibility changes ('status flips to `delisted`, visibility to `private`') and emphasizes it is not a hard delete. This distinguishes it from other delete tools like delete_alert or delete_claim, and from unpublish_report, by detailing the preservation behavior.

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

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

The description mentions 'owned by the caller' and 'idempotent', which provides some context, but it lacks explicit guidance on when to use this tool over alternatives like unpublish_report or when a hard delete might be needed. No exclusions or alternatives are named.

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

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

Beyond annotations (destructiveHint=true, idempotentHint=true), description details what is destroyed (catalog and scan index) and that it stops firing immediately. Also discloses tier restriction 'sp500+ (sample rejected)' which is critical for access control.

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 brief sentences, each valuable: action and effect, immutability guideline, then idempotency and tier. No wasted words, front-loaded with the core 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 a simple single-parameter tool with output schema, the description covers all essential aspects: effect, usage pattern, idempotency, and authorization tier. No gaps remain.

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 sole parameter rule_id is fully described in the schema, but the description adds context: 'by id (from create_rule/list_rules)' indicating where to obtain valid IDs. This is helpful beyond the schema's basic 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 it deletes a rule by ID and specifies it removes from catalog and scan index, stopping firing immediately. It references sibling tools (create_rule/list_rules) for source of ID, distinguishing it.

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 (to delete a rule by ID) and provides alternatives: 'Rules are immutable — to change one, delete then create_rule.' Idempotency hint also guides retry behavior.

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 explains that the operation is a soft-delete (status change to archived), idempotent, and does not delete linked claims. It aligns with annotations (destructiveHint, idempotentHint) and adds context about future expiration.

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 comprehensive yet efficient, with each sentence adding value. It is front-loaded with the key action and status change. Slightly longer than necessary but well-structured.

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

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

Given the simple parameter set (1 param) and presence of an output schema, the description covers all needed context: behavior, idempotency, limitations, alternatives, and future plans.

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 `thesis_id` is described in the schema as 'Id returned by `save_thesis` or `list_theses`.', which is clear. The description adds no additional parameter info, but with 100% schema coverage, baseline is 3; the slight improvement comes from the schema description itself being helpful.

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: 'Soft-delete a saved thesis: status flips to `archived`'. It distinguishes from siblings by noting that it does not delete linked claims (use `delete_claim`) and that hard-delete is not supported.

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: when to use (archiving a thesis), when not to use (for claims), and notes idempotency. It also mentions tier restrictions ('paid + free (sample rejected)').

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 show destructiveHint=true and idempotentHint=true. The description adds valuable behavioral details: deleting a missing/already-expired/foreign id returns deleted:false instead of an error. No contradiction with annotations.

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

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

Two concise sentences with no wasted words. The first sentence states purpose and timing, the second clarifies error handling.

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 behavior. Low parameter count and high schema coverage mean no gaps.

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

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

Schema description coverage is 100% (upload_id described). 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 action 'Delete' and the resource 'uploaded document'. It distinguishes from sibling delete tools by specifying the resource type and includes the time constraint (before 24h TTL). The edge-case behavior (returns false for missing/expired/foreign) further clarifies the scope.

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

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

The description explicitly guides when to use the tool (before TTL) and explains non-error behavior for invalid IDs. It does not mention when not to use alternatives, but the context is sufficient for an agent to decide.

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

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

Annotations indicate destructiveHint=true and idempotentHint=true. The description adds significant behavioral detail: it's a soft-delete (not hard delete), status becomes 'archived', the name is freed for reuse, and it's idempotent. 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 with additional tier note), front-loaded with key actions, and every sentence adds value. No superfluous 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 that an output schema exists (not shown but indicated), the description covers all necessary behavioral aspects: the effect on watchlist status, name reuse, idempotency, and access restrictions. It is complete for a simple deletion tool with few parameters.

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

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

Schema coverage is 100% for the single parameter 'name'. The description adds meaning beyond the schema by specifying case-insensitive matching and that the name is freed for reuse. While the schema already describes length constraints, the description clarifies the behavioral effect on name availability.

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

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

The description clearly states that the tool soft-deletes a watchlist by name (not ID), flips its status to archived, and frees the name for reuse. It distinguishes itself from siblings like list_watchlists and save_watchlist by explicitly noting that the deleted watchlist remains readable via list_watchlists with status=all/archived.

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

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

The description explains when to use this tool (for soft-deletion), its idempotency, and a tier restriction (sp500+). It doesn't explicitly state when not to use it (e.g., for permanent deletion), but the context of 'soft-delete' and mention of list_watchlists for reading archived items provides indirect 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. Description adds that no data reads are required and it's available on all plans, which is 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?

Three concise sentences, front-loaded with core function, usage guidance, and additional behavioral context. No wasted words.

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

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

Given the tool has an output schema, the description does not need to explain return values. It covers purpose, usage, parameter semantics, and behavioral traits comprehensively for a simple tool.

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

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

Schema coverage is 100% and the description adds meaningful context: filtering to a single table name with examples and noting omission returns full 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 it returns the Parquet schema for all tables, including table descriptions, column names, types, primary keys, and foreign-key references. It distinguishes itself from sibling tools as the only schema exploration tool.

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 using this tool to understand the data model before querying with other tools. Does not include 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?

Discloses soft-delete behavior, setting of 'dismissed_at', and idempotency. Annotations already indicate destructive hint and idempotent hint; the description adds that the effect is a soft-delete and the row is still queryable for audit.

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

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

Two sentences pack all essential information without redundancy. Front-loaded with the core action and parameter, followed by idempotency and tier note.

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

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

For a single-parameter, soft-delete tool with a clear schema and accompanying output schema, the description covers everything needed for correct invocation and understanding of side effects.

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 already covers the parameter meaning. The description restates the source of the id, but adds no additional semantics beyond the 100% coverage schema. Baseline 3 is appropriate.

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

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

Clearly states the action ('soft-delete'), the resource ('single inbox item'), and the required identifier ('by its id from list_alert_inbox'). Explicitly distinguishes from an alert id, clarifying what the tool does not do.

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 instructions on where the id comes from and that the row remains queryable with a flag. Mentions idempotency and a tier constraint, but does not explicitly compare to sibling tools or state when not to use.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that it is deterministic, returns a red-flag narrative with citations, and flags partial=true due to data limitations—transparent about constraints.

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 purpose: what it computes, limitations/flag, and usage context. Front-loaded and 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 the output schema exists, the description sufficiently covers purpose, limitations, and usage context. No gaps for a single-parameter 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?

The schema already provides a good description for the single parameter (ticker). The tool description does not add further meaning beyond stating what the tool does with the ticker.

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

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

The description clearly states the tool computes deterministic forensic-accounting scores (partial Beneish, Sloan, solvency) for a single ticker, and distinguishes it from siblings which are general CRUD or other financial analysis 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?

It mentions it's used by the forensic_earnings_brief SOP, providing context for when to use. However, it lacks explicit when-not-to-use guidance or alternatives beyond mentioning the partial nature.

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 provide minimal info (readOnlyHint=false, etc.). The description adds significant behavioral context: the tool is not read-only (it creates a file), not destructive, but most importantly it discloses that the workbook carries a watermark and verification status is 'unverified' because ratios are not re-derived. This goes well 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 separation into 'what it does', 'trust note', and 'usage pairing'. The first sentence is front-loaded with the key purpose. Could be slightly more concise, but every sentence adds value.

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

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

Given the tool's medium complexity (hierarchical array input, absence of output schema in the input, but output schema exists), the description covers the output characteristics (named table, summary sheet, watermark) and provides enough context for the agent to understand what the tool produces and when to use it.

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

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

Schema covers 100% of parameters with descriptions, so the bar for extra value is high. The description adds context: `notes` is rendered on Summary sheet, `subject_ticker` is used for subject-row highlighting, and the `peers` array is described as 'tabulated against the subject.' This enriches parameter 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?

The description clearly states the purpose: 'Render a peer comparables table into an Excel workbook.' It specifies the exact resource (Excel workbook) and action (render/generate), and distinguishes from sibling tools like `generate_dcf_xlsx` by mentioning the specific content (comps, summary sheet, watermark).

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: 'Pair with `get_peer_comparables` for a typical flow' and 'For authoritative numbers, source them from `get_peer_comparables` / `get_financial_ratios` first.' This tells the agent when to use this tool vs other data retrieval tools, and provides context about trustworthiness.

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 minimal annotations (readOnlyHint: false, destructiveHint: false), the description discloses the server-side re-derivation from inputs_echo, the correction banner on discrepancy, the presigned URL return with 15-minute expiry, and the absence of chart images. No contradictions.

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

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

The description is well-structured, starting with a concise core statement, then details about sheets, return type, server-trust explanation, and pairing guidance. 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?

The description covers all essential aspects: output format, content (sheets), return mechanism (presigned URL), trust model (re-derivation), error condition (correction banner), and integration with compute_dcf. Given the complexity, it is complete enough 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?

The input schema has 100% description coverage, providing clear parameter meanings. The description adds context on how dcf_result is typically obtained from compute_dcf and how inputs_echo is used for re-derivation, enhancing understanding beyond 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 explicitly states the verb 'Render' and resource 'forward DCF result into a professional Excel workbook', listing the sheets (Summary, Sensitivity, Inputs). It differentiates from siblings by mentioning pairing with compute_dcf and contrasting with generate_comps_xlsx.

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

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

The description provides explicit pairing guidance with compute_dcf for a typical analyst flow, explains the server-trust re-derivation and correction banner, and warns that fabricated values will not appear as authoritative. This clearly informs when and how to use the 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?

The description goes far beyond annotations by detailing server-side re-derivation, verification logic, and correction banner behavior: 'the deal is re-derived in-Worker from the supplied lbo_result.inputs_echo... the workbook renders Valuein's recomputed figures'. It also mentions the 15-minute presigned URL and response fields like verification.status. 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 efficient and well-structured: a one-sentence purpose, a one-sentence output, then a critical behavioral note, followed by a typical workflow pairing. 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 complexity (3 params, deeply nested lbo_result object) and the lack of an output schema, the description is remarkably complete. It covers the output format (presigned URL), verification flag, correction banner, and typical integration with compute_lbo. No notable gaps remain.

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

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

Schema coverage is 100%, so the description does not need to add parameter details. However, it enriches understanding by explaining how lbo_result.inputs_echo is used for re-derivation and that the workbook shows Valuein's figures, not the caller's. This adds meaningful context 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 clearly states the action: 'Render an LBO result into a professional Excel workbook', specifying the resource (LBO result) and the output (Excel workbook with specific sheets). It distinguishes from siblings like compute_lbo and other generate_ tools, making the purpose unambiguous.

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

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

The description explicitly pairs this tool with compute_lbo in a typical flow: 'agent calls compute_lbo... then passes the structured result straight to generate_lbo_xlsx'. This provides clear context for when to use. However, it does not explicitly state when not to use or mention alternative tools, so it lacks full exclusion guidance.

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

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

Discloses no embedded charts (v1), that figures are unverified and carry a visible watermark, and explains server-trust and verification status 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 dense but front-loaded with purpose and structure; each sentence adds value. Slightly long but efficient and well-organized.

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

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

Given the presence of an output schema and the tool's complexity, the description covers output structure, limitations, workflow, and verification thoroughly.

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 parameters are already well-described. The description adds contextual workflow guidance but does not significantly augment parameter meaning beyond the schema.

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

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

The description clearly states the tool renders a research brief into a Word document, detailing its structure (cover page, masthead, footer, watermark) and explicitly differentiates from siblings like 'generate_dcf_xlsx' and '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?

Describes the typical flow: 'create_report → generate_research_brief_docx', advises to pair with sibling tools for visuals, and instructs to resolve citations via 'verify_fact_lineage' before publishing.

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. The description adds: 'newest-first' ordering, 'absence is a first-class answer' (no error for missing key), and the recommendation to re-ground at task start. This adds value beyond annotations.

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

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

Two sentences: first states purpose, second details usage. Every sentence is essential and front-loaded. 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 an output schema present, return values need not be explained. The description covers both modes, missing key behavior, usage timing, and a tier restriction. Complete for a read-only memory retrieval tool.

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

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

Schema coverage is 100% with a description for the 'key' parameter. The description further clarifies the two usage patterns (omit for all, specific key for one) and the null behavior, adding nuance 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's purpose: 'Recall this user's durable memory.' It specifies two modes (read all or by key) and distinguishes between them. It also implies the complementary sibling 'set_agent_memory' by being the read counterpart.

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

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

Provides explicit guidance: 'Omit key to read everything... do this at the START of a task' and 'Pass a specific key to fetch one entry.' Also explains the behavior for absent key and mentions a usage tier restriction.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that the tool returns found: false for unknown or other-customer IDs by design, and mentions a tier restriction (sp500+). This provides crucial behavioral context.

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

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

The description is concise with three sentences each delivering distinct value: action and output, scope, and error handling. The verb 'Fetch' is front-loaded, and no extraneous text exists.

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 sufficiently explains the tool's purpose, input, output fields, and edge cases (found: false). All critical information is covered.

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

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

Schema coverage is 100% with the run_id parameter already described as 'Run identifier, from list_agent_runs.' The description adds minimal new information about the parameter (e.g., 'caller's own'), so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool fetches full detail for a specific agent run by ID, listing included fields (status, goal, tickers, etc.). It distinguishes from sibling list_agent_runs by noting the ID comes from that list, and clarifies it works for both agent and workspace-triggered runs.

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 when you have a run_id from list_agent_runs, but does not explicitly state when not to use it or list alternatives. However, the context is clear enough for an agent to decide.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description supports. The description adds valuable context beyond annotations, such as the meaning of the going_active flag, dedup behavior with latest_only, and folding behavior with collapse_groups. No contradictions.

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

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

The description is five sentences, front-loaded with the purpose, then key details, then parameter usage. It is efficient without unnecessary words. Some minor repetition (e.g., 'going_active' mentioned twice) but overall 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 has 7 parameters with full schema descriptions and an output schema, the description covers the main behavioral aspects: purpose, key fields (percent_owned, etc.), dedup and grouping, and the going_active signal. The 'Institutional tier only' constraint is stated. This is fairly 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 coverage is 100%, so the baseline is 3. The description adds extra meaning for key parameters like latest_only (dedupe to most recent) and collapse_groups (fold multi-person filings), enhancing understanding beyond the schema's descriptions. The going_active flag is also highlighted, though it's not a parameter. Overall, the description adds moderate 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 returns SC 13D/SC 13G blockholder disclosures for US public companies, specifying the verb, resource, and scope. It distinguishes from siblings like get_top_holders by focusing on activist/passive filings and highlighting 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?

The description provides guidance on when to use parameters like latest_only and collapse_groups, and notes 'Institutional tier only.' However, it does not explicitly compare against alternatives or state when not to use this tool. The unique niche is clear from the description, so a 4 is appropriate.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint, and openWorldHint (all safe). The description adds valuable behavioral context: data source (10-K filings), PIT-safety via as_of_date, the informational nature of R&D percentage, and meaning of flags. 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 detailed but well-structured, front-loaded with the main purpose. While some technical details about R&D and flags are dense, they are relevant and earned. A slightly shorter version could improve readability without losing 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?

The tool has an output schema (not shown, but referenced), so description does not need to detail return values. With 3 parameters fully covered in schema and additional behavioral notes, the description is complete and sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so parameters are well-documented. The description adds context for as_of_date (eliminates look-ahead bias) and lookback_years (defaults to 5 for a full cycle). This provides additional semantic value beyond the schema definitions.

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

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

The description clearly states the tool retrieves a multi-year capital allocation breakdown for US public companies, listing all six deployment categories and additional metrics. It distinguishes itself from siblings by specifying use cases like owner-earnings and reinvestment-rate analysis, and the verb 'get' aligns with read-only intent.

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 when to use the tool: 'Use this tool when the user asks: how does a company allocate capital...' and lists several specific questions. It does not explicitly exclude alternatives among siblings, but the context is clear. Slight deduction for lack of '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 already indicate read-only and non-destructive behavior. The description adds valuable context: what data is returned (thesis ids, score history) and tier restrictions ('sample rejected' for free tiers). No contradictions.

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

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

The description is concise: two sentences plus a tier line. It is front-loaded with the core purpose and adds necessary details efficiently.

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 a simple input schema, an output schema present, and comprehensive annotations, the description is complete for a read-only retrieval tool. It covers what the tool returns and usage context.

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

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

Schema coverage is 100% and the parameter 'claim_id' has a clear description in the schema. The tool description does not add additional parameter information, so it meets the baseline but does not exceed.

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 'Fetch a single claim by id' and specifies what is included (ids of theses and score history), distinguishing it from sibling tools like list_claims and save_claim.

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

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

The description provides explicit usage guidance: 'Use this to inspect a claim's evidence, current status, and how its outcome has evolved.' It does not explicitly mention when not to use, but the context of siblings makes the purpose clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds rich context: point-in-time with no look-ahead bias, data sourced from 10-K/10-Q, confidence scoring explanation, provenance behavior. No contradiction with annotations.

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

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

Long but well-structured and front-loaded. Each sentence adds value. Could be slightly more terse, but no wasted words. The detailed disclaimers are justified for a complex data tool.

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

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

Given 9 parameters, output schema exists, and sibling tool ecosystem, description covers what the tool returns, its limitations, and when to use alternatives. No gaps apparent for agent decision-making.

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

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

All 9 parameters have schema descriptions (100% coverage). Description adds significant meaning beyond schema: explains as_of_date eliminates look-ahead bias, min_confidence penalty mechanics, lineage_detail levels. Does not just repeat 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 starts with 'Retrieve standardized SEC EDGAR fundamental financial metrics for a US public company', a specific verb+resource. It lists exact metrics and differentiates from siblings by explicitly stating what not to do (derive metrics yourself, instead use get_valuation_metrics, get_financial_ratios, compute_dcf).

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

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

Explicitly states when to use: to get as-reported line items. Provides clear when-not: 'Do NOT derive metrics from them yourself' and directs to alternatives. Also addresses plan gating and upgrade suggestion.

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, idempotentHint, and destructiveHint, so the bar is lower. The description adds valuable context: the URL is short-lived (15-min), supports HTTP range reads, is signed, and cannot list or read other objects. This goes beyond the annotations, though not exhaustively.

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

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

The description is a single paragraph but efficiently front-loaded with the core purpose. Every sentence provides distinct, non-redundant information, 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 that an output schema exists, the description does not need to detail return values. It comprehensively covers the URL behavior, dataset options, constraints, and usage context, making it fully adequate for agent invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: 'fact' dataset_type requires ticker; others are full-universe tables. It also explains the ticker pattern and length constraints, providing practical guidance beyond the schema.

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

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

The description clearly states the tool returns a short-lived download URL for a bulk Parquet object, specifying the verb 'Returns' and the resource 'bulk Parquet object'. It distinguishes from sibling tools by emphasizing high-throughput computation and streaming capability, which is unique among the listed siblings.

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

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

The description explicitly states when to use the tool: for high-throughput computation exceeding MCP context window, and explains HTTP range reads for tools like DuckDB and Polars. It also clarifies dataset-specific requirements (ticker for 'fact'). However, it does not explicitly mention when not to use it or name alternative tools, 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 declare readOnlyHint and idempotentHint true, indicating safe read operations. The description adds value by explaining that eps_trend_est is a deterministic estimate from prior EPS and that eps_surprise_pct measures deviation from the company's own trend, not a consensus beat. It also clarifies the point-in-time behavior of as_of_date.

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 roughly 6 sentences, well-structured: first sentence lists outputs, then important caveats in bold, then usage guidance. It is front-loaded with key details and avoids unnecessary repetition.

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

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

Given the tool's moderate complexity (3 params, output schema exists, annotations present), the description provides sufficient context. It explains the core concept (trend vs consensus), point-in-time safety, and default limit rationale. An output schema exists, so return value details are not required.

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

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

All three parameters are described in the schema with 100% coverage. The description enriches this by providing context for limit (default covers 2 years of quarterly signals plus TTM equivalents) and as_of_date (point-in-time filter for backtesting). It also mentions the underlying data source (earnings_signals.parquet) and how older rows surface.

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 earnings results and a model-derived trend signal for a company, listing specific fields (actual EPS, eps_trend_est, eps_surprise_pct, revenue, revenue growth). It distinguishes from siblings by emphasizing that eps_trend_est is not Wall Street consensus but a proprietary SEC-derived 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 explicitly advises to use the tool for tracking earnings/revenue trajectory and momentum, not for claiming a consensus beat or miss. It also mentions point-in-time safety for backtesting with as_of_date, providing clear context. However, it does not name alternative tools for consensus data.

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

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

Discloses that valuation data is 'LIVE' and not strictly PIT, explains the PIT logic for 'as_of_date', and notes that null values carry reasons. Annotations already indicate read-only and idempotent, so description adds valuable depth without contradiction.

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

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

The description is long but well-structured: first sentence states core purpose, then details categories, then provides usage guidelines and caveats. Every sentence adds value, though some minor redundancy could be trimmed (e.g., repeat of 'valuation is LIVE').

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

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

Given the complexity (6 params, output schema exists), the description covers all necessary aspects: what data is returned, how to handle missing categories, PIT behavior, lineage, and comparison to sibling. No gaps identified.

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

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

Schema coverage is 100%, but the description adds meaning: clarifies that 'as_of_date' is preferred over 'period_end_before', explains that omitting 'categories' returns all available for the ticker, and notes per-ticker availability. This goes beyond 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 specifies the tool retrieves financial ratios from 'ratio.parquet', lists all categories, and distinguishes from 'get_valuation_metrics' by noting the DCF/DDM difference. The verb 'Get' and resource 'financial ratios' are clear.

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 this tool vs 'get_valuation_metrics', advises omitting 'categories' to see available ones, and explains the 'is_calendar_aligned' filter for joining. Provides clear context and exclusions.

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

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

Annotations provide readOnlyHint, idempotentHint, and destructiveHint, indicating a safe, read-only operation. The description adds value by detailing the scoring scale, role weights, transaction classification (P=+1, S=-1), neutralization of options and grants, and cluster flag logic.

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 covering all key aspects without fluff. It could be improved with bullet points for readability, but it is concise and 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 that an output schema exists, the description need not explain return values. It comprehensively covers the calculation, weights, clustering, and tier restriction, making it complete for an agent to understand what the tool does.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds context for how parameters like lookback_days and cluster_window_days are used in the computation, but does not provide significant new information 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 it computes a role-weighted insider sentiment score on a fixed [-100, +100] scale for a single issuer over a lookback window. It distinguishes from siblings like get_insider_transactions by focusing on aggregated sentiment 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 mentions 'Institutional tier only' as a constraint but does not explicitly state when to use this tool vs alternatives such as get_insider_transactions. The usage context is implied but not directly compared to siblings.

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

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

Beyond annotations (readOnlyHint=true), the description adds critical behavioral context: the institutional tier requirement and upgrade link. It also details what the output includes (insider name, role, transaction code, etc.), which annotations do not cover.

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

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

Two sentences: the first defines the tool's output concisely, the second lists filters and entitlement. No extraneous content, and the main purpose is front-loaded.

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

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

For an 8-parameter tool with output schema, the description covers the primary use case, return fields, filters, and entitlement. It omits details on pagination or error handling but is sufficient for an experienced agent.

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 each parameter described. The description summarizes filter categories and provides example codes (P=purchase, S=sale), but this adds minimal new meaning beyond the schema.

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

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

The description clearly states the tool returns 'Form 3 / 4 / 5 / 144 line items' with specific fields, distinguishing it from sibling tools like get_insider_sentiment. The verb 'Returns' and resource 'insider transactions' are explicit.

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

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

Provides clear context on filters (lookback, transaction codes, roles, min shares) and explicitly states the institutional tier restriction and ENTITLEMENT_DENIED behavior. However, it does not directly compare with the sibling 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?

Annotations already declare readOnly and idempotent; description adds valuable behavioral context: 45-day reporting lag, staleness_warning at 90 days, source partition. 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?

Three sentences, each with distinct necessary information: output content, source, and data staleness. Front-loaded, no filler, every sentence earns its place.

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

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

Given output schema exists and annotations are rich, description adds source and staleness details. Missing mention of pagination or rate limits, but overall sufficient 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% with full parameter descriptions. Description adds no new parameter-level insight beyond echoing top-N and defaults. 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?

Description clearly states it returns top-N institutional holders with specific aggregate metrics, source, and tier. It distinguishes from sibling tools like get_blockholders by specifying institutional tier, but does not explicitly name alternatives, so it's clear but not perfectly differentiated.

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 institutional holdings via 'Institutional tier only', but no explicit when-not or alternative tool names. Agent may infer contrast with get_blockholders or get_top_holders but lacks direct 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?

Goes well beyond annotations by explaining the as_of_date cutoff behavior, QoQ delta computation, and error handling for ambiguous filer_name matches. Adds access restriction ('Institutional tier only') and clarifies the difference between period_end and as_of_date.

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 concise paragraph covering purpose, key parameters, and constraints. It could be improved by separating parameter usage into bullet points, but it is efficient and front-loaded with the main purpose.

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

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

Given the complexity (6 parameters, output schema present), the description adequately covers purpose, parameter guidance, behavioral details, and an access restriction. It does not mention rate limits or pagination, but the output schema likely covers return structure.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by explaining the fuzzy match mechanism for filer_name, the error scenario of multiple matches, and the interpretation of period_end vs as_of_date, which clarifies parameter interaction.

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 13F filer's full portfolio with QoQ deltas, specifying verb, resource, and distinctive details (new/increased/decreased/exited/unchanged). This differentiates it from sibling tools like get_institutional_holdings by focusing on 13F filings and quarterly changes.

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

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

Provides clear guidance on specifying the filer (prefer filer_cik, filer_name fuzzy match with error handling) and defines 'Institutional tier only'. However, it does not explicitly compare to alternative sibling tools or specify when to use this vs others for similar data.

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

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

Beyond annotations indicating read-only and idempotent, the description adds that omitting day returns the most recent (not necessarily today's) and that no brief returns 'found: false'.

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

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

The description is concise, well-structured, and front-loaded with the main purpose, followed by detailed usage guidance without redundancy.

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

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

The description covers all necessary behavioral aspects including the parameter behavior and edge case (no brief exists), and given the output schema exists, return values need not be detailed.

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

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

The schema already documents the 'day' parameter fully, but the description adds contextual instruction on omitting vs providing it, which is valuable for correct use.

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

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

The description clearly states the tool reads the caller's Morning Brief, a specific daily market digest, and distinguishes it from sibling tools by being uniquely about the morning brief.

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 explains when to omit 'day' for the most recent brief and when to provide a specific day, and normalizes the case of no brief existing.

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: PIT semantics for as_of_date, peer selection caveats, use of TTM ratios, and pipeline-computed data. No contradiction with readOnlyHint and idempotentHint.

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

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

The description is well-structured with key purpose first, followed by details and caveats. It is slightly lengthy but each 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 the output schema exists, the description provides all necessary context: what is returned (peers with ratios), categories, data recency (TTM), point-in-time semantics, peer selection method, and plan availability. Complete for an informed decision.

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 covers all parameters with descriptions (100% coverage). The description adds extra context for as_of_date (PIT behavior) and categories enumeration, improving 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?

The description uses a specific verb 'Get' and identifies the resource 'peer comparison for a company and its closest competitors'. It distinguishes from sibling tools like get_financial_ratios and compare_periods by specifying peer context.

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

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

The description indicates when to use (for peer benchmarking) and notes limitations (peer selection uses current S&P 500 membership regardless of as_of_date). It is clear but does not explicitly state when not to use or name alternatives.

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

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

Disclosures beyond annotations: survivorship-free, per-row confidence, _meta.pit_safe flag, sector derivation (not licensed GICS), empty array for out-of-range dates, and plan availability.

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

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

Well-structured with front-loaded purpose, but slightly verbose; multiple paragraphs each add value but could be tightened.

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

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

Given 8 parameters, 100% schema coverage, output schema, and sibling tools, the description is thorough—covers usage, return values, caveats, and plan availability.

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

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

Adds context beyond schema: limit suggests size near index, offset explains truncation paging, as_of_date states survivorship-free, is_active warns bias, include_share_classes explains CIK dedup.

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 historical index membership and a survivorship-free universe, and explicitly distinguishes it from search_companies which only returns current membership.

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

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

Provides explicit guidance: use for historical questions, not for current membership; recommends use before get_compute_ready_stream for backtests; warns about survivorship bias when using is_active filter.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds extensive behavioral context: zero look-ahead bias, sourcing of EOD close (from stock_price_daily.parquet), TTM financials computation, and exact fields returned. 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, starting with the key benefit (zero look-ahead bias). It is fairly long but every sentence adds value, covering behavior, use cases, and plan coverage. No wasted words, though could be slightly shortened.

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

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

Given the tool has an output schema (so return values are documented elsewhere), the description fully covers parameter meaning, behavioral guarantees, use cases, and plan dependencies. It is complete for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters, but the description adds meaningful context: for 'as_of_date' it explains that the closest prior trading day close is used and that financials are PIT-filtered, going beyond schema syntax to inform 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?

The description clearly states the tool returns a full snapshot of PIT valuation multiples, specifying the verb 'Returns' and resource 'snapshot of valuation multiples for a company on a specific historical date' with zero look-ahead bias. It does not explicitly differentiate from siblings like get_financial_ratios or get_valuation_metrics, but the unique point-in-time aspect is highlighted.

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 lists specific use cases: 'historical valuation screens, backtesting entry-point multiples, forensic audit of peak / trough valuations, comparing a company's current multiples to its own history.' It also mentions plan-dependent coverage. However, it does not provide explicit when-not-to-use or alternative tools.

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