FinBridge

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is carried by structured data. The description nonetheless adds real context beyond it: upstream sources (OpenDART K-IFRS, SEC EDGAR US-GAAP), the Fed H.10 annual-average FX basis, accounting-basis caveats, and a plan quota ('free plan up to 4' years). Only minor operational details (rate limits, latency) are absent.

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 one-sentence summary followed by clearly delimited Args/Returns/Examples/Errors sections, each earning its place. Minor redundancy: the Args and metrics enumeration duplicate the schema's own descriptions, so a small amount of text could be trimmed without losing 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 everything an agent needs: valid inputs, FX conversion basis, accounting-standard mismatch caveats, output shape, hard exclusions, and error recovery paths. An output schema exists so the return-value explanation is optional, yet the description still orients the agent 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 — every parameter (kr_company, us_company, years, metrics, response_format) is already documented in the schema, and the description's Args block largely restates it. The worked natural-language example does add value by showing how kr_company's three accepted identifier forms map to a real query.

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) and resource (annual financial statements of a Korean vs US listed company), plus the exact data sources and FX methodology. An agent can distinguish this immediately from get_dart_financials and get_edgar_financials, which cover only one market each.

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

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

Explicitly states when not to use it ('annual only', 'non-KR/US companies') and routes the agent to search_dart_company / search_edgar_company on unknown-name errors. This is a full when/when-not/alternative specification, not an implied one.

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 read-only/destructive=false, but the description adds real behavioral context beyond them: preserved-copy vs live-DART reads (fresh), table structure retention (row/col order, span, unit labels), that zero/negative strings survive, and the explicit disclaimer that no XBRL hierarchy is claimed.

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 purpose and routing before the arg list, and every section carries information. The args block largely restates schema fields, which is mild redundancy rather than waste; overall it is long but well organized.

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

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

For a 15-parameter, multi-action tool with an output schema and annotations, the description covers workflow ordering, comparison semantics, truncation/pagination behavior, and explicit non-goals. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so per-parameter meaning is already documented; the description still adds interaction-level semantics the schema lacks — that compare_rcept_no compares only the selected table/section, that both overviews must be read first, and that section_query rejects ambiguous matches.

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 ('Explore one DART filing by receipt number') and immediately scopes it: main body by default or a named attachment. It also names the sibling it is not (get_dart_financials for normalized figures), so an agent can route correctly 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 sequencing: 'Use get_dart_filings first to obtain rcept_no', 'Start with action=overview', then select a section/table rather than requesting a flattened filing. It also names the alternative tool for normalized figures and the condition selecting it, plus the HWP/PDF exclusion.

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 cover the safety profile (readOnlyHint, destructiveHint=false), but the description adds non-obvious context: report names are in Korean, error codes (DART 013 for empty range, 020 for quota exhaustion) with recovery advice, and the follow-up path of passing rcept_no to get_dart_document. It does not restate what the read-only annotation already conveys, which is the right call.

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 front-loaded: purpose, then exclusions, args, returns, examples, errors. It is on the long side and partly restates schema parameter lines, but each block is scannable and earns its place for a 7-parameter tool with quota subtlety.

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

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

For an open-world, quota-sensitive, 7-parameter list tool, the description covers filtering, defaults, pagination, return fields, next-step chaining, and error recovery. An output schema exists, yet the brief return summary is only a glanceable convenience rather than a gap.

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, but the description expands the `type` enum with full Korean label meanings for every code and gives worked examples showing acceptable corp formats and date combinations. This adds genuine interpretation value over the terse schema enum 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?

Opens with a specific verb+resource ('List corporate disclosure filings from DART') and enumerates the filter dimensions. The 'Not this tool for' block explicitly separates it from get_edgar_filings, get_disclosure_feed, and get_dart_major_events, so an agent can distinguish it from siblings without opening any schema.

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 ('track what a company disclosed'), when-not-to-use (four named alternative tools with the condition that selects each), and reinforces the routing with a closing line about keyword-filtered major events. 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 only declare readOnly/openWorld/non-destructive, but the description goes far beyond: 24-hour process-local cache reuse, a database-first fallback with served_from=finbridge_db to conserve the shared daily DART quota, the rule that statement/account_query filters always go live, the fact that data_as_of.generated_at is response-creation time not retrieval time, no-look-ahead point-in-time semantics, and explicit 'facts only, no forecast' caveats. This is unusually rich behavioral disclosure.

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 well with purpose first, but the definition is sprawling. The lengthy Returns block restates structures that an output schema already provides (normalized, accounts, sum_checks, preserved_revisions, revision_links, earnings_disclosures), which the scoring brief says the description needn't explain. Much of this is genuinely useful context, but the volume exceeds what is needed to call the tool.

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

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

