Valuein — SEC EDGAR Fundamentals

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

Disclosure of significance classification thresholds (minor, notable, significant) adds behavioral detail beyond readOnlyHint and idempotentHint annotations. Could elaborate on default sort or metric scope but sufficient for safe invocation.

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 packed with essential info: purpose, output details, usage format, safety, and availability. No filler. Front-loaded with action and scope.

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 4 simple parameters, no output schema needed (tool clearly returns comparison metrics), and strong annotations (readOnlyHint, idempotentHint), the description fully covers what an agent needs: what it does, how to use it, and behavioral constraints.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add new parameter info beyond schema, but the period format examples and point-in-time explanation are consistent with schema descriptions. No contradiction.

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 verb 'Compare', specific resource 'core financial metrics across two fiscal periods', and unique differentiation: side-by-side with absolute/percentage changes and significance classification. Distinguishes from sibling tools like get_company_fundamentals or get_financial_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?

Explicitly describes when to use (comparing financial metrics across periods), provides period format examples, and implicitly distinguishes from sibling tools (e.g., get_financial_ratios doesn't compare periods). Also notes point-in-time safety and plan availability.

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

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

Describes data pulling from R2 (FCF base, net debt, shares) and override capability. Discloses non-persistence, aligning with annotations (readOnlyHint, idempotentHint). No contradictions.

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

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

Two sentences, front-loaded with purpose and output, then usage guidance and disambiguation. 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 output schema exists, the description adequately covers return values (intrinsic value + sensitivity grid). Combined with annotations, it provides sufficient context for tool selection and invocation.

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

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

Schema coverage is 71%, and description adds meaning by explaining the source of default values (R2) and purpose of override parameters. Without describing each param in detail, it provides enough context for parameter selection.

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

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

Clearly states it computes a forward DCF valuation, specifying inputs (growth, WACC, terminal assumptions) and outputs (per-share intrinsic value + sensitivity grid). Mentions it pulls data from R2 and allows overrides, distinguishing it from create_report.

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

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

Explicitly says when to use (caller provides assumptions) and what not to do (does not persist, use create_report instead). Mentions Tier: sp500+, but lacks explicit when-not usage or alternatives beyond the sibling 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?

Beyond annotations (which indicate non-readOnly, non-idempotent), the description adds valuable context: alerts are stored durably now, the firing pipeline is future (Phase 2), and webhook deliveries can be HMAC-signed. This discloses persistence and security traits.

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

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

The description is brief and well-structured: a short first paragraph covering the three condition shapes, and a second paragraph adding persistence and HMAC details. No unnecessary words.

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

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

Given an existing output schema, the description adequately covers creation behavior, condition shapes, and future pipeline. It could mention what the API returns (e.g., alert ID) but the output schema likely covers that.

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 only 33% schema description coverage, the description's high-level explanation of condition shapes partially compensates, but it does not detail parameters like name, channel, or nested fields beyond what the schema already provides.

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

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

The description clearly states 'Persist an alert' and enumerates three distinct condition shapes (filing_event, ratio_threshold, watchlist_change), differentiating it from sibling tools like list_alerts and delete_alert.

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

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

The description implies when to use each condition shape but lacks explicit guidance on when not to use this tool or alternatives such as delete_alert or list_alerts. No exclusions or comparative context are provided.

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

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

Annotations provide idempotentHint and no destructive/readOnly flags. The description adds key behavioral traits: synchronous execution, statefulness (persist under caller's authorship), output contents (markdown, JSON, citation chains), and the clear division of labor (server provides numbers, LLM provides prose). 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 a single paragraph of ~5 sentences, front-loaded with the main action. However, the final line about 'Tier: sample tier rejected' is cryptic and may cause confusion without adding value, slightly reducing 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 sibling count and tool complexity, the description covers purpose, output format, and current limitations. It does not explain idempotency or error handling, but the idempotent hint and schema key address that. Output schema exists, so return value explanation is adequate.

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

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

Schema descriptions cover 80% of parameters (title, ticker, report_type, params subfields). The description adds context about the sensitivity grid and the report_type constraint but does not significantly enhance parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description explicitly states 'Synchronously generate a research report and persist it under the caller's authorship' and specifies the only supported type (reverse_dcf). It differentiates from siblings by noting the tool's role (structured numbers + lineage, not text) and contrasts with compute_dcf or other report types implicitly.

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

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

The description states the tool is for reverse_dcf only and clarifies its synchronous nature. However, it does not explicitly guide when to use this tool versus alternatives like compute_dcf, get_report, or other report creation tools, leaving some ambiguity.

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

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

The description adds value beyond annotations by revealing it is a soft-delete (status change) and idempotent. Annotations provide destructiveHint=true and idempotentHint=true, but the description clarifies the mechanism. 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 extremely concise with two sentences, no redundant information, and effectively communicates the core behavior.

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

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

For a simple tool with one parameter, the description covers the essential behavior (soft-delete, idempotency). The existence of an output schema reduces the need to explain return values, so it is adequately complete.

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

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

The description does not mention the parameter 'alert_id' or explain its role. With 0% schema description coverage, the burden on the description is high, yet it provides no additional meaning beyond the schema's type and length 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 'Soft-delete: status flips to deleted' which specifies the action (delete) and the exact behavior (soft-delete, status change). This distinguishes it from other delete tools that might perform hard deletes.

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

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

No guidance is provided on when to use this tool versus other delete tools (e.g., delete_report, delete_thesis). The description only states idempotent behavior but does not explain prerequisites or 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 idempotentHint=true and destructiveHint=true. The description adds value by explaining the exact idempotent behavior (deleting a missing override returns without error) and the side effect of report reversion to canonical values. This context is beyond what annotations convey.

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

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

The description is two sentences with no unnecessary words. The first sentence covers purpose and idempotency, the second explains consequences. It is front-loaded and efficient, though the second sentence could potentially be integrated more concisely.

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 only one parameter and an output schema exists (not shown but present), the description explains the key behavioral aspects: idempotency, error handling for missing overrides, and the impact on reports. This is largely complete for a delete operation.

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

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

The input schema has one parameter, fact_id, with no description beyond type and length constraints. Schema description coverage is 0%. The description uses fact_id in the context of removal but does not explicitly define what a fact_id represents. While somewhat clear from the tool name and context, it could provide more explicit semantics.

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 'Remove a user-authored citation correction by fact_id.' This provides a specific verb (Remove) and resource (citation correction), and identifies the key identifier (fact_id). It distinguishes the tool from siblings like save_citation_override and list_citation_overrides.

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

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

The description explains idempotency and the effect on reports ('revert to canonical fact value on next regeneration'), which helps in understanding when to use it. However, it does not explicitly state when not to use this tool or suggest alternatives, such as using save_citation_override to restore an override.

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

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

Adds behavioral details beyond annotations: status transition, artifact preservation with 90-day audit window, and rejection for sample tier. No contradiction with annotations.

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

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

Two sentences, front-loaded with key information, no superfluous content. Highly concise and well-structured.

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

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

Covers all essential aspects: soft-delete behavior, idempotency, audit window, and restrictions. Completeness is adequate for a simple deletion tool with output schema present.

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

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

Schema coverage is 100% with clear parameter description. The tool description does not add new parameter details beyond what schema already provides, achieving baseline.

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

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

Description clearly states 'soft-delete' a report owned by caller, specifying exact status and visibility changes. Differentiates from other delete tools via title and behavior description.

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 some context like idempotency and sample tier rejection but does not explicitly guide when to use this tool over alternatives like delete_alert or delete_thesis.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds valuable context: it is a soft-delete (row stays for audit/re-scoring), idempotent for already-archived theses, and no hard-delete is supported. This goes 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 very concise: two sentences covering the core action, idempotency, and policy on hard-delete. No fluff, front-loaded with the most important information.

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

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

For a simple single-parameter tool with comprehensive annotations and an output schema, the description covers all necessary aspects: behavior, idempotency, persistence for audit, and future expiry. It is complete and leaves no obvious gaps.

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

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

The only parameter 'thesis_id' is fully described in the schema (100% coverage). The description does not add parameter-specific information, but it also does not need to. Baseline score of 3 is appropriate as the schema already handles semantics.

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 performs a soft-delete, flipping status to 'archived', and distinguishes this from a hard-delete. It also mentions idempotency and future archival expiry, making the purpose very specific and unambiguous.

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

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

The description explains when to use the tool (to soft-delete a saved thesis), confirms idempotency, and clarifies that hard-delete is not supported. It does not explicitly compare to sibling tools like 'delete_alert', but the context of soft-delete vs. hard-delete is clear enough for correct 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?

Adds significant context beyond annotations: explains soft-delete nature (status flip), name reuse, and idempotency. Annotations only provide idempotentHint and destructiveHint; description clarifies what 'destructive' means in this context.

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

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

Two sentences, concise, front-loaded with key information (soft-delete, status change, name reuse, idempotency). No wasted words.

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

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

Covers essential behavior for a soft-delete tool with output schema. Lacks mention of prerequisites (e.g., watchlist must exist) but idempotency may mitigate. Sufficient for the action type.

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

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

Schema has 0% description coverage, but description mentions 'name is freed' implying the parameter identifies the watchlist. Does not explicitly describe the parameter meaning or constraints beyond the schema, but provides useful context.

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

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

Description clearly states soft-delete action (archive watchlist), specifies behavior (status to archived, name freed), and distinguishes from sibling tools like save_watchlist. Uses specific verb 'delete' with context 'soft-delete'.

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 archiving watchlists without explicit when-to-use vs alternatives. However, explains side effects (name freed) which helps decide. Does not mention when not to use, but context is clear enough.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the schema is embedded in the manifest and requires no data reads, which is consistent. No contradictions. Could further mention that it's fast or returns a large result for all tables, but it's sufficient.

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: purpose, usage guidance, and availability. No wasted words. Key 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?

Given the simple tool (one optional parameter, no output schema, rich annotations), the description covers purpose, usage, and behavioral aspects completely. 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?

Input schema has one optional parameter 'table' with description covering 100% coverage. The description adds context that omitting the parameter returns the full schema for all tables, which is not in the schema description. This adds value beyond the schema.

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

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

The description clearly states it returns the Parquet schema for all tables in the Valuein SEC data warehouse, listing the included details (table descriptions, column names, types, primary keys, foreign-key references). This distinguishes it from sibling tools that perform data queries or 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?

Explicitly states 'Use this tool to understand the data model before querying with other tools', providing clear guidance on when to use it. It also notes that no data reads are required and it's available on all plans, implying no restrictions.

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 context by clarifying it's a 'soft-delete' and explains the row remains accessible for audit, going beyond annotations. No contradiction.

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

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

Two sentences plus a word, each providing essential information: action, effect, and auditability. No wasted words; front-loaded with the primary action.

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

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

The description covers purpose, behavior, and audit trail. Output schema exists, so not explaining return values is acceptable. Could mention idempotency again (already in annotations) but overall complete 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 0%, meaning parameter descriptions are absent. The tool description does not elaborate on inbox_id beyond its name. For a simple string parameter, more context (e.g., where to find it) would be 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 performs a soft-delete on an inbox item by setting dismissed_at. It distinguishes itself from hard-delete tools like delete_alert by specifying the row remains queryable for audit.

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 notes the item stays queryable via list_alert_inbox with include_dismissed=true, implying use when audit is needed. However, it does not explicitly state when to avoid this tool or mention alternatives like delete_alert.

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

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

The description adds value beyond annotations by stating it is deterministic, returns a red-flag narrative ranked by severity with citations, and that the result includes a partial flag. It does not contradict annotations (readOnly, idempotent, non-destructive). The behavioral traits are clearly disclosed, though more on rate limits or data freshness could be added.

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 paragraphs with no fluff. The first paragraph covers purpose, output, and use context. The second adds important limitations and tier. Every sentence adds value, making it efficient and well-structured.

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

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

Given the tool's complexity (partial forensic scores) and the presence of an output schema, the description covers input (single ticker), output (narrative with severity and citations), limitations (partial), and use context (SOP, sp500+ tier). It is comprehensive for an agent to understand when and how to invoke it.

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

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

The only parameter, ticker, is explained in the description as being for a single ticker. The schema has no descriptions (0% coverage), but the description compensates by providing context. For a simple string parameter, this is adequate, though examples or format hints could enhance clarity.

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

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

The description clearly states it computes deterministic forensic-accounting scores (Beneish, Sloan, solvency) for a single ticker, returning a narrative with severity and citations. It distinguishes itself by its specialized focus and mentions it's part of the forensic_earnings_brief SOP, setting it apart from sibling tools like get_earnings_signals or get_financial_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 explains when to use the tool (for forensic accounting of a ticker) and notes its limitations (partial Beneish due to missing data, flagged as partial=true). It implies usage in the context of the forensic_earnings_brief SOP. However, it does not explicitly list when not to use it or compare to alternatives, which keeps it from a 5.

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

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

Description adds details beyond annotations (readOnlyHint false, destructiveHint false) by explaining the Excel formatting features (table, highlight, summary). It does not mention side effects like file generation or size limits, but the output schema (present) may cover return type.

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: four sentences front-loaded with purpose and key details (table format, summary sheet, usage tip). No redundant information.

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

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

Covers output format and usage pairing but omits parameter semantics and file size/timeout limits. Given complexity (nested peers array, 4 params) and presence of output schema, it is minimally complete but missing actionable details about input.

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

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

Input schema has 0% description coverage, and the tool description does not explain parameters (subject_ticker, peers, etc.) beyond implicit references. It fails to compensate for the lack of schema descriptions, leaving agents to guess parameter meaning.

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

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

Description clearly states the tool renders a peer comparables table into an Excel workbook, with specific formatting features like named Excel Table and summary sheet. It effectively distinguishes from sibling tools (e.g., get_peer_comparables retrieves data, while this generates the workbook).

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 suggests pairing with get_peer_comparables for a typical flow, providing context. However, lacks guidance on when not to use this tool or alternative approaches.

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

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

Annotations are minimal (no readOnly, destructive, etc.), so the description carries the full burden. It adds valuable details: returns a 15-minute presigned R2 download URL, uses native conditional formatting, no chart images needed. Discloses behavioral aspects 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?

Four sentences, front-loaded with purpose, no redundancy. 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?

Covers what the tool does, what it returns (presigned URL), and how to use it in context. Despite nested parameters, the description and schema together provide sufficient information. Output schema existence reduces the need to explain return values.

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

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

Schema coverage is 67% with descriptions for dcf_result and company_name. Description adds little beyond schema, except the pairing hint. ticker has no extra explanation. Baseline 3 is appropriate as schema does the heavy lifting.

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'), resource ('forward DCF result into a professional Excel workbook'), and includes specific components (Summary, 5x5 Sensitivity heatmap, Inputs sheet). It distinguishes from siblings like compute_dcf and generate_comps_xlsx.

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

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

Explicitly pairs with compute_dcf, describing a typical analyst workflow. It also mentions 'Tier: pro+' indicating licensing. However, it does not explicitly state when not to use this tool versus 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 (readOnlyHint=false, etc.) are present. The description adds value by explaining it consumes the same shape as `create_report`, the output is a Word doc with no embedded charts, and it notes v1 limitations. No contradiction with annotations.

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

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

The description is concise with two well-structured paragraphs. Key information is front-loaded (purpose, components) and the second paragraph provides workflow context. No unnecessary sentences.

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, an output schema exists (relieving the need to describe return values), and the complexity is moderate, the description covers the core purpose and typical flow with sibling tools. It could briefly mention the output format (docx file) more explicitly, but overall it's adequate.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions that the tool consumes `sections` and `citations` shapes (as emitted by `create_report`), but does not explain individual parameters like `ticker`, `title`, `abstract`, `snapshot`, or `company_name`. Some compensation, but not thorough.

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

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

The description clearly states it renders a structured research brief into a Word document with specific components (cover, abstract, snapshot table, body, citations). It also distinguishes from sibling tools like `generate_dcf_xlsx` and `generate_comps_xlsx` by explicitly noting the lack of embedded charts and suggesting pairing.

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 good context on when to use: it's for generating the docx after `create_report`, and notes that it should be paired with other tools for visuals. However, it could be more explicit about when not to use or list alternatives directly.

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, idempotent, and non-destructive behavior. The description adds significant value by highlighting the 'going_active' flag as an actionable signal and explaining parameter effects (e.g., latest_only deduping). 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 with a clear first sentence defining the purpose, followed by key fields and parameter explanations. It is slightly lengthy but every sentence adds value, earning a score just below perfect.

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

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

Given the presence of an output schema (not shown but indicated), the description adequately covers purpose, key outputs, and parameter usage. It also includes important context like 'Enterprise tier only' and the 'going_active' signal, making it complete 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% with detailed parameter descriptions. The description adds extra context (e.g., 'typically what analysts want' for latest_only, 'single most actionable activist signal' for going_active) that enhances understanding beyond the schema.

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

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

The description clearly states the tool returns SC 13D/13G blockholder disclosures for US public companies, specifies key fields like percent_owned and the 'going_active' flag, and distinguishes it from siblings by emphasizing a unique activist signal.

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

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

The description provides clear context on when to use the tool (for blockholder disclosures) and includes an 'Enterprise tier only' note. However, it does not explicitly contrast with siblings like get_top_holders or get_institutional_holdings, leaving some ambiguity for an agent.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by clarifying point-in-time safety via as_of_date and specifying the data source (SEC EDGAR), which are not in annotations.

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

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

The description is concise and well-structured, with a clear first sentence stating the core purpose, followed by details on data source and included metrics, ending with key usage notes. No unnecessary sentences.

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 no output schema, the description lists the specific metrics included (operating cash flow, capex, FCF, dividends, etc.), making it complete for an analyst to understand what data is returned. The tool is not complex, and the description covers all necessary 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 description coverage is 100%, so parameters are fully documented. The description adds context for lookback_years (default 5 years for a full cycle) and as_of_date (point-in-time, eliminates look-ahead bias), but these are already covered in the schema's descriptions.

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

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

The description explicitly states the tool retrieves a multi-year capital allocation breakdown for US public companies, specifying the resource (cash flow deployment data) and action (get), and distinguishes it from sibling tools like get_company_fundamentals and get_financial_ratios by focusing on capital allocation inputs.

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

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

The description clearly states the tool is for US public companies and includes data sourced from 10-K filings, providing context for when to use it. However, it does not explicitly state when not to use it or mention alternatives among siblings.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds useful context: point-in-time behavior, no look-ahead bias, and data source. Does not contradict annotations.

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

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

Three sentences, each adding value: first states purpose and metrics, second specifies source, third clarifies point-in-time property. No fluff, front-loaded.

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

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

Given 5 parameters with 100% schema coverage, output schema exists, and annotations present, description covers key aspects. Could mention return value shape or how to handle missing data, but not necessary.

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

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

Schema coverage is 100%, so baseline is 3. Description adds some context beyond schema (e.g., 'point-in-time date eliminates look-ahead bias') but doesn't detail each parameter's interaction. Adequate given schema completeness.

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 retrieves standardized SEC EDGAR fundamental metrics for US public companies, listing specific metrics (revenue, net income, EPS, etc.) and source filings. This distinguishes it from siblings like get_financial_ratios or get_valuation_metrics.

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

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

Description mentions data source (10-K/10-Q), point-in-time capability, and lack of look-ahead bias. However, it doesn't explicitly state when not to use this tool versus siblings like get_financial_ratios or get_earnings_signals.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds value by stating URL expiry (1 hour) and plan availability ('Available on every plan — sample returns a URL scoped to the sample bucket'), which are not in annotations.

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

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

Description is concise (3 sentences) and front-loaded with the core purpose. It covers use case, datasets, expiry, and example without redundancy. Could be slightly more structured (e.g., bullet points for datasets) but currently efficient.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description is complete: it explains the return value (pre-signed URL), use case, datasets, ticker requirement, expiry, and plan info. No output schema exists, so description must cover return; it does adequately.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add parameter details beyond what schema provides (e.g., ticker required for 'fact', dataset_type enum). It lists dataset types and briefly explains 'fact' requiring ticker, but this largely mirrors the schema descriptions.

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

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

The description clearly states the tool returns a pre-signed Cloudflare R2 URL for direct Parquet file access, with specific verb ('Get') and resource ('pre-signed Cloudflare R2 URL'). It distinguishes from siblings by explaining the use case (bulk data exceeding MCP context window) and listing datasets, which no sibling tool does.

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

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

The description explicitly says when to use this tool ('when the query requires bulk data that exceeds the MCP context window') and provides an example usage pattern. It does not explicitly state when not to use or name alternatives, but the sibling tools list and context imply alternatives exist for smaller data.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context about trend calculation (trailing 4-quarter average) and plan availability, which is helpful but not extensive.

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

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

The description is three sentences with no fluff; each sentence adds distinct value (definition, usage guidance, availability).

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 no output schema, the description explains the key metrics (EPS trend, surprise_pct). However, it could mention expected output format or additional fields. Still adequate for a simple data retrieval tool.

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

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

Schema description coverage is 100%, so the schema already documents parameters well. The description adds brief context about as_of_date for backtesting but does not add significant new meaning 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 'Trend-based earnings expectations and surprise metrics' and explains EPS trend and surprise_pct, which distinguishes it from sibling tools like get_company_fundamentals or get_financial_ratios that focus on different metrics.

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

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

The description explicitly mentions point-in-time safety for backtesting with as_of_date, but does not explicitly say when NOT to use it or compare to alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool's non-destructive, read-only nature is clear. Description adds value by noting ratios are pipeline-derived and that knowledge_at does not apply, but no additional behavioral traits beyond annotations.

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

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

Description is concise, front-loading the main action and then listing categories. The note about period_end vs knowledge_at is important but could be slightly shorter. No wasted sentences.

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

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

Given the rich input schema and annotations, the description covers all necessary context: data source, categories, special behavior (TTM, period_end usage), and plan availability. Output schema exists so return values need not be explained.

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 each parameter is already well-documented in the schema. The description adds no further parameter details, but baseline is 3.

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

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

The description clearly states the tool retrieves pipeline-computed financial ratios from the ratio table, covering 7 specific categories. It distinguishes itself from siblings like get_valuation_metrics by focusing on comprehensive ratio categories including TTM rows.

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 to filter by period_end for historical analysis, not knowledge_at, clarifying correct usage. Implicitly suggests not using as_of_date. Provides guidance on when to omit categories or fiscal_period.

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, openWorld, idempotent, and non-destructive. The description adds rich behavioral details: specific role weights (CEO/CFO=3.0, etc.), transaction type mapping (P=+1, S=-1), neutralization of options/exercises/grants, and cluster flag logic. No contradictions with annotations.

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

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

The description is concise, packing a lot of information into a single paragraph. It is front-loaded with the core purpose. However, it could be slightly more structured (e.g., bullet points for role weights) to aid quick scanning.

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

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

The output schema exists, so the description doesn't need to detail return format. It covers the score range, cluster flag, and enterprise restriction. For a single-issuer query tool, this is nearly complete. Missing perhaps a note that it returns a single score per request.

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

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

Schema coverage is 100% (all three parameters have descriptions). The description adds context: 'lookback_days' is linked to 'scan transactions for', and 'cluster_window_days' is explained as 'sliding window for the cluster_flag detection'. This goes beyond the schema's minimal 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 purpose: 'Role-weighted insider sentiment score on a fixed [-100, +100] scale for a single issuer over a lookback window.' It specifies the resource (insider sentiment), the scale, and scope (single issuer, lookback). This distinguishes it from sibling tools like get_insider_transactions or get_smart_money_flow.

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

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

The description includes 'Enterprise tier only,' indicating when the tool is available. It also provides detailed role weights and transaction handling, which helps agents decide when to use this aggregated sentiment score versus raw transaction data. However, it lacks explicit 'when not to use' or direct comparison to 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description adds key behavioral info: the tier-gated response, the point-in-time date behavior (as_of_date eliminates look-ahead bias), and the lineage_detail parameter options. This provides comprehensive transparency without contradicting annotations.

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

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

The description is two short paragraphs, front-loading the core purpose and immediately listing filters and constraints. Every sentence adds value, with no redundancy or fluff.

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

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

Given the 8 parameters, 100% schema description coverage, and an existing output schema, the description covers all essential aspects: what data is returned, available filters, tier restrictions, and behavioral nuances. No missing information is critical for the agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining that as_of_date overrides lookback_days and listing transaction code mappings (P, S, A, etc.) that are not fully detailed in the schema. This adds moderate value beyond the schema.

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

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

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

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

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

The description explicitly notes that the tool is 'Enterprise tier only' and that lower tiers receive ENTITLEMENT_DENIED, providing clear usage constraints. It does not explicitly mention alternative tools, but given the specificity of the data, the guidance is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: a ~45-day reporting lag and a staleness_warning when data is older than 90 days. No contradiction with annotations.

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

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

Two sentences, no fluff, front-loaded with the main function. Every sentence earns its place.

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

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

Given the tool has 4 parameters and an output schema, the description covers the essential aspects: what data is returned, source, lag, staleness warning, and enterprise restriction. 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%, so the baseline is 3. The description adds context like 'latest by default' for period_end and mentions top-N, but most parameter details are already in the schema.

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

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

The description clearly states it returns top-N institutional holders with aggregate metrics and HHI, sourced from Form 13F-HR. However, it does not explicitly differentiate from sibling tools like get_top_holders or get_blockholders.

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

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

The description implies usage for institutional holdings data but lacks explicit guidance on when to use this tool versus alternatives. It mentions 'Enterprise tier only' but no when-to-use or when-not-to-use conditions.

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, idempotent, non-destructive behavior. The description adds value by detailing the QoQ delta categories (new/increased/decreased/exited/unchanged) and the ambiguity error for multiple name matches. This context goes beyond annotations without contradicting them.

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

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

Three concise sentences: main function, identifier usage, and tier restriction. Front-loaded with the primary action. No redundant or unnecessary words. Every sentence adds essential information.

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

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

The description mentions 'full portfolio' but the top_n parameter limits positions (default 25, max 200), which is a notable discrepancy. The description should clarify that results are a ranked subset. Otherwise, it covers identifier usage, defaults, and tier. Output schema exists, so return format details are not required here.

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

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

Input schema covers all parameters with descriptions (100% coverage). The description reinforces key points (prefer filer_cik, default period_end, top_n default) and explains the fuzzy match logic. This adds usability guidance beyond the schema descriptions, earning above baseline.

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

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

The description clearly states it returns a 13F filer's full portfolio at a specific period_end with QoQ deltas. The verb 'Returns', resource '13F filer's full portfolio', and additional details (QoQ deltas, default period) make the purpose unambiguous. It distinguishes from siblings like get_institutional_holdings by focusing on a single filer's portfolio with 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 explicit guidance on specifying the filer via filer_cik (preferred) or filer_name (fuzzy match, ambiguity error). Mentions the enterprise tier restriction. However, does not discuss when not to use this tool compared to siblings or alternative approaches for different needs.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds context about data sources (pipeline-computed ratios, TTM ratios) and plan availability. It does not contradict annotations; annotation_contradiction is 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 moderately concise at 4 sentences, covering purpose, peer selection, ratio categories, TTM usage, historical comparison, and plan availability. It is front-loaded with the primary purpose. Minor redundancy could be trimmed, but it is 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 no output schema, the description explains what is returned (ratios from up to 10 peers alongside subject company) and mentions categories. It also covers plan availability and sampling behavior. It could add details about return format (e.g., data structure), but completeness is high for a tool with strong annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that peers are auto-selected by SIC code and that TTM ratios are used, but it does not add new meaning beyond the schema for each parameter. For example, 'limit' and 'categories' are well-described in schema.

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

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

The description clearly states it retrieves ratio-based peer comparisons for a company and its closest competitors, selecting peers by 2-digit SIC code. It distinguishes from sibling tools by mentioning peer selection and specific ratio categories, making it unique among sibling tools like get_financial_ratios or get_valuation_metrics.

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

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

The description explicitly mentions when to use it (for peer benchmarking) and provides guidance on historical comparisons via period_end_before. However, it does not explicitly state when not to use it or mention alternatives for peer selection (e.g., if user wants custom peers), which would elevate it to a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. Description adds valuable context: explains how historical data is constructed (using index_membership.parquet with accurate join/leave dates), which is beyond annotations. No contradictions.

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

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

Description is concise yet comprehensive: 6 sentences covering purpose, usage, key implementation detail, output fields, recommended workflow, and availability. Front-loaded with the most critical information. Every sentence adds value.

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

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

Given the tool has 5 parameters with 100% schema coverage, no output schema, and annotations present, the description fully addresses what the agent needs: purpose, when to use, how it works internally, output fields, and relationship to sibling tools. 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%, so baseline is 3. Description adds meaning by explaining the purpose of 'as_of_date' (historical date for survivorship-free universe) and 'index' (returns S&P 500 constituents). However, it doesn't detail all parameter behaviors (e.g., sector substring match). Slight additional value over schema.

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

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

Description clearly states 'Get a survivorship-free universe of companies valid on a specific historical date.' It specifies the verb (get), resource (universe of companies), and key property (survivorship-free, point-in-time). Differentiates from siblings like 'screen_universe' and 'get_compute_ready_stream' by highlighting its role as the first step in a backtest and its historical validity focus.

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

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

Explicitly tells when to use: 'Use as the first step of a quantitative backtest before calling get_compute_ready_stream.' Also states what not to expect: no survivorship bias, uses historical data, not current snapshots. Provides context for bias-free research and mentions plan availability.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint, so the safety profile is clear. Description adds the important behavioral trait that sample tier always returns preview regardless of input format, which is not in annotations.

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

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

Three sentences, front-loaded with the verb, each sentence adds essential information. No redundant or unclear phrases.

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 (2 params, read-only, output schema exists) and the comprehensive annotation coverage, the description adequately covers the behavior, including format details and tier constraint.

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, but the description adds significant meaning by explaining what each format returns (e.g., 'rendered body' for markdown, 'full structured payload' for json). It also clarifies the tier-related preview override.

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 'Fetch a report by id' with specific verb and resource, and distinguishes the three format options. It is well-differentiated from sibling tools like create_report, delete_report, etc.

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

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

Description provides context on when to use each format (e.g., 'rendered body' for markdown, 'structured payload' for json) and notes the tier-dependent preview behavior. However, it does not explicitly exclude alternatives or give when-not-to-use guidance.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by detailing return payload (metadata + full payload) and use case (render diff against HEAD). 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. First sentence states purpose and scope, second explains usage and return value. 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 presence of output schema, return values are documented elsewhere. Description covers purpose, usage guidelines, and behavioral context. Adequate for a fetch tool with 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 50%. Description clarifies the 'version' parameter (from list_report_versions) but offers minimal insight for 'report_id' beyond the tool's context. Baseline 3 with partial compensation.

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 specifies verb 'fetch', resource 'archived version of report', and scope 'author-only'. Clearly distinguishes from siblings like 'get_report' and 'list_report_versions'.

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

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

Explicitly states 'Use after list_report_versions identifies the version number you want', providing clear context. Does not explicitly exclude alternatives like 'get_report' for the current version, but the instruction 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, idempotentHint, and non-destructive nature. The description adds transparency by specifying the exact return content (EDGAR interactive viewer URL and raw filing index URL) and availability on all plans, complementing the annotations without contradiction.

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

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

The description is concise at three sentences, front-loaded with the core purpose, and every sentence adds value: purpose, output details, and availability. No waste.

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

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

Given the output schema exists, return values need no further explanation. The description covers the tool's scope, constraints (US public companies, EDGAR links), and availability. However, it could briefly mention that the tool is limited to EDGAR filings, which is already implied, making it largely complete.

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

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

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds some context (e.g., form types listed, 8-K event codes explained) but does not significantly enhance beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns direct links to original SEC EDGAR filings for US public companies, specifying form types (10-K, 10-Q, etc.) and output details (interactive viewer URL and raw index URL). This differentiates it from siblings like search_filing_text (which searches content) and get_company_fundamentals (which provides metrics).

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

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

The description implicitly indicates when to use this tool (when needing links to filings) and mentions availability on all plans, but does not explicitly state when not to use it or compare to alternatives. For example, it doesn't contrast with search_filing_text for content search or get_company_fundamentals for financial 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?

Description adds significant behavioral context beyond annotations: composite nature, normalization, configurable weights, per-component attribution, and access restriction. Annotations already indicate read-only, idempotent, and non-destructive behavior, which the description does not contradict.

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 compact (3 sentences) and front-loaded with key information. Each sentence adds unique value: definition, mechanics, and output feature with access note. No redundant or superfluous content.

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

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

Given the tool's complexity and the presence of an output schema, the description covers all essential aspects: components, normalization, weights, attribution, and access. It is fully sufficient 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%, so baseline is 3. Description provides overarching context for weight parameters and lookback window, clarifying their roles in the composite score. It adds value by explaining the default weights and how they affect the output.

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 defines the tool as a composite flow score aggregating insider, institutional, and blockholder changes, and distinguishes it from sibling tools that provide individual components. It states the score range and the three data sources.

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 implies usage for a holistic smart money flow view and mentions enterprise tier requirement, but lacks explicit guidance on when to use this composite versus the individual component tools or alternatives. It provides context but no exclusion criteria.

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

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

Annotations already mark it as read-only and idempotent. The description adds that it returns the full record including outcome and a NOT_FOUND error for unknown or unauthorized ids, providing useful behavioral context beyond the annotations.

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

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

Two compact sentences that each add value. No redundant or irrelevant information. Properly front-loaded with the action.

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

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

For a simple read-by-id tool with one parameter and existing annotations, the description covers the key points: what it does, what it returns, and error conditions. Output schema exists (not shown but referenced), so return details are 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?

The thesis_id parameter description adds context: 'Id returned by save_thesis or list_theses', which explains its origin beyond the schema's type and length constraints. Since schema coverage is 100% and the parameter is well-documented, this scores high.

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

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

The description uses 'Fetch a single saved thesis by its id' which is a specific verb-resource combination. It clearly distinguishes itself from sibling tools like list_theses and save_thesis.

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

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

The description indicates when to use this tool (by thesis id) and mentions the NOT_FOUND error. While it doesn't explicitly state when not to use it, the use case is straightforward given its simplicity.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds value by detailing deduplication precedence (13D > 13G > institutional > insider) and classification schema, which are not in annotations.

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

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

The description is concise (one paragraph, ~90 words) and front-loaded with the core function. Every sentence adds value, from the union concept to the deduping rule and competitive positioning.

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

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

Given the composite nature across multiple filings, the description explains the classification and deduping logic. An output schema exists, so return values are covered. Minor omission: no mention of error handling or performance, but overall sufficient.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description does not add parameter-specific detail beyond what the schema provides, so baseline score of 3 applies.

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

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

The description clearly defines the tool as a composite that merges insider, 13F, and 13D/13G data with classification. It distinguishes itself from siblings like get_insider_transactions and get_institutional_holdings by being a unified view.

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 the tool is for consolidated cap table needs, contrasting with Bloomberg's separate tools. However, it does not explicitly state when to avoid it in favor of sibling tools for single source queries.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's behavioral burden is lower. The description adds value by disclosing point-in-time safety with as_of_date and that data is 'per-period' and includes both computed ratios and pre-computed DCF inputs. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph. The first sentence front-loads the core purpose. Every sentence adds unique information: metrics list, as_of_date behavior, plan availability. No redundancy or fluff.

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

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

Given the tool's moderate complexity (5 params, output schema present), the description is complete. It explains what data is returned (computed ratios + DCF inputs), the point-in-time feature, and plan availability. With an output schema, return value details are not needed. The description covers all necessary aspects for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the purpose of as_of_date ('eliminates look-ahead bias for backtesting') and clarifying that limit controls 'maximum number of periods'. However, it does not elaborate on all parameters 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 'comprehensive valuation and profitability metrics for a US public company' and lists specific metrics (gross margin, ROE, DCF, etc.). The verb 'Get' plus the resource 'valuation metrics' precisely defines purpose. It distinguishes itself from siblings like get_company_fundamentals and get_financial_ratios by being comprehensive and including DCF/DDM values.

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

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

The description explicitly mentions that as_of_date enables 'historical analysis and backtesting without look-ahead bias', guiding when to use that parameter. It also says 'Available on all plans', clarifying no plan restrictions. However, it does not explicitly contrast with sibling tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds the NOT_FOUND behavior, which provides some context but does not go beyond annotations significantly.

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

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

Two sentences, front-loaded with the key action. 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?

For a simple fetch operation with an output schema, the description covers the main behavior and error case. Could mention more about what the output contains, but output schema exists.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'by name' but does not elaborate on constraints like maxLength=80 or minLength=1 from the schema. The user-scoping hint ('unknown to this user') adds some value but insufficient.

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 watchlist by name', which is a specific verb and resource. It distinguishes from sibling tools like list_watchlists (list all) and delete_watchlist (delete).

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 specific watchlist name but provides no explicit guidance on when to use this tool over siblings or what prerequisites exist.

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

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

The description adds substantial behavioral detail beyond annotations: pagination by fired_at, default filters for dismissed/read, and tier restriction. Annotations already indicate read-only and idempotent; description enriches understanding without contradiction.

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

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

Three sentences: first states purpose and ordering, second details defaults, third mentions tier restriction. No wasted words, front-loaded, 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 that an output schema exists (noted in context signals), the description does not need to explain return values. It covers ordering, pagination, defaults, and tier restriction appropriately for a read-only listing tool.

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

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

The schema already documents 3 of 4 parameters with descriptions and defaults. The tool description restates default behavior but does not add new parameter semantics beyond summarizing defaults, which is helpful but not additive.

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 lists the caller's in-app alert inbox in newest-first order. It specifies the scope ('caller's') and the channel ('dashboard'), distinguishing it from other tools like list_alerts or dismiss_inbox_item.

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 default behavior (dismissed hidden, read included) and notes that alerts are a paid-tier feature, setting usage context. However, it does not explicitly mention when to use alternatives like list_alerts.

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, and non-destructive behavior. The description adds useful behavioral traits: pagination and newest-first ordering, complementing the annotations without contradiction.

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

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

The first sentence is front-loaded with core purpose. The second sentence 'Sample tier rejected' is irrelevant and wastes space, but otherwise the description is 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 output schema exists, return values need not be detailed. However, the description misses key filtering by status enum, which is present in the schema but not mentioned. It adequately covers ordering and pagination but not all parameter-driven behavior.

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

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

With 0% schema description coverage, the description should compensate by explaining parameter meanings. It mentions 'paginated' vaguely but does not detail limit, cursor, or status parameters, relying on self-explanatory names which may not suffice (e.g., cursor).

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

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

The description clearly states it lists the caller's alerts with pagination and newest-first ordering, which distinguishes it from create/delete alert tools. However, the phrase 'Sample tier rejected' is confusing and detracts from clarity.

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

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

The description does not explicitly state when to use this tool versus alternatives like list_my_reports or create_alert. Usage is implied by name and context, but no explicit guidance is provided.

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

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

Description adds behavioral context beyond annotations: author-only access, newest-first ordering, 0-or-1 row for fact_id, and a cryptic 'Sample tier rejected' note. Annotations already cover read-only and idempotence, so description adds value.

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 short paragraphs, front-loaded with main purpose. Every sentence adds unique information (filters, siblings, agent use). No redundancy or fluff.

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

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

Given output schema exists and annotations are present, the description is complete. It explains ordering, filtering, caller scope, and use case. No gaps that hinder 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 covers 3 of 4 parameters with descriptions. Description adds filter examples ('all AAPL corrections') and clarifies fact_id returns at most one row, providing extra meaning 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 lists citation overrides for the caller, with 'Author-only newest-first' ordering and filters by ticker or fact_id. It differentiates by naming sibling tools save and delete citation overrides, making purpose distinct.

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 a concrete agent use case: call with ticker to introspect prior corrections for system prompts. It implies when to use (for checking user corrections) but lacks explicit when-not-to-use or comparisons with other listing tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds pagination mechanism, ordering, filter logic, and authorization note, enhancing behavioral understanding.

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

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

Two sentences, no redundancy, front-loaded with purpose and key behavior. 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 full schema coverage and presence of output schema, description covers pagination, ordering, filtering, and access context. No missing behavioral aspects.

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

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

Schema covers all parameters with descriptions (100% coverage). Description adds value by stating filters compose with AND, but does not elaborate on each parameter beyond schema.

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

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

Clearly states it lists the caller's own reports, newest-first, cursor-paginated, with AND filters. Distinguishes from siblings by specifying 'caller's own reports' and noting sample tier rejection.

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 pagination and filter composition instructions but does not explicitly compare with alternatives like search_reports. Lacks 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals key behavioral traits: visibility filter (public only), reputation calculation formula, null for small samples (n<5), and sample tier rejection (sp500+ only). No contradictions with annotations.

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

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

Three sentences, front-loaded with core purpose, no redundant information. Every sentence adds value.

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

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

Given the complexity (theses, reputation, privacy) and the presence of an output schema, the description covers privacy, reputation edge cases, and sample restrictions adequately.

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

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

Schema coverage is 100%, but the description adds meaning by linking customer_id to Stripe and the profile page usage, and explaining the limit is implicit. It provides context beyond schema descriptions.

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

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

The description clearly states the tool returns public theses and reputation aggregate for a user, distinguishing it from sibling tools like list_theses (likely general) and get_thesis (single). The specific use case (profile page) further clarifies its role.

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

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

The description specifies the context: used by the /[handle] profile page and that only public entries are surfaced. It implicitly guides when to use (for public theses) but does not explicitly state when not to use or name alternatives like list_theses.

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 safe read operation (readOnlyHint, idempotent, not destructive). Description adds that it is author-scoped and returns change summaries, but no additional behavioral traits 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 front-loaded sentences with no filler. Concise and to the point.

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?

Output schema exists, so return values need not be explained. Description covers purpose, ordering, and pairing. Could add brief pagination note but overall sufficient.

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

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

Schema description coverage is only 33% (cursor documented). Description does not explain `limit` and `cursor` pagination or how `report_id` is used, leaving agents to infer from schema defaults.

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

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

Clearly states it lists report version history with newest-first ordering and per-entry change summaries. Explicitly distinguishes from sibling `get_report_version` by mentioning pairing usage.

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

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

Specifies 'Author-only' and 'newest-first' usage, and recommends pairing with `get_report_version` for diffing. Does not explicitly state when not to use, but context from siblings is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds ordering (newest-first), cursor-based pagination, filter specifics, and a behavioral constraint (sample tier rejected), providing full transparency.

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

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

Two sentences, front-loaded with purpose, covering ordering, filters, pagination, and constraint. No wasted words.

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

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

Given the output schema exists and annotations cover safety, the description sufficiently covers purpose, filtering, pagination, ordering, and a key constraint. It is complete for a read-only list operation.

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

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

Schema coverage is 100%, so each parameter is fully documented. The description summarizes filters and pagination but adds no 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 it returns the caller's saved theses, newest-first, with filters. This distinguishes it from siblings like get_thesis (single thesis) or save_thesis (write operation).

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

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

The description mentions filters and pagination, guiding when to use the tool. It also notes the sample tier restriction. However, it does not explicitly contrast with get_thesis for individual theses or other list operations.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds pagination, ordering, and filtering behavior. No contradiction.

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

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

Extremely concise: one sentence plus a note. Every word adds value. Front-loaded with key details.

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

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

Has output schema, so return values are covered. Mentions pagination, ordering, filtering, and scope. However, 'Sample tier rejected' is unclear and no sibling comparison is provided.

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 0%. The description hints at filtering by status but does not explain limit or cursor parameters. Does not compensate for low 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 it lists the caller's watchlists with pagination, newest-first order, and filtering by status. It distinguishes from siblings like get_watchlist (single) and create/delete watchlists.

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

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

No guidance on when to use this tool vs alternatives like get_watchlist or list_alerts. No exclusions or prerequisites are mentioned.

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 idempotentHint=true and destructiveHint=false. Description adds that re-marking does NOT reset the first-read timestamp and that it returns the unread_count for badge updates. This adds value beyond annotations. No contradiction.

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

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

Two sentences, each adding value. Front-loaded with the core action, followed by key behavioral note and return value. No redundant words.

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

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

Given the tool's simplicity (one parameter, idempotent, returns unread_count), the description is nearly complete. It explains the return value and idempotency. Minor gap: no mention of error conditions (e.g., invalid inbox_id) but output schema may cover that.

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 0% on the single parameter 'inbox_id'. Description does not explain the parameter's meaning, format, or constraints beyond what the schema provides (string, length constraints). For a single required param, minimal compensation.

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 verb 'Set read_at' on a single inbox item, which distinguishes it from sibling tools like 'dismiss_inbox_item' that perform a different action. The purpose is specific and actionable.

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

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

No explicit guidance on when to use this tool vs alternatives like dismiss_inbox_item. Only mentions idempotency, which is behavioral, not usage context. The description does not clarify prerequisites or scenarios.

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

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

The description goes beyond annotations by detailing that the URL is presigned for 15 minutes, caching behavior (docx cached after first build, md always instant), and that force_regenerate busts the cache. Annotations only indicate idempotent and non-destructive; the description adds depth on side effects and limits.

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

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

The description is about 150 words across four paragraphs, front-loaded with the core purpose. Each paragraph adds value without redundancy. Slightly verbose in docx details but remains efficient.

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

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

Given the tool has 3 parameters, an output schema, and complex caching/format behavior, the description covers all agent needs: what it returns, format differences, cache invalidation, and access control. No gaps are evident.

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

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

Schema coverage is 100%, but the description adds meaningful context: format enum values are explained with content specifics (cover page, ticker, citations), report_id uses authoritative sources (from create_report or list_my_reports), and force_regenerate clarifies cache behavior and its lack of effect on md.

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 15-minute presigned download URL for a report in a chosen binary format. It distinguishes between 'md' (cached markdown, instant) and 'docx' (branded Word document), differentiating it from siblings like 'get_report' which likely returns content directly.

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

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

The description provides clear context on when to use each format (md vs docx) and when to use force_regenerate (e.g., after update_report). It mentions tier gate mirrors get_report, implying similar access constraints, but does not explicitly exclude alternatives or state when not to use this tool.

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