FinBridge

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds genuine behavioral context beyond that: the FX conversion methodology, the accounting-basis mismatch caveat, and the per-metric/per-year row shape of the response. Not fully exhaustive (no mention of rate limits or caching), but substantial added 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?

Front-loaded with the core purpose, then structured Args/Returns/Examples/Errors sections. There is mild redundancy between the Args block and the already-complete schema descriptions, but the examples and error guidance earn their space.

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?

An output schema exists, so return-value explanation is not required, yet the description still summarizes the row shape and the FX/caveat payload. Combined with explicit error handling and usage exclusions, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents each parameter including accepted identifier formats and the metrics enum. The Args block restates these with examples but adds no semantics the schema lacks. Baseline 3 applies.

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

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

States a specific verb (compare), the exact resources (annual financial statements of a Korean and a US listed company), the data sources (OpenDART/K-IFRS and SEC EDGAR/US-GAAP), and the normalization applied (KRW→USD via Fed H.10 rates). This clearly separates it from the single-market siblings get_dart_financials and get_edgar_financials.

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

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

Gives explicit exclusions ('Don't use for quarterly data (annual only) or non-KR/US companies') and routes the agent to fallback tools (search_dart_company / search_edgar_company) when a name is unknown. The example query also shows a realistic invocation condition.

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 behavior beyond the readOnly/openWorld/destructive annotations: preserving table order, rowspan/colspan, unit labels, not discarding zero/negative strings, not fetching HWP/PDF attachments, and explicitly not claiming an XBRL hierarchy. This gives an agent accurate expectations about scope and limitations.

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

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

The description is long, but the tool has 13 parameters and multiple action modes, so the extra length is justified. It is front-loaded with the core purpose and workflow, and the Args section is structured and readable, though some parameter-level detail overlaps with the schema.

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, an output schema, and rich annotations, the description is complete: it covers the recommended workflow, comparison flow, truncation/pagination caps, structured-content guarantees, and exclusions. An agent has enough context to invoke it correctly without guessing.

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 high at 85%, but the description adds meaning for the comparison parameters, explaining compare_rcept_no and compare_index as selecting a second filing and index, and advising to use both overviews first. It also clarifies ambiguous section_query rejection and pagination behavior beyond the schema's terse field docs.

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 states a specific verb and resource: 'Explore the primary body of one DART filing by receipt number while preserving section and table structure.' It also differentiates itself from siblings by prescribing get_dart_filings for obtaining the receipt number and get_dart_financials for normalized financial figures, so an agent can tell this tool apart.

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?

Usage guidance is explicit and actionable: 'Use get_dart_filings first to obtain rcept_no,' 'Start with action="overview",' then select a section or table instead of requesting a long flattened filing. It also names the alternative for financial normalization, clarifying 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=true and destructiveHint=false, but the description adds meaningful context: report names are in Korean, errors reveal DART status 013 and remedies, the return shape is given, and the agent is routed to get_dart_document with rcept_no. It also warns about the 90-day default and pagination. That is far good beyond the thumbnail-protected annotations.

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

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

The description is long but extremely well-structured: purpose first, then exclusions, then args, examples, return shape, error guidance, and a final routing hint. The only slack is that get_dart_major_events is mentioned both in the 'not this tool' list and in the closing sentence, but even that adds the keyword-filtering nuance. Overall it earns its place.

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

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

For a 6‑parameter tool with a separate search and document tools, the description covers every needed decision: defaults, formats, type codes with Korean labels, example calls, return object shape, pagination, error conditions with remedies, and a pointer to get_dart_document. It leaves no gap that would force the agent to introspect blindly.

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 real meaning: corps such as Korean names, 6-digit codes, or 8-digit DART corporates; it explicitly says omitting the filter gives a market-wide list; it gives each type code (A–J) with Korean labels and the underlying category. The description explains defaults for from/to and pagination limits. This is added value beyond the bare 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?

First sentence uses a specific verb and resource: 'List corporate disclosure filings from DART', with optional filters. It then names alternatives (get_edgar_filings, get_disclosure_feed, get_dart_major_events), which makes it unambiguous which sibling it is not. The purpose is fully disambiguated.

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 'Not this tool for: ...' and lists three sibling tools with the conditions that select them. It also ends with 'For major events with keyword filtering use get_dart_major_events.' Examples show typical calls. Nothing is left to inference.

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 establish readOnly, openWorld, and non-destructive behavior, but the description adds substantial operational context: 24-hour cache reuse, response creation time vs source retrieval time, automatic consolidated-to-separate fallback, no-look-ahead point-in-time semantics, revision linking rules, and earnings disclosure handling. These are meaningful behavioral traits beyond the structured hints.

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

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

The definition is front-loaded with purpose and exclusions, then organized into Args, Returns, Examples, and Errors. It is very long and repeats some schema parameter details, but most of the detail earns its place given the tool's complexity and the subtle financial semantics involved.

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 complex nine-parameter financial data tool with an output schema, the description is exceptionally complete. It covers purpose, alternatives, parameter behavior, return semantics, edge cases, revision handling, point-in-time behavior, and error recovery.

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 does add useful meaning beyond the schema, including filing timing, automatic fs fallback behavior, case-insensitive account querying, and the no-look-ahead semantics of as_of, though much of the Args section still mirrors 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?

States a specific verb and resource: fetch and normalize financial statements of a Korean company from OpenDART. It also names the function (fnlttSinglAcntAll) and explicitly distinguishes the tool from sibling tools like get_edgar_financials, compare_financials_kr_us, and screen_companies.

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

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

Provides explicit when-to-use and when-not-to-use guidance, naming alternatives for US statements, KR-vs-US comparison, bulk screening, and filing text. It also gives error handling guidance and examples for common query patterns.

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

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

Beyond the readOnly/destructive annotations, the description discloses important behavior: there is no transaction price in KR reports, reports are filed within ~5 business days, buy/sell is derived from the sign of share change, a filter with no matches returns count 0 rather than an error, and summary totals cover the entire fetched set regardless of the filter. These are exactly the non-obvious behaviors an agent needs.

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

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

The description is long but organized into labeled sections (purpose, not-for, args, returns, important, examples, use-when, errors), with the core purpose and sibling differentiation front-loaded. The length is justified by the tool's complexity and every block carries actionable information; only minor repetition of sibling routing exists.

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

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

For a moderately complex lookup tool with an output schema and 4 parameters, the description covers input formats, enum semantics, return shape, edge cases (no matches, unknown company), timing, and the no-price caveat. Nothing an agent needs to invoke it correctly is left out.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaningful value on top: company can be a 6-digit code, name, or 8-digit DART corp_code; tx_type is tied to positive/negative share change; and response_format choices are mapped to markdown table vs machine-readable JSON. It mostly reinforces the schema but with richer operational meaning.

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

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

The description opens with a specific verb and resource: 'Korean insider transactions for a listed KR company' from DART's elestock report, explicitly framed as the Korean equivalent of SEC Form 4. It also distinguishes itself from sibling tools by naming get_edgar_insider_trades and get_edgar_13f as covering US insiders and institutional managers, so an agent can select it correctly.

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

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

It provides explicit routing: 'Not this tool for: US insiders... or institutional managers', then repeats the alternatives in the 'Use when' section ('For US insiders use get_edgar_insider_trades. For institutional holdings use get_edgar_13f'). It also gives an error-handling path (unknown company -> search_dart_company), leaving no ambiguity about when to call 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 provide readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond the annotations: filtering is applied client-side over the most recent 100 events, the default window is 180 days, the return shape is identical to get_dart_filings, and error conditions are documented (no events in range -> widen dates; invalid regex; unknown company -> search_dart_company). These details let the agent anticipate behavior and handle failures, going well 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 long but meticulously structured: it front-loads purpose and differentiators, then flows through 'Not this tool', 'What this adds', Args, Returns, Examples, Use when, and Errors. Every sentence earns its place; there is no filler or repetition of schema content. The use of sections and bullet-like formatting makes it scannable despite its length, and the most critical routing information appears first.

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

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

The tool has a rich output schema (indicated as present) and a complex sibling landscape. The description covers all necessary aspects: purpose, differentiation, parameter semantics, return shape (explicitly matching get_dart_filings), default behavior, examples, and error handling. An agent can confidently select and invoke this tool correctly without needing additional documentation. No gaps are apparent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics: it explains that 'kinds' is a JavaScript regex matched against Korean report names and provides concrete examples ('증자|합병|전환사채'), clarifies the default date window (180 days), and gives full usage examples for corp, kinds, from/to. It also documents the limit range (1-100). These additions go beyond the schema descriptions, though not exhaustively (e.g., no explicit mention that 'corp' can be omitted for market-wide scans appears in the description and schema both). The extra examples and filtering behavior justify a 4.

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

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

The description states the specific verb ('List') and resource ('major-event disclosures, DART type B') and enumerates concrete event types (capital increases, mergers, convertible bonds, treasury stock, bankruptcy, lawsuits). It also explicitly names sibling tools it is not, distinguishing it from get_dart_filings, get_edgar_filings, and get_disclosure_feed. An agent can instantly tell what this tool does and how it differs from its peers.

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

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

The description gives explicit when-to-use and when-not-to-use guidance. It opens with 'Not this tool for:' and lists alternatives for full filings, US 8-K, and cross-market feeds. It further explains what it adds over get_dart_filings (regex filter, 180-day default window, matched-count totals) and ends with 'Use when: event-driven screening...' plus an explicit 'For every filing category... use get_dart_filings.' This is textbook routing guidance.

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

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

The description goes beyond the readOnlyHint annotation by explaining behavioral nuances: row counts are refreshed every 30 minutes, may show 'counting…' immediately after a server start, and that it returns no company data itself. It also discloses potential error messages and the meaning of 'database has not been built yet.'

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

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

The description is long but well-organized, with clear sections for key objects, examples, usage, and errors. It front-loads the main purpose and provides essential context for the read-only nature. It is slightly verbose but all content is relevant and helpful.

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 the tool has no parameters, the description is very complete. It specifies the return structure, explains the key tables and views, gives example use cases, and lists error conditions. It fully prepares an agent to call the tool and interpret results.

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 tool has no parameters, and the schema declares an empty object, so there is nothing to clarify. The description explicitly states 'Args: (none)', which is redundant but harmless. Per the rubric, with high schema coverage and no parameters, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool inspects the schema of the local finbridge database, enumerating tables, views, columns, row counts, and example queries. It explicitly distinguishes itself from query_db by stating 'get_db_schema describes the tables, query_db runs the SELECT.'

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

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

It provides explicit when-to-use guidance: 'Use when: preparing a query_db, or checking ingest coverage.' It also names what not to use it for and points to alternative tools like get_stock_prices and the screeners, which is excellent orientation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context: 'refreshed nightly + intraday for KR', 'Filing metadata only; bodies are at the linked source URLs', and error handling ('empty result is not an error'). This goes beyond annotations without contradicting them, though it doesn't exhaustively detail all behaviors.

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

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

The description is long but well-structured: purpose first, then Args, Returns, Examples, Use/Don't use, Notes, Errors. Every section earns its place, with no fluff. Front-loaded with the core purpose and scoping, making it easy for an agent to quickly grasp the tool's role and call it correctly.

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

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

Given 9 optional parameters, interactions, and an output schema, the description covers everything an agent needs: return format, filtering semantics, examples, usage guidance, and error handling. It also differentiates from numerous siblings. No critical gaps remain for correct invocation.

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

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

Schema coverage is 100%, so the schema documents each parameter. However, the description adds valuable interactions: material_only default behavior (8-K / KR type-B), forms overriding material_only, and days vs from/to precedence. Examples illustrate parameter combinations, enhancing the agent's ability to use them correctly beyond schema alone.

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

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

The description states a specific verb+resource: 'Recent regulatory disclosures from the local finbridge database (filings table)'. It clearly distinguishes itself as a unified feed across KR and US markets, and explicitly contrasts with sibling tools like get_dart_filings / get_edgar_filings by positioning as a faster-than-news primary source focused on material events.

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 when: scanning for catalysts / breaking corporate events, or one company's recent filings' and 'Don't use for filing BODIES (open the url) or for financial statement values (get_dart_financials / get_edgar_financials / query_db)'. Names alternative tools and provides clear conditions, leaving nothing to inference.

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

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

The description goes well beyond the readOnlyHint/openWorldHint annotations by disclosing normalization details (2023-01-03 filing-date boundary), null handling, withheld totals/weights for incomplete data, amendment evidence, and the 45-day filing deadline caveat. It also warns that empty changes does not establish no activity, which is critical behavioral context.

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

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

The description is dense but well-organized, front-loading the core purpose and then covering caveats. It is longer than ideal, but every sentence carries meaningful behavioral or usage information. The structure is logical: purpose, parameters, return details, limitations.

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 (13F data, amendments, normalization, exclusions), the description is remarkably complete. It covers input requirements, output contents, edge cases, and limitations. The output schema exists, so return values don't need to be spelled out, but the description still explains the sources and changes fields.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the filer parameter accepts either a name or CIK, and by clarifying the top parameter limits displayed rows. It doesn't add much beyond the schema, but the filer clarification is genuinely useful.

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 reconstructs quarter-end institutional manager holdings from SEC 13F filings, and explicitly distinguishes it from issuer-ticker lookups. It names the resource (SEC 13F-HR filings) and the specific verb (get/reconstruct), making it easy to differentiate from siblings like get_edgar_filings or get_edgar_financials.

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 to pass a manager name or CIK, not an issuer ticker, and explains the top parameter range and response_format options. It also clarifies what the tool does not do (no ticker mapping, no reverse ownership lookup), which helps an agent decide when to use it 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?

The description is transparent about read-only behavior, coverage limits (~1000 filings per company), error handling, and the fact that it only returns metadata/URLs and does not fetch full documents. This aligns perfectly with the readOnlyHint and destructiveHint annotations.

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

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

The description is well structured with clear sections for purpose, examples, usage boundaries, and errors. It is detailed but every sentence adds value, and the included examples improve clarity without redundancy.

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

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

The description, schema, and output schema together provide complete context: parameters, return shape, coverage limits, error handling, and disambiguation from sibling tools. No critical information is missing for an agent to invoke this tool correctly.

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

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

The schema covers 100% of parameters with meaningful descriptions, and the tool description further clarifies company formats, form-type filtering, date range syntax, and limit defaults. Examples make parameter usage concrete.

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 a US company's recent SEC filings from EDGAR, returns metadata and document URLs, and does not download contents. It also distinguishes itself from sibling tools like get_dart_filings and get_disclosure_feed.

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

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

The description provides explicit use cases, examples, and a 'Use when' / 'Don't use for' section that clearly scopes the tool. It also explains likely errors and empty results, giving strong practical guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description goes beyond this by disclosing caching behavior ('results may be reused from a process-local cache for up to 24 hours'), the meaning of data_as_of.generated_at (response creation time, not source retrieval time), and the fact that peer comparisons use separately dated snapshots. It also explains the ordering of periods and the special case that Q4 is not reported separately in quarterly mode. All of this adds significant behavioral context that annotations alone do not provide.

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

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

The description is well-structured and front-loaded. It leads with the core purpose, then addresses exclusions, parameter details, return structure, examples, and error handling in a logical order. Every sentence earns its place: no fluff, no repetition. Despite being lengthy, it remains efficient because each piece of information is actionable for an agent.

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 (5 parameters, output schema, multiple sibling tools), the description is remarkably complete. It explains the return structure (NormalizedFinancials with company, basis, periods, notes), specifies that periods are most-recent first and fiscal_year is the calendar year of the period end, and details error scenarios (unknown company -> use search_edgar_company; unsupported filers). With an output schema present, the description needn't fully repeat return values, but it does provide enough context for correct invocation and interpretation.

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 meaningful semantics beyond the schema: it explains that 'quarterly' means discrete Q1-Q3 from 10-Q filings and that Q4 is not reported separately, clarifies that values are raw USD and eps_diluted is per share, and gives concrete examples mapping natural language to parameters ('Apple's revenue and net income for the last 3 years' -> {company:'AAPL', metrics:['revenue','net_income']}). This goes beyond the schema's terse parameter descriptions, earning a 4.

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

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

The description opens with a precise statement of what the tool does: 'Normalized annual (10-K) or quarterly (10-Q) financial statements for a US company, from SEC EDGAR XBRL company facts (US-GAAP).' This names the verb (get), the resource (financial statements), the source (SEC EDGAR XBRL), and the geographic scope (US). It also explicitly distinguishes itself from siblings like get_dart_financials, compare_financials_kr_us, and screen_companies, making the purpose unambiguous even without reading schemas.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It lists specific alternatives ('Not this tool for: Korean statements (get_dart_financials), a KR-vs-US pair on one screen (compare_financials_kr_us), or ranking many companies at once (screen_companies)') and a dedicated 'Use when' / 'Don't use for' section. This leaves no doubt about selection criteria, including the unsupported case of IFRS 20-F filers.

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 readOnlyHint annotation, the description discloses important behaviors: summary totals cover the whole fetched window regardless of filter, unparseable XMLs are skipped and counted in notes, and a filter with no matches returns count 0 (not an error). This is valuable for expectation-setting.

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

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

The description is well-structured with clear sections (main purpose, exclusions, filter explanation, args, returns, examples, usage, errors). It is thorough but not verbose, using bullet-like sections and staying concise while covering all necessary information. The main purpose is front-loaded.

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

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

The description includes a detailed 'Returns' section that acts as an output schema, explaining the structure of the result including summary, trades array, and notes. It also covers error handling and edge cases, making the tool's behavior fully predictable 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?

All three parameters are described in the schema, and the description adds further meaning: it explains transaction codes (P, S, M, F, A, G), acquired_or_disposed values, and clarifies that 'limit' is the number of filings parsed. The examples also map user intents to parameter values.

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

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

The description clearly states the tool fetches latest insider transactions for a US company from SEC Form 4 filings, with a buy/sell summary and optional filter. It distinguishes from get_dart_insider_trades and get_edgar_13f by explicitly noting the US scope and the focus on Form 4 filings.

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

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

Provides explicit 'Use when' and 'Don't use for' sections, naming alternatives like get_edgar_13f for institutional holdings and get_dart_insider_trades for Korean companies. Includes concrete examples and clarifies the effect of the limit parameter, making selection straightforward.

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

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

Annotations already mark the tool as readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral context: it does not assert direct competition, does not fill limits with unrelated companies, the rank='size' mode is explicitly size-reference only, and segment splits are informational unless rank='segments'. It also notes that unverified cross-currency absolute market-cap ordering is never used. This goes far beyond the annotations and clarifies edge cases.

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?

Although long, the description is structured into Args, Returns, Examples, Use when, Notes, and Errors sections. Every sentence adds value—no filler. The opening sentence states the core purpose immediately, and the structure allows an agent to quickly find relevant details. The length is justified given the tool's complexity.

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

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

The description covers the return structure (policy_version, purpose, insufficiency_reason, plus per-peer selection_reason, comparison_role, evidence_status) and error behavior (unknown/ambiguous company -> candidate list; no classification -> basis_kind='size'). It also includes nuanced notes about segment names and curated themes. With a comprehensive output schema and rich description, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% (every parameter has a description), but the tool description adds significant extra meaning: it explains how market disambiguates shared codes (TW/JP 4-digit), what same_market_only affects (cross-market peers allowed by default), the semantics of rank='segments' with cosine similarity and tie-breaking, and the default of limit=5. It also clarifies response_format defaults. This is far more than the schema alone provides.

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

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

The description opens with a precise purpose: 'Comparison references for one company across KR / US / TW / JP / EU.' It explicitly distinguishes itself from siblings by stating 'Don't use for strategy screens (screen_*) or for full financial statements (get_dart_financials / get_edgar_financials)' and names alternatives. The verb+resource is clear, and the differing ranking modes (business-related, size, segments) make the tool's scope unambiguous.

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

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

The description includes an explicit 'Use when' section: 'building a comparison table or choosing competitors for a financial comparison.' It then lists exclusions ('Don't use for strategy screens (screen_*) or for full financial statements (get_dart_financials / get_edgar_financials)'). This gives the agent both positive and negative routing guidance, which is ideal.

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

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

Annotations already mark the tool read-only, and the description adds valuable behavioral context beyond that: pricing sources differ per asset class (live ccxt quotes for crypto/ETFs, latest database closes for stocks, registered amount for cash and physical assets), allocation is aggregated per currency, and combined totals convert to KRW via an ECB-derived USD/KRW rate. This gives the agent a clear model of side effects, dependencies, and edge cases.

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: main purpose is front-loaded, followed by empty-case behavior, explicit alternatives, and then helpful technical details. Every sentence carries meaningful information, and there is no fluff or repetition.

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

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

With an output schema present and no parameters, the description covers all necessary invocation context: what is returned, how values are sourced, under what conditions it returns an empty list, and which sibling tools should be used instead. No critical gap remains.

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 tool has zero parameters and an empty input schema, so there are no parameter semantics to add. The no-parameters baseline is 4, and the description does not need to explain anything more for invocation.

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 states exactly what the tool does with a specific verb and resource: 'Return the holdings this user has already registered in FinBridge with import_portfolio', listing all asset types and valuation aspects. It also explicitly distinguishes itself from sibling tools by naming get_valuation, get_stock_prices, and screen_companies as what it is not for.

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

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

It gives unambiguous when-to-use and when-not-to-use guidance by naming the alternatives ('Not this tool for: analysing or valuing a company (get_valuation), prices (get_stock_prices), or finding companies (screen_companies)') and states the limiting condition that it only reads what the user stored. The empty-list case is also explicitly handled.

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

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

Goes well beyond the annotations by disclosing append-only semantics, the exact trigger conditions for a new entry (import_portfolio only when holdings/assets actually change, plus each restore), the dedup rule for identical resubmissions, and precisely what is and is not captured. These are behavioral facts the readOnly/idempotent hints cannot 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?

Three sentences, front-loaded with the core definition before the trigger rules and the recovery hint. Information density is high, though the parenthetical about valuations being recomputed is slightly tangential and the sentences are long.

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?

An output schema exists, so return values need not be described; the description instead covers everything else an agent needs — snapshot contents, creation triggers, dedup behavior, and the undo path. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100% and the single 'limit' parameter (min 1, max 100, default 20, most recent first) is fully documented in the schema. The description adds no parameter-level detail, which is acceptable here but earns only the baseline.

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

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

States a specific verb (list) and resource (append-only portfolio snapshots) and immediately defines what a snapshot is: whole-portfolio quantities, average prices, symbols and asset classes at a moment in time. It also distinguishes itself from computed data by noting market prices/valuations are never stored, which separates it from get_portfolio/analyze-style siblings.

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

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

Explicitly says when to use it ('to see when the portfolio changed') and names the follow-on action restore_portfolio_snapshot for undoing a bad import. It does not, however, state when NOT to use it — e.g. that get_portfolio should be used for current holdings — so the routing against the closest sibling is left implicit.

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

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

The description extensively discloses behavioral nuances beyond the readOnlyHint annotation, including free-tier limits ('130 trading sessions'), the plan_limit field when trimmed, truncation semantics, and error scenarios (unknown company, JP/EU no-prices, market-specific hints). It contradicts nothing in the annotations and adds substantial transparency about account entitlement and data usage.

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?

Although lengthy, the description is impeccably structured with clear sections (Args, Account limits, Returns, Examples, Use when, Errors) and uses line breaks for readability. Every sentence adds value—no fluff or redundancy—and the organization makes scanning for key details effortless.

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

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

Given the tool's complexity (multiple markets, identifier formats, account limits, error conditions), the description covers all necessary context: market coverage by region, data sources, return structure, example calls, and edge-case errors. It also includes a note about live data alternatives, ensuring an agent has full situational awareness to invoke the tool correctly.

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

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

Schema coverage is 100% with each parameter documented in the schema, but the description goes further: it explains the company resolution priority (ticker > KR code > exact name > partial match), provides concrete examples for from/to and response_format, and clarifies limit defaults. This enrichment makes parameter usage unambiguous and adds meaning beyond the raw 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 fetches daily OHLCV price history from the local finbridge database, specifying the resource and the verb. It also distinguishes itself from crypto-focused tools by explicitly noting 'Crypto has its own feed (get_crypto_ohlcv)' and 'Don't use for crypto' in the usage section, making the purpose unmistakable.

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

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

The description provides explicit guidance: 'Use when: historical closes/volumes for charting or return calculations from ingested data' and names the alternative tool for crypto (get_crypto_ohlcv). It also clarifies limitations like 'no real-time equity quote tool' and directs to other tools for live crypto and filings, leaving no ambiguity about when to invoke 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?

While annotations mark readOnlyHint=true and destructiveHint=false, the description goes far beyond by explaining the data is pre-announcements, not executed trades, has short unrecoverable coverage, no historical query, no aggregates, and units are shares. It also notes the 未轉讓 table. This adds critical behavioral context beyond annotations.

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

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

The description is long but every sentence carries unique value—scope, warnings, units, usage. It is well-structured with headers and front-loads the core purpose. Slightly verbose but not redundant, earning a 4.

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 is exceptionally complete: it covers return fields, coverage details, units, usage scenarios, and even explains the 未轉讓 table. Given the tool's complexity (8 params, output schema), nothing an agent needs is missing.

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

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

Despite 100% schema coverage, the description adds meaning: min_shares applies to transfer table only, include_untransferred default true, role is a Chinese substring, units are shares not thousands, and no monetary conversion. It clarifies the exact meaning and constraints of parameters, exceeding 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 explicitly states it returns Taiwan insider share-transfer pre-announcements from TWSE and TPEx, clearly distinguishing them from executed trades. It names the sibling tools (get_dart_insider_trades, get_edgar_insider_trades) it is not, making its scope unambiguous.

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

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

It provides explicit when-to-use guidance ('Use when: someone asks what Taiwanese insiders have declared they intend to sell...') and when-not-to ('Don't use it to claim an insider sold'). It also warns against comparing numbers across tools, giving clear exclusions and alternatives.

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

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

Annotations cover the safety profile (readOnly, non-destructive, closed-world), but the description goes far beyond it: it discloses snapshot vs real-time nature, the nightly ingest job, null-return rules for bad denominators, FX conversion behavior, cross-market accounting differences, and error semantics. This is unusually rich behavioral context that the annotations cannot 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?

Content is front-loaded and clearly sectioned (prose, Args, Returns, Examples, Caveats, Use when, Errors), and each block is substantive. It is verbose, however, and the Share counts / PER fallback paragraph could be tightened for an agent-scanning tool description.

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 complex single-company valuation tool with an output schema, the description covers inputs, units (ratios plain, ROE/CAGR in percent), returns, multi-currency caveats, and error states. Even though an output schema exists, the documented field semantics (metric_evidence, multiple_scenarios, fx_conversion) give an agent everything needed to call and interpret it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: the company resolution priority (exact ticker > 6-digit code > exact name > partial name) and the candidate-list error on ambiguous partial matches, plus clarification that scenario outputs are arithmetic from user multiple, not invented 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?

States a specific verb+resource ('get the latest valuation snapshot for one company') and enumerates the exact metrics returned (market cap, PER, PBR, PSR, ROE, debt ratio, CAGR). It explicitly differentiates from siblings by naming screen_companies/query_db for ranking and get_dart_financials/get_edgar_financials for raw statements.

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 'Use when / Don't use for' block gives explicit inclusion criteria (assess one company's valuation, compare to its own market) and explicit exclusions with named alternatives for both exclusion cases. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds that it returns specific fields (names, symbols, markets) and explicitly states it does not change the watchlist or holdings, which reinforces the non-mutating nature. This adds some value beyond annotations but isn't rich with additional behavioral details.

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 sentences that front-load the purpose and immediately state the return content and non-mutating behavior. There is no filler or redundant information.

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

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

For a tool with no parameters and a full output schema (which describes the return structure), the description covers the purpose, the exact return fields, and the read-only nature. Nothing an agent needs to decide to call it is missing.

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

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

The tool has zero parameters, so there is nothing for the description to explain. Per the calibration rule, a baseline of 4 applies when there are no parameters. The description doesn't need to add parameter 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 the verb 'Read' and the resource 'companies followed by the authenticated user', and specifies what is returned (names, symbols, markets). It distinguishes itself from write tools like manage_watchlist and from other read tools like get_portfolio or get_peers.

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

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

The description provides clear context: it is for viewing the authenticated user's watchlist. It doesn't explicitly name alternatives or say when not to use it, but the read-only framing and sibling tool manage_watchlist make the intended use obvious. It's clear enough without exclusions.

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

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

Annotations declare destructiveHint=true, openWorldHint=true, and readOnlyHint=false, but the description adds rich behavioral context beyond them: a confirmation gate that returns preview:true with a changes diff and does not save unless confirm=true, the fact that rows with missing fields are saved with missing_fields and needs_input, cash status not_asked meaning no balance is on file, and undo via restore_portfolio_snapshot. No contradiction with annotations.

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

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

The description is front-loaded with purpose and usage, then organized into a numbered list under an 'IMPORTANT' heading for response handling. Despite its length, each sentence earns its place by conveying essential operational detail for a complex, destructive import tool with a confirmation gate. No redundant or filler content is present.

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

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

Given the tool's complexity, schema richness, and the presence of an output schema, the description is complete. It explains the preview/confirm workflow, how to handle missing fields and unresolved symbols, cash balance detection, and the undo path, covering everything an agent needs to invoke the tool correctly and interpret its responses.

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 meaningful usage context beyond the schema, such as how different asset types are priced, when to pass value directly for ETFs or foreign products, and additional asset_class labels. However, much of the parameter-level detail (e.g., unit, price_scale, price_symbol) is already well documented in the schema, so the added value is helpful but not exhaustive.

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 states a specific verb and resource ('Store the structured holdings... in their FinBridge portfolio'), and explicitly distinguishes itself from siblings by naming what it is not for: 'Not this tool for: the watchlist (manage_watchlist), valuing a company (get_valuation), or reading what is already stored (get_portfolio).' It also clarifies supported sources and asset types. An agent can tell this apart from related tools without opening schemas.

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

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

Explicit guidance is provided: 'Use when: the user explicitly enters what they hold and wants it stored for get_portfolio.' It also gives when-not conditions, lists alternatives, and covers prerequisites through the confirmation gate, missing fields, cash handling, and undo instructions. The routing logic is unambiguous.

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 clarifies that removing deletes an entry while adding is non-destructive, and that it changes saved preferences, not financial assets. This complements the destructiveHint and idempotentHint annotations.

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

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

The description is somewhat repetitive in the second paragraph, restating idempotency and the exclusion of financial assets, but it remains well-organized and scannable.

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

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

The description explains what the tool does, when to use it, what it does not handle, and the result behavior (reports list size). With an output schema present, this is complete enough 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?

Although the schema already covers the parameters, the description adds the critical conditional requirement that symbol is needed for both 'add' and 'remove', which is not fully captured by the required array. It also clarifies action 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 the tool adds or removes a company from the user's watchlist, with specific verbs and resource. It distinguishes itself from portfolio and market data tools.

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

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

It explicitly says 'Not this tool for holdings and cash' and names the alternatives get_portfolio/import_portfolio, plus excludes market data. It also explains idempotent behavior for add/remove.

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 read-only, but the description adds substantial behavioral detail: rejected non-SELECT inputs, forbidden keywords, separate read-only process, 2-second deadline, concurrent query limit, 1 MB result budget, and free-account restrictions. 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?

Well-organized with sections for description, args, returns, examples, use-when, and errors. Some redundancy exists between the main description and the sql parameter description, but the content is dense and purposeful.

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 input constraints, output shape (columns, rows, row_count, truncated), example queries, error behavior, and data limitations. This is a complex SQL tool and the description gives an agent everything needed to use it correctly.

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

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

Schema descriptions already fully cover all three parameters. The tool description adds meaningful examples, clarifies trailing semicolon tolerance, explains compact JSON output, and notes helpful views and data coverage, going beyond the baseline.

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

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

States exactly what it does: runs a single read-only SELECT query against the FinBridge database. Clearly differentiates from sibling tools like screen_companies and get_db_schema by name and scope.

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

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

Provides explicit 'Use when' guidance (custom aggregation/joins that screen_companies cannot express) and explicit 'Don't use' guidance (anything that writes; no real-time equity data). Names relevant alternative tools such as get_crypto_ticker, get_dart_filings, and get_edgar_filings.

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 flag destructiveHint=true and idempotentHint=false; the description goes further by disclosing that ALL holdings are replaced, that the restore is itself recorded as a new snapshot, and that history is append-only so the action is reversible the same way. It also flags a user-facing consequence (tell the user what was restored).

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?

Front-loads the destructive scope in the first sentence, then usage, then reversibility. Four sentences with little waste, though the closing parenthetical about get_portfolio valuation is marginally decorative.

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 destructive, non-idempotent mutation with an output schema present, the description covers scope of destruction, the optional-parameter fallback, and the reversibility model. It tells the agent everything needed to call it responsibly without explaining return values.

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

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

Schema coverage is 100% and the schema already documents the omit behavior, but the description adds interpretive meaning by framing omission as 'undo the last change' and restating the fallback semantics in plain language. This is a modest value-add over the baseline 3.

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

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

States a specific verb (roll back/restore) and resource (stored portfolio snapshot), names the source (get_portfolio_history), and specifies scope ('replacing ALL current holdings and assets'). It is clearly distinguishable from siblings like import_portfolio and get_portfolio_history.

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

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

Gives explicit when-to-use ('to undo a bad import_portfolio call') and a precise operating rule for the optional parameter (omit snapshot_id to undo the last change). The alternative tools are named and tied to the condition that selects them.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds rich behavioral detail beyond that: match priority order, English matching limitation (reads own company table), error conditions (DART_API_KEY not configured, no match returns count 0), and the fact that corp_code is required by other dart_* tools. This fully discloses operational behavior.

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

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

The description is well-structured with headers (Args, Returns, Match priority, Examples, Use when, Errors). Every sentence adds value: alternatives, parameter details, return format, matching nuances, and errors. It is long but not padded; each section is necessary for correct invocation.

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 and describes return fields, so the description needn't repeat them. It covers match priority, English matching caveat, error handling, and the relationship to other dart_* tools. An agent has all information needed to decide when to call and interpret results 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%, but the description adds significant meaning: query accepts three formats (Korean/English name, 6-digit stock code, 8-digit corp_code) with examples; listed_only clarifies the default true and explains the ~90k unlisted entities; limit range is reaffirmed. Examples illustrate realistic usage. This goes far 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 states the exact verb (search) and resource (companies registered with DART), and clarifies the output (corp_code). It explicitly names the sibling search_edgar_company as the alternative for US registrants, making differentiation unambiguous.

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

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

Explicitly states when to use ('when you need a corp_code or must disambiguate similar names') and when not to ('Don't use for US companies'), with explicit alternatives (search_edgar_company, screen_companies, query_db) for other regions. No inference needed.

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

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

The annotations already indicate readOnlyHint and destructiveHint false, and the description adds useful behavioral context by describing the return structure, the error behavior for no matches, and the limitation that only SEC registrants with a listed ticker are searchable. It does not contradict the annotations and adds meaningful transparency about edge cases.

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

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

The description is well-organized with clear sections for use cases, examples, and errors. It is slightly repetitive in places (e.g., the return shape is described both in prose and in the Returns line), but every section contributes useful information and the overall length is appropriate for a tool with routing nuances.

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 provides complete context for selecting and calling the tool: when to use it, when to skip it, what it returns, error behavior, search limitations, and examples. Given the sibling tools include related search and EDGAR functions, this context is sufficient for an agent to use the tool correctly without further clarification.

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

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

The schema already provides full descriptions for both parameters, so the baseline is 3. The description adds value by giving concrete examples of accepted query forms (tickers, name fragments, CIKs), explaining the ranking order, and repeating/illustrating the limit behavior, which goes beyond the schema text.

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 identifies the tool as a search over SEC EDGAR registrants by ticker, company name, or CIK, and specifically notes that it returns the 10-digit zero-padded CIK needed by other edgar_* tools. It also distinguishes itself from search_dart_company for Korean companies.

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

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

The description explicitly states when to use the tool ('use when you need a CIK or to disambiguate a company name'), when it can be skipped (exact tickers can go directly to other edgar_* tools), and when not to use it (Korean companies, private companies). It also names the alternative tool for Korean companies, giving clear routing guidance.

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