For a 9-parameter, open-world, quota-constrained tool with an output schema, the description covers the gaps the structured fields leave: fallback/auth/quota behavior, point-in-time correctness, restatement vs unit-error distinction, and error handling. 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the ~March filing lag for annual reports, the automatic consolidated->separate retry with a note, what as_of actually returns (point_in_time version), and that account_query is a case-insensitive substring. These are semantics the schema's terse field descriptions do not carry.

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?

Opens with a specific verb+resource ('Fetch financial statements of a Korean company from OpenDART') and names the exact DART endpoint. It immediately distinguishes itself from siblings by explicitly listing what it is NOT for (US statements, KR-vs-US pairs, multi-company ranking), so an agent can route correctly without opening any schema.

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 an explicit 'Not this tool for' block naming get_edgar_financials, compare_financials_kr_us, and query_db, plus a closing 'Use for KR-listed company fundamentals. Don't use for US companies... or for filings text (get_dart_filings)'. Error recovery ('no data' -> try another year/report or fs='separate'; unknown company -> search_dart_company) is also spelled out.

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 read-only/non-destructive, but the description adds rich behavioral context beyond them: the buy/sell sign semantics, that the API provides no transaction dates or prices, that filedAt is the filing date not the transaction date, that summary totals cover the whole fetched set regardless of filter, and that an empty filter match returns count 0 rather than an error.

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 front-loaded with purpose first, then exclusions, args, returns, caveats, examples, and usage. It is on the longer side, but nearly every block carries actionable information; the Returns block partially duplicates the output 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 a filter-heavy tool with an output schema, this definition is fully sufficient: it states scope, alternatives, argument formats, the derived semantics of the buy/sell field, error handling, and the data-availability caveat, so an agent can call it correctly without further inference.

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, but the description adds domain meaning beyond the schema: it spells out the accepted company identifiers (6-digit code / name / 8-digit corp_code), explains buy/sell as the sign of 증감수 at the conceptual level, and clarifies the summary-vs-filter interaction.

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

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

States a specific verb+resource scoped to Korean listed companies, names the DART filing type (elestock) and explicitly equates it to SEC Form 4. It also names what it is NOT (get_edgar_insider_trades, get_edgar_13f), so an agent can distinguish it from siblings 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?

Has explicit 'Not this tool for:' and 'Use when:' sections that route to the correct sibling for US insiders and institutional holdings, plus an Errors section telling the agent what to do when a company is unknown.

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

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

Annotations already declare readOnly/openWorld/destructive, but the description adds substantial behavior beyond them: the 180-day default scan window, matched-count totals when kinds is set, the index-vs-live-DART scan boundary (FinBridge index vs recent 100 events), quota fallback semantics, and the DART status 013 empty-range error. This is well above the bar set by 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?

Front-loaded with purpose and organized into clear labeled sections (Args, Returns, Examples, Use when, Errors), so it scans well. It is on the long side and some of the retroactive-correction phrasing ('What this adds over...') is dense, but essentially every sentence carries decision-relevant 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 6-param optional-filter list tool with an output schema, the description covers return shape, defaults, examples, sibling routing, and failure modes. An agent has everything needed to call it correctly and interpret the result without further inference.

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: regex examples in Korean for kinds, the corp identifier format variants, and the scanning-window caveat tied to how kinds filtering behaves. It stops short of documenting the 'fresh' parameter, which is left entirely to 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 (List) plus the exact resource (major-event disclosures, DART type B) and enumerates the event types covered. It explicitly distinguishes itself from get_dart_filings, get_edgar_filings, and get_disclosure_feed, so an agent can select it without opening any schema.

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 an explicit 'Not this tool for' list naming the alternative for each excluded case, a 'What this adds over get_dart_filings type=B' comparison, and a 'Use when' clause with a concrete decision rule ('which companies announced X' vs 'what did company Y file'). When-to-use and when-not-to-use are both fully covered.

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=true and destructiveHint=false annotations, the description discloses meaningful runtime behavior: row counts are counted in the background and refreshed every 30 minutes, rows can be null with rows_note 'counting…' after server start, and the likely error state 'database has not been built yet' is explained. There is no contradiction with 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 long but organized with clear sections and a front-loaded purpose. Some redundancy exists between 'Read this before writing a query_db statement' and 'Use when: preparing a query_db,' but the density is largely justified given the tool's role as a schema-discovery prerequisite.

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 zero parameters and a provided output schema, the description goes well beyond the minimum by listing key tables, views, row-count behavior, example SQL queries, usage boundaries, and failure modes. An agent can confidently decide when to call this tool and what to do with its 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 zero parameters, so the input schema already fully defines the call shape. The description adds an explicit 'Args: (none)' confirmation, which is useful but not a heavy burden; the baseline 4 for zero-parameter tools 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 names a specific verb ('Inspect') and resource ('schema of the local finbridge database'), then clarifies exactly what it does not do: 'It returns no company data itself — get_db_schema describes the tables, query_db runs the SELECT.' This clearly distinguishes it from the close sibling query_db and from data-returning tools.

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

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

The description gives explicit when-to-use directions: 'Read this before writing a query_db statement' and 'Use when: preparing a query_db, or checking ingest coverage.' It also names exclusions and alternatives, such as get_stock_prices and get_valuation, and warns that FinBridge has no real-time quote 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, but the description layers on rich operational detail: refresh cadence (nightly + intraday for KR), default material_only behavior, summary-only rows that may omit form_type/items/url, 'empty result is not an error', and precedence rules between args. This fully discloses edge cases and side effects 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 long but well organized with distinct sections (Args, Returns, Note, Examples, Use when, Errors). It is front-loaded with the purpose statement. Some non-essential marketing language ('positioned as a faster-than-news primary source') and the 'Not investment advice' disclaimer could be trimmed, but overall each section earns its place 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?

With 11 optional parameters and an output schema present, the description nevertheless documents every relevant operational aspect: default ranges, limits, precedence, authentication requirements, output shape including optional summary fields, edge cases, and error semantics. It includes multiple examples covering different markets, companies, watchlists, and materiality settings, so an agent has everything needed to call 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?

Although schema coverage is 100%, the description adds essential semantic detail: override precedence (from/to overrides days, forms overrides material_only, watchlist ignored when company set), the watchlist's personal-API-key requirement, and the effect of brief on returned fields. It also supplies concrete examples for each major parameter combination.

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 definition: 'Recent regulatory disclosures from the local finbridge database (filings table, refreshed nightly + intraday for KR), newest first' and specifies the material filing types by market. It differentiates from siblings by explicitly naming what it is not for ('filing BODIES', 'financial statement values' with get_dart_financials/get_edgar_financials/query_db).

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?

Contains an explicit 'Use when' section ('scanning for catalysts / breaking corporate events, or one company's recent filings') and a 'Don't use for' section that points to alternative tools for bodies and financial values. This gives clear routing guidance and leaves 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 and destructiveHint=false, but the description adds substantial behavioral context: results may be cached up to 24 hours, data_as_of.generated_at is response creation time not retrieval time, peer comparisons use separately dated snapshots, Q4 is not reported separately for quarterly, and unsupported companies (funds, 20-F filers) return explanatory errors. These details go well beyond the annotations and significantly aid correct 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?

The description is long but well-structured and front-loaded: it opens with the core purpose, then exclusions, then detailed parameter explanations, return format, examples, and usage guidance. Every section adds value; there is no filler. The structure mirrors the tool's complexity and makes the information easy to scan.

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

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

Given the tool's complexity (5 parameters, output schema, error cases, sibling tools), the description is fully complete. It covers all parameters with nuanced explanations, describes the return structure (NormalizedFinancials with periods), provides usage examples, names sibling alternatives, and explains error behavior for unknown or unsupported companies. 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?

Although schema coverage is 100%, the description adds meaning beyond the schema: it explains the meaning of 'annual' vs 'quarterly' (Q4 not separately reported), that periods are most-recent first, that values are raw USD, and that eps_diluted is per share. It also provides concrete examples mapping natural-language queries to parameter values ('Apple's revenue...' -> {company:'AAPL', metrics:['revenue','net_income']}). This fully compensates any gaps and enhances parameter understanding.

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

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

The description states a precise verb ('get') and resource ('US company financials from SEC EDGAR XBRL company facts (US-GAAP)'), and specifies scope (annual 10-K, quarterly 10-Q, raw USD). It explicitly differentiates from siblings like get_dart_financials and compare_financials_kr_us, so an agent can instantly tell what it does and what it is not.

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 'Not this tool for' guidance naming specific alternatives (get_dart_financials, compare_financials_kr_us, query_db) and conditions ('Korean statements', 'KR-vs-US pair', 'ranking many companies'). It also provides 'Use when' and 'Don't use for' statements, leaving no ambiguity about selection.

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

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

Beyond 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 cover safety (readOnly=true, destructive=false, openWorld=false), and the description adds substantial behavioral context beyond that: the non-assertion policy for default rows, same-currency constraint for size ranking, segment-data provenance (有価証券報告書 XBRL / SEC DERA), the conglomerate-matching rule, and explicit error/fallback behavior. This is rich disclosure on top of structured fields.

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

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

Well front-loaded and sectioned (Args / Returns / Examples / Use when / Notes / Errors), with examples that anchor each mode. It is long and repeats the 'business-related references, not verified competitors' point several times, which is mildly redundant but defensible given the tool's misuse risk.

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, yet the description still correctly frames what comes back (policy_version, purpose, insufficiency_reason, selection_reason, evidence_status) without over-specifying formats. Combined with the routing guidance and per-market identifier rules, an agent has everything needed to call this 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, but the description goes well beyond it: it defines what rank='segments' actually computes (cosine similarity over mapped segment industries, tie-break by normalized size), clarifies same_market_only's default and cross-market implication, and documents company-identifier formats per market. That materially changes how an agent would set these params.

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 (find comparison reference peers for one company) and instantly distinguishes itself: it produces references, not asserted competitors, across five named markets. The three rank modes are named up front, so an agent can tell it apart from screen_*/financial-statement tools without opening the schema.

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 'Use when' (comparison tables / choosing competitors) paired with 'Don't use for strategy screens (screen_*) or full financial statements (get_dart_financials / get_edgar_financials)'. This names the alternatives and the condition that routes away from this tool, 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?

Goes far beyond the readOnly/openWorld/destructive annotations by disclosing valuation sources (live ccxt for crypto/ETFs, latest database close for stocks, registered amounts for cash/physical), currency aggregation behavior, and KRW conversion method. It also documents empty-list behavior and the tool's ignorance of unheld companies.

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?

Every sentence carries useful information: purpose, exclusions, empty behavior, data freshness, and currency handling. Despite the length, it is tightly organized and front-loaded with the core definition.

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 non-obvious aspects an agent needs: input-less scope, return composition, valuation rules, currency conversion, empty result behavior, and explicit sibling routing. With an output schema present and zero parameters, nothing essential 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 input schema has zero parameters, so there is nothing to document. The description still adds meaningful context about the implicit scope (the current user's registered holdings), which is the closest analog to 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?

States a specific verb ('Return') and resource (holdings registered in FinBridge via import_portfolio), and enumerates the asset classes covered. It names sibling exclusions (get_valuation, get_stock_prices, search_dart_company / search_edgar_company) so the agent can disambiguate.

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 not to use the tool and names the relevant alternatives: valuation, prices, and company search. Also clarifies that it only reflects the current user's stored holdings, which prevents misuse for general market/screening 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?

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?

Despite readOnlyHint=true and destructiveHint=false covering the safety profile, the description adds substantial behavioral context: newest-first ordering, account entitlement trimming with plan_limit, split/dividend adjustments, truncation semantics, market-specific no-price errors, and coverage boundaries. No contradiction with annotations exists.

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 earns its place given the many market caveats, account limits, and resolution rules. It is well-structured: core capability first, then coverage, args, return shape, examples, use-when, and errors. The information is front-loaded 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?

For a tool with five parameters, account limits, market coverage variations, and error modes, the description is exceptionally complete. It even provides the return object shape, truncation meaning, and market-specific error hints, so an agent has everything needed to call and interpret the result correctly. The output schema presence does not reduce the value of this added context.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by explaining company resolution priority (ticker > KR code > exact name > partial name), candidate-list errors on ambiguous names, inclusive date semantics, and giving concrete examples for limit and from/to usage. This materially improves correct 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 a specific verb and resource ('Get daily OHLCV price history from the local finbridge database') and immediately scopes what it covers: listed equities and ETFs, with explicit exclusions for Japan, Europe, and crypto. This clearly distinguishes it from the many filing- and financial-data siblings.

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

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

The description explicitly says when to use it ('historical closes/volumes for charting or return calculations from ingested data') and when not to ('Don't use for crypto...'). It also names the live-data alternatives (get_dart_filings / get_edgar_filings) and clarifies that no real-time quote tool exists, fully routing the agent to the right choice.

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

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

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 already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: the nightly ingest job, snapshot-not-real-time caveat, share-count and PER fallback logic, Taiwan exchange-published value precedence, null denominator behavior, currency conversion details, and the explicit 'not investment advice' disclaimer. No contradiction with the read-only annotation.

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 tightly organized with labeled sections: intro, share/PER methodology, Args, examples, Caveats, Use when, and Errors. It front-loads the core purpose and then layers edge cases and disclaimers. Every section contributes actionable guidance; nothing is redundant filler.

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

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

For a complex, multi-market valuation tool, the description is complete: it covers return semantics (plain numbers vs percents, metric_evidence, multiple_scenarios), units, fallback behavior, currency conversion, basis of accounting, error conditions, and what should not be inferred from scenarios. Even with an output schema present, the description provides the interpretive context needed to use 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?

Although schema coverage is 100%, the description enriches parameter understanding beyond the schema: it explains company resolution priority (ticker > code > exact name > partial name), the candidate-list error for multiple partial matches, the meaning and bounds of per_multiples/pbr_multiples ('no default is invented'), and response_format behavior for markdown vs json. These are semantics not present in 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 names a specific verb and resource: 'Get the latest valuation snapshot for one KR, US, or Taiwan company from the local finbridge database.' It enumerates the metrics returned (market cap, PER, PBR, ROE, etc.) and explicitly differentiates from siblings by saying what it is not for (many-company ranking, raw statements). An agent can immediately tell this is a single-company valuation tool.

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

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

The description includes an explicit 'Use when' section and a 'Don't use' section naming alternatives: 'use query_db' for ranking and 'get_dart_financials / get_edgar_financials' for raw statements. This gives clear selection criteria and exclusions beyond any schema or annotations.

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 declare readOnlyHint=true and destructiveHint=false, but the description adds extensive behavioral context: rejection of non-SELECT input, separate read-only process with SQLite authorization, 2-second deadline, concurrency limits, 1 MB result budget, free-account restrictions, and specific error behavior (e.g., 'rejected with the reason'). 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 lengthy but well-structured with clear sections (overview, constraints, alternatives, args, returns, examples, when to use, errors). It is front-loaded with core purpose and constraints. While it could be trimmed slightly, every section adds value and the examples are highly instructive.

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 SQL tool, the description covers all necessary aspects: query constraints, return format, error behavior, usage context, and even points to specific views (v_financials, v_latest_annual). It explicitly mentions the output structure and includes a hint to call get_db_schema for table shapes, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, so the schema documents each parameter, but the description adds meaningful nuances: SQL must start with SELECT or WITH, a single trailing ';' is tolerated, limit range (1-500, default 50), and response_format choices. It also provides concrete examples that illustrate parameter usage. This goes beyond the baseline of 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 opens with a precise verb-resource-scope statement: 'Run a single read-only SELECT query against the local finbridge database (ingested KR/US fundamentals, filings, daily prices).' It clearly distinguishes itself from siblings by explicitly saying 'Prefer get_valuation or get_peers for ordinary single-company work' and positioning itself as the 'escape hatch' for questions no dedicated tool answers.

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 instructions: 'Use when: custom aggregation/joins over ingested data that no dedicated tool expresses. Don't use for anything that writes — it will be rejected.' It also names alternatives (get_valuation, get_peers) and prerequisites (call get_db_schema first).

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 substantial behavioral context: market-specific coverage (KR vs US), price vs total return caveat, currency caveat for AUM, single-year pinning for total_return_pct, and the 'database has not been built yet' error case. These go well beyond the annotations and are critical for correct interpretation.

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 exceptionally well-structured: it front-loads the purpose, then provides parameter semantics, coverage caveats, return format, examples, and usage guidance in logical sections. Every sentence contributes information; there is no redundancy or filler, making the length justified by the tool's complexity.

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

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

Given the tool's complexity (13 optional parameters, market-specific behavior, data quality caveats), the description is complete: it explains coverage differences, return semantics, parameter usage with examples, the exact return structure, and error handling. With annotations covering the read-only/destructive profile and an output schema described in the Returns section, 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?

Although the schema has 100% parameter description coverage, the description enriches it further: it explains the meaning of min_aum with an example (100000000000 = 1,000억) and notes it's KR-only because US AUM is null; clarifies index_contains 'TR' for total-return indices; explains premium_pct is same-day; and provides real usage examples for each filter. This adds value beyond the schema.

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

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

The description clearly states the tool screens ETFs in the local FinBridge database on specific distinguishing metrics (premium/discount to NAV, AUM, tracked index, momentum, and US audited total return). It explicitly distinguishes from operating-company tools by directing to get_valuation or query_db, and from statement-based tools like get_dart_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?

Explicitly says 'Use when: choosing or comparing funds' and 'Don't use for stocks (get_valuation / query_db) or for a single fund's price history (get_stock_prices).' It also explains why statement-based tools are not applicable to funds, giving clear when/when-not guidance with named alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral details: no-match returns count 0 (not an error), DART_API_KEY error condition, match priority ordering, and English name matching limitations. These go well beyond annotations and inform the agent of 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?

Though long, the description is front-loaded with purpose and usage, then parameters, return format, matching, examples, and errors. Each sentence adds value; no fluff. The structure uses headers ('Args:', 'Returns:', 'Match priority:', 'Examples:') which aids scanning. Appropriate length for the tool's complexity.

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

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

Covers all necessary information: purpose, usage, parameters, return structure, matching behavior, examples, error conditions, and limitations. Even though an output schema exists, the description explains the return format clearly. The tool's complexity (multiple query types, matching priority, edge cases) is fully addressed.

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 goes beyond schema by explaining query accepts name/stock code/corp_code, clarifying listed_only default and meaning, and detailing match priority (exact stock code > Korean name > partial > English). This adds substantial semantic value beyond the schema's terse descriptions.

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

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

Description states a specific verb ('search'), resource ('companies registered with DART'), and output (corp_code required by other dart_* tools). It distinguishes itself from search_edgar_company by name and usage, and clarifies its role as the entry point for DART tools. Purpose is unambiguous and differentiated.

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

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

Explicitly tells when to use ('Use when you need a corp_code or must disambiguate similar names') and when not to use ('Don't use for US companies' with alternative 'use search_edgar_company'). Also covers Japan/Taiwan/Europe via query_db. No ambiguity left for the 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: ranking order (exact-ticker > exact-name > prefix > substring), the error behavior (no match -> error suggesting a shorter fragment), and the constraint that only SEC registrants with a listed ticker are searchable. This goes beyond what annotations provide, though it doesn't describe pagination or rate 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 well-structured and front-loaded: the core purpose is in the first sentence, followed by routing guidance, args, return format, examples, and error behavior. Every section earns its place, and the examples are compact and illustrative. No fluff or repetition of schema 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?

For a search tool with a rich output schema and full schema coverage, the description is complete. It covers what the tool does, when to use it, what it returns, how results are ranked, and what happens on error. The only minor gap is lack of pagination details, but the limit parameter and return shape make this sufficient for an agent to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by giving concrete examples of valid query formats ('AAPL', 'BRK-B' or 'BRK.B', 'Berkshire', '320193') and clarifying the limit range (1-50, default 10). It also explains the return shape ({count, companies: [...]}) which helps the agent understand what the query parameter produces.

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 ('Search'), a specific resource ('SEC EDGAR registrants'), and the exact purpose: returning the 10-digit zero-padded CIK needed by other edgar_* tools. It also distinguishes itself from search_dart_company by explicitly excluding Korean companies. This is a clear, differentiated purpose.

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 you need a CIK or to disambiguate a company name before calling get_edgar_financials/filings/insider_trades'), when not to use it ('Don't use for: Korean companies'), and names the alternative (search_dart_company). It also notes that exact tickers can skip this step, which is valuable routing guidance.

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