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

The annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description does not need to restate safety. It adds behavioral context by noting 'Rows are returned in the order given, with currency per company — no ranking or judgement.' This clarifies output ordering and the lack of derived ranking, which is valuable beyond the annotations. This is a good complement to annotations.

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

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

The description is two sentences, front-loaded with the core purpose and a clear behavioral note about ordering and currency. Every word adds value; there is no fluff or repetition. This is a model of conciseness.

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

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

Given the tool's complexity is moderate (4 params, output schema present, annotations cover safety), the description is largely complete. It covers purpose, ordering, and lack of ranking. The only minor gap is the lack of explicit mention of currency handling details (e.g., currency codes) and whether metrics are normalized across companies, which might be inferred from the schema example. But with an output schema present, this is sufficient.

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

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

Schema description coverage is 75%, covering the key parameters (metrics, tickers, period, frequency) with examples. The description adds the concept of 'side-by-side' and the ordering constraint, but does not elaborate on parameter formats beyond the schema. Since the schema already does heavy lifting, a 4 is appropriate—it adds some value without being redundant.

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 tool does side-by-side comparison of metrics and ratios for multiple companies in a single call, which is precise and clearly distinguishes it from related tools like get_financials or get_metric_history that handle individual companies or histories. The explicit mention of 'several companies' removes ambiguity about its scope.

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

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

The description implies usage for multi-company comparisons, but does not explicitly state when to use this tool versus alternatives like get_financials or get_metric_history. It does mention no ranking or judgement, but lacks clear exclusions or guidance on when to prefer siblings. Given the large sibling list, a brief note on alternatives would help.

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 false, covering the safety profile. The description adds that the server issues no recommendation of its own and that data is third-party, providing extra behavioral context beyond the annotations.

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

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

The description is two concise sentences that front-load the core purpose and then add a clarifying nuance. No wasted words, and it is well-structured for quick parsing.

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

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

The tool has an output schema, and the description lists the key data points it returns. The single parameter is clearly defined, and the purpose is fully covered. Nothing essential is missing for an agent to invoke 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?

The schema covers 100% of parameters, with the only parameter 'ticker' described as 'BIST ticker'. The description does not add further parameter details, so it provides no additional value beyond the schema, warranting the baseline score 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 clearly states the tool retrieves third-party analyst consensus from Yahoo Finance, listing specific data points (buy/hold/sell counts, targets, earnings date, rating changes). This is specific and distinct from sibling tools like get_quote or get_financials, making the purpose unambiguous.

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

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

The description gives clear context that this provides analyst consensus data, which implies usage when such data is needed. It does not explicitly mention alternatives or when not to use it, but the specialization is evident from the description and name, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the data being withdrawn under KVKK and that it explains 'not found' results, but it does not disclose details like whether the list is exhaustive, pagination, or how the stated reason is formatted.

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

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

Two short sentences with no filler. The core purpose is front-loaded, and the second sentence adds a valuable use case ('Explains not found results for specific ids') without redundancy.

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

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

For a zero-parameter read-only tool with an output schema present, the description is largely complete. It explains what the tool returns and why it exists. It could be slightly stronger by noting whether the result is a full list or a lookup, but the output schema likely covers return structure.

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

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

The tool has zero parameters, so the schema provides no parameter semantics to cover. The description adds meaning by explaining what the returned data represents (withdrawn disclosures with stated reasons), which is the only semantic context needed for a no-parameter tool.

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 ('withdrawn from public access') and resource ('Disclosures KAP has withdrawn'), and adds the purpose of explaining 'not found' results for specific ids. It is clear about what the tool returns, though it doesn't explicitly differentiate from siblings like get_disclosure or search_disclosures.

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

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

The description implies when to use this tool: when a disclosure id appears 'not found' or when checking blocked/withdrawn disclosures. However, it does not explicitly state when not to use it or name alternative tools, leaving the agent to infer the usage context from the sibling list.

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

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

The description discloses important behavioral detail: KAP-absent sections are returned as null with a `not_available` note and are 'never invented.' It also mentions the optional Yahoo profile/holders addition. This goes beyond the readOnly/idempotent annotations, with no contradiction.

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

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

Two sentences with no filler. The first sentence front-loads the resource and its core contents, while the second covers the optional enrichment. The dense list is justified.

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

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

With a rich output schema, 100% parameter coverage, and annotations declaring read-only/idempotent behavior, the description completes the picture by explaining null/missing-data semantics and provenance. The need to provide either ticker or company_id is inferable from the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little parameter-level meaning beyond the schema; the 'Yahoo profile and holders' phrase mirrors include_market_profile, and nothing is missing.

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 concrete resource ('Company profile from KAP') and enumerates its contents: name, tickers, capital, ISINs, shareholders, board, etc. This is clear but does not explicitly differentiate from sibling tools like search_companies or get_quote.

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?

There is no explicit when-to-use or alternative guidance. The phrase 'Company profile from KAP' implies the use case, and the schema adds that company_id comes from search_companies, but the description itself leaves sibling selection 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 read-only and non-destructive. The description adds that no sentiment/interpretation is added and that coverage is limited to English wire/press, which is useful context beyond annotations.

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

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

Two sentences, front-loaded with purpose, then coverage and alternative. No redundancy; every word contributes.

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

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

Given output schema and annotations, description covers main usage and limitations. Lacks details on pagination or default behavior, but those are inferable from the schema (tab enum, limit min/max). Adequate for an agent to call 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 50%; description mentions 'ticker or keyword' which clarifies query/ticker usage, but does not explain tab, limit, end_date, or start_date beyond what schema provides. Some compensation exists but not complete for the half of parameters lacking 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?

States it retrieves news from Yahoo Finance's news module for a ticker or keyword, listing specific fields (title, publisher, published_at, url, summary, source). It also names an alternative for Turkish sources, distinguishing it from search_disclosures.

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

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

Explicitly notes coverage is mostly English wire/press and directs Turkish primary sources to search_disclosures, providing a clear when-not and alternative. This helps the agent choose the right tool without opening schemas.

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 the tool as read-only, idempotent, and non-destructive. The description adds behavioral details beyond that: ordering ('newest first'), the specific fields in each event (date, type, title, ids, source_url), and a limitation ('No classification or summarisation beyond KAP's fields'). This gives agents a clearer expectation of what the tool does and does not do, exceeding the annotation baseline.

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

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

The description is two sentences with no redundancy. The primary purpose is front-loaded ('Chronological events for a company'), followed by a concise list of sources and event structure. Every word contributes to understanding, making it efficient and well-structured.

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

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

The tool has 7 parameters and an output schema, so the return format is presumably defined elsewhere. The description covers the key aspects: the sources, the event fields, and the limitation on classification. It does not explicitly explain pagination or default date ranges, but those are hinted at via schema defaults and descriptions. Given the complexity, the description is adequate but could mention default behavior or pagination to be fully complete.

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

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

Schema coverage is 71%, with descriptions for ticker, start_date, max_pages, event_types, and disclosure_type, but not for limit or end_date. The description indirectly clarifies the meaning of event_types by listing the categories (disclosure, corporate_action, news) and mentions date filtering through 'chronological events', but it does not add details for limit or end_date. Since most parameters are already documented, the description adds marginal value beyond the schema, warranting a 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?

The description clearly states the tool returns 'Chronological events for a company (newest first)' and enumerates the event sources (KAP disclosures, corporate actions, Yahoo news). This distinguishes it from sibling tools like get_corporate_actions or get_company_news, which focus on single event types. The specific verb 'get' plus resource 'timeline' is unambiguous.

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

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

The description implies that this tool aggregates multiple event types into a unified timeline, contrasting with siblings that cover individual categories. However, it does not explicitly state when to prefer this over alternatives (e.g., 'if you need only corporate actions, use get_corporate_actions'). The context is clear but lacks explicit exclusions, so a 4 is appropriate.

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

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

Beyond the read-only/idempotent annotations, the description adds valuable behavioral detail: Yahoo supplies exact ex-dates and cash amounts, KAP disclosures are classified via a keyword table with an 'other' fallback, KAP body amounts are not parsed, and callers should read the referenced disclosure. It also discloses optional process-status returns.

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 compact, front-loaded with the core purpose, and every sentence earns its place: source distinction, classification behavior, KAP parsing limitation, and optional status output. No filler or redundant restatement of the tool name.

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 annotations, output schema, and reasonably strong parameter descriptions, the description covers the important non-obvious context: source-specific accuracy, KAP classification limitations, the need to read referenced disclosures, and optional process status retrieval. Nothing critical about how to use the tool 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?

Most parameters are already documented in the schema (ticker, dates, limit, include_kap, process_ref_ids), so the description does not need to repeat them. It adds meaning where the schema is thinner: process_ref_ids maps to 'optionally returns KAP process statuses', and the 'other' type is explained as the unmatched-keyword fallback.

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 resource (corporate actions for a company) and enumerates the event categories covered: dividends, bonus/rights issues, capital changes, buybacks, and general meetings. It also distinguishes the two data sources, Yahoo and KAP, making the tool's scope clear relative to nearby disclosure/quote 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 implies when the tool is appropriate—when a caller needs corporate-action events for a single BIST ticker—and explains Yahoo vs. KAP behavior. However, it never explicitly names alternatives or gives when-not-to-use guidance, such as directing reference-id status lookups to kap_status instead.

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 false, establishing the operation is safe. The description adds value by detailing what the response includes (normalized metadata, plain text body, flattened structured data) and the default behavior. It does not contradict annotations and provides useful context about output structure.

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

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

The description is a single, information-dense sentence that front-loads the core purpose ('One disclosure') followed by specific metadata fields. Every element contributes meaning; there is no redundant or filler content. It is concise while being thorough.

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

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

Given an output schema exists, the description need not explain return values in detail. It covers the key aspects: normalized metadata, body content, and flattening behavior. It does not mention edge cases like truncation or error handling, but these are likely covered by the schema and annotations. Overall, it is complete enough for an agent to call correctly with moderate confidence.

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 75% with three of four parameters having descriptions. The description lists metadata fields but does not directly elaborate on parameter semantics beyond what the schema already provides. It adds marginal value, such as clarifying that 'text' is the default format and that data is flattened, but this is mostly covered by the schema's 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?

The description clearly states the tool retrieves a single disclosure with normalized metadata and body content. It distinguishes the singular nature ('One disclosure') from search-based siblings, but does not explicitly name alternative tools like search_disclosures. The purpose is specific and actionable.

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

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

The description implies usage when a specific disclosure_id is known, reinforced by the required parameter. However, it does not explicitly state when to prefer this tool over search_disclosure_data or other document retrieval tools, nor does it provide exclusions. The guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the return fields and the fact that it lists attachments, which is useful context but does not disclose edge cases (e.g., no attachments, invalid disclosure_id) or pagination behavior. With annotations covering safety, this is adequate but not exceptional.

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

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

The description is two sentences with no fluff. The core purpose is front-loaded, and the next-step guidance is a natural extension. Every sentence earns its place.

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

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

Given the presence of an output schema (which likely documents the return structure), the description need not detail return values. For a simple list tool with one parameter, it covers the main workflow and return fields. It does not explain how to find disclosure_id, but that is a minor omission given the tool's simplicity and the availability of related sibling tools like get_disclosure.

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

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

Schema description coverage is 0%, so the description must compensate for the single parameter disclosure_id. It does not explain what disclosure_id is, how to obtain it, or its format beyond the schema's integer type. The phrase 'Pass an id' refers to attachment_id, not disclosure_id, so no guidance is given for the actual parameter. This is a significant gap for a low-coverage 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 states a specific verb ('List'), a resource ('a disclosure's attachments'), and the exact fields returned ('attachment_id', name, source_url'). It clearly distinguishes this tool from siblings like get_disclosure or search_disclosures by focusing on attachments.

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 clear next-step guidance ('Pass an id to get_document_text or search_documents to read it'), indicating the workflow after listing. It does not explicitly name alternatives or exclusions, but the purpose is specific enough that an agent can infer when to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: 'in memory; nothing is stored' and the specific failure mode of returning `text: null` with a reason for unsupported formats. This goes beyond the annotations and helps set expectations for the agent.

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

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

Three sentences, each earning its place: the first states the core function and memory behavior, the second covers failure modes, and the third routes to the preferred alternative. The most important scoping information is front-loaded, and there is no redundant filler.

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

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

The description is complete for a read-only extraction tool: it covers supported formats, failure modes, and the alternative for long documents. The output schema exists, so return values need not be explained. A minor gap is that it doesn't mention pagination or the max_chars limit explicitly, but the schema already documents those, so the description is sufficiently complete.

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

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

Schema description coverage is 67%, with attachment_id and pages already described in the schema. The description adds meaning by explaining the overall extraction behavior and the `text: null` return for unsupported formats, which indirectly clarifies the role of the parameters. It doesn't repeat schema details, and the remaining max_chars parameter is self-explanatory with its default and bounds in the schema.

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

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

The description states a specific verb ('Extract text') and resource ('PDF/HTML/text attachment'), and explicitly distinguishes itself from search_documents by noting the alternative pulls only relevant parts of long reports. It also clarifies what it is not for (binary formats, scanned PDFs), making the tool's 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 explicitly says to prefer search_documents when only a relevant part of a long report is needed, providing a clear alternative and condition. It also warns that binary formats and scanned PDFs will not work, which helps an agent decide when to use this tool versus another.

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

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

The description discloses key behaviors beyond the annotations: determinism, the TTM summation rule for flow-based ratios on quarterly data, and the explicit 'null with a reason, never a guess' policy for missing inputs. These are valuable operational details not present in the schema or annotations.

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

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

Two sentences with no fluff. The core purpose and ratio list are front-loaded, followed by the key behavioral nuance. Every sentence carries essential information.

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

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

With an output schema present and annotations covering safety, the description addresses the most important behavioral nuance (missing inputs) and the TTM rule. It does not explain interaction between ticker and disclosure_id, but that is a minor omission given the schema descriptions.

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 high (83%), so the baseline is 3. The description adds context about the ratios list and the TTM behavior that relates to period and frequency, but it does not explain each parameter beyond what the schema already provides. It adds marginal value without compensating for any gaps.

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

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

The description clearly states the tool computes deterministic financial ratios and enumerates the specific ratio families (margins, liquidity, leverage, etc.). It distinguishes the tool from raw financial data tools like get_financials, though it does not explicitly name a sibling alternative.

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

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

The description provides usage context such as the trailing-12-month behavior for quarterly flow ratios and the null-with-reason behavior for missing inputs. However, it does not explicitly guide when to choose this tool over related tools like get_financials or get_metric_history, leaving that to 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 mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it states that each field includes source line/taxonomy name, reporting currency, and that KAP filings provide exact figures with quarter vs. cumulative labels. This helps set expectations about data provenance and format 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 dense but every part earns its place: what is returned, key fields, source metadata, the two invocation modes, and how to find FR ids. Even though it is a single paragraph, it avoids fluff and front-loads the core purpose before source-specific 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?

Given the tool's complexity (two data sources, many selectable fields, an output schema, and rich annotations), the description is thorough enough for an agent to decide when to call it and how to construct a valid request. The only minor omission is explicit comparison to get_financial_ratios, but that is not necessary 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?

With 80% schema coverage, the schema already documents most parameters. The description adds meaning beyond that by explaining the two mutually relevant parameter families (ticker vs. disclosure_id), the source difference, and the field source/taxonomy metadata. It also directs the agent to search_disclosures for constructing valid disclosure_id 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 identifies what the tool returns: income statement, balance sheet, and cash flow data in one normalized schema, with a concrete list of fields. It also distinguishes the two data sources (ticker vs. disclosure_id), which helps differentiate usage from related sibling tools like get_financial_ratios or compare_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 explains the two invocation modes: ticker for Yahoo Finance time series and disclosure_id for official KAP filings. It also points the agent to search_disclosures with a specific pattern to find FR ids, giving clear contextual guidance. It stops short of naming alternatives to avoid, but the source-selection guidance is strong.

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, idempotent, non-destructive behavior, and the description adds useful computation semantics: growth is relative to the absolute value of the previous period, so loss-to-profit swings are signed correctly. This goes beyond the schema and is valuable for interpreting results correctly. No contradiction with annotations.

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

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

The description is two tight sentences, with the core computation stated first and the important sign-handling caveat immediately appended. Every sentence earns its place and no filler 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 robust annotations, high schema coverage, and an output schema, the description adds the main missing behavioral nuance, the sign convention, and clarifies that the tool is the authoritative computed source. The main gap is the absence of explicit guidance on selecting this tool over sibling metrics tools, but the core invocation information is adequate.

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

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

Schema description coverage is 83%, so parameters are mostly self-documenting. The description adds no parameter-specific guidance beyond emphasizing one metric, leaving metric, ticker, periods, frequency, comparison, and disclosure_id semantics to the schema. This meets the baseline but does not exceed it.

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 a specific operation: computing period-over-period change for one metric, including current/previous values, absolute and percentage change. It does not explicitly name sibling tools, but the one-metric scope and the computed-here-not-by-the-model line help distinguish it from raw financials, history, and multi-metric comparison 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?

Computed here, not by the model implies the agent should call this tool rather than calculate growth itself, and one metric suggests it is aimed at single-series growth rather than multi-metric comparisons. However, it provides no explicit contrast with get_financials, get_metric_history, or compare_financials, nor any when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the source (Yahoo Finance) and the snapshot nature, which is useful context. It doesn't disclose staleness, update frequency, or whether values are delayed, but with annotations carrying the safety burden, a 3 is appropriate.

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

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

Two sentences with no waste. The instrument list is front-loaded, the data fields are specified, and the source is given. Every sentence earns its place.

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

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

For a zero-parameter read-only snapshot tool with an output schema present, the description is nearly complete. It states the instruments, fields, and source. The only minor gap is not describing update frequency or data delay, but the output schema likely covers return structure, and annotations cover safety.

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 schema provides no parameter semantics. The description compensates by specifying exactly what data is returned (instruments and fields), which is the only semantic content an agent needs. Baseline 4 for zero-parameter tools is correct.

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 resource (market overview) and enumerates exactly which instruments are included (BIST 100/30, bank index, USD/TRY, EUR/TRY, gold, Brent, S&P 500, DAX, VIX) plus the data fields (last, change %, 52-week range). This is a clear, specific verb+resource statement that distinguishes it from sibling tools like get_quote or get_price_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?

The description implies a snapshot/overview use case and the source (Yahoo Finance) is stated. It doesn't explicitly say when to use this over get_quote or get_price_history, but the zero-parameter snapshot nature and the explicit instrument list make the context clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the agent knows this is a safe, non-destructive read. The description adds that data is normalized and chart-ready, which is useful context, but does not explain further behavior like normalization specifics or response volume. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is concise, two sentences, with a clear example of the output format. It is front-loaded with the main purpose and adds the clarifying note that no charts are produced. No wasted words.

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

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

Given the tool's moderate complexity (4 params, 2 required, output schema present), the description is adequate for basic usage but does not specify normalization basis, time range defaults, or how to interpret the data. The sibling tools like get_financials suggest overlap, so more usage guidance would improve completeness.

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

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

Schema coverage is only 50%, but the description shows the exact output shape, which implicitly clarifies what the 'metrics' parameter should contain (keys in the response). It doesn't explain 'periods' or 'frequency' beyond schema, but the response example and metric names give enough guidance.

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 resource (time series of normalized financial metrics) and indicates it is chart-ready, distinguishing output format. It doesn't explicitly name a sibling to differentiate from, but the context and wording make its purpose clear.

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

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

Implied usage: for retrieving metric history in a structured format. It does not explicitly state when to use this instead of get_financials or compare_financials, but the chart-ready emphasis hints at use cases. No explicit 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 already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds useful context by stating the output is entirely numeric and uninterpreted, and by listing the computed summary fields. This goes beyond the annotations without contradicting them.

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

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

The entire description is one compact sentence that front-loads the core resource (OHLCV candles), includes the important computed fields, and closes with a differentiating constraint ('no interpretation'). Every part adds value and there is no filler.

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

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

Given a 7-parameter tool with 86% schema coverage, rich annotations, and an output schema, the description does not need to spell out every field or return structure. It successfully frames what the tool returns and its limitations, leaving only minor gaps like explicit sibling differentiation.

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 high at 86%, so the schema already documents most parameters well. The description adds meaning by connecting 'optional standard technical indicators' to include_indicators and clarifying the output is chart-ready, but it does not need to compensate much for undocumented parameters.

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

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

The description clearly identifies the tool as returning OHLCV candles with computed summary statistics and optional technical indicators. It distinguishes this from analytical or interpretation tools by explicitly stating 'chart-ready, no interpretation', and from related siblings like get_quote which presumably provides current price data.

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

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

The description implies usage through the phrase 'chart-ready, no interpretation', suggesting it should be used when raw price history is wanted rather than interpreted analysis. However, it does not explicitly name alternative siblings or state when not to use them, so usage guidance remains implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it clarifies that the computation is 'pure arithmetic on price data' and explicitly disclaims causal interpretation. It also discloses the after-close publication mapping behavior in the disclosure_id parameter description, which is a non-obvious behavioral detail.

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

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

The description is two sentences with zero waste. The first sentence front-loads the core output and scope, and the second sentence adds a crucial caveat about causation. Every word 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?

The tool has an output schema, so return values need not be described in detail. The description covers the core data, the event/disclosure input modes, and the non-causal nature of the computation. The only minor gap is that it does not explicitly state when to prefer this over get_price_history or get_company_timeline, but the event-centric framing and disclosure_id parameter make the use case clear enough.

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 60%, and the description adds value by explaining the event-date/disclosure_id duality and the after-close mapping behavior. The main description also clarifies that the output includes excess return versus BIST 100, which gives meaning to the tool's purpose. However, days_before and days_after semantics are only partially explained by the schema defaults and bounds, and the description does not elaborate on them further.

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

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

The description states a specific verb ('get') and resource ('price reaction around an event date'), and enumerates the exact data returned: daily closes, returns, volume, and excess return versus BIST 100. It also distinguishes itself from a causal analysis tool by explicitly disclaiming causation, which helps an agent understand what this tool 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 clearly implies when to use this tool: when an agent needs price/volume behavior around an event date or disclosure, and it explicitly notes the tool does not assert causation, which is a useful exclusion. It does not name sibling alternatives like get_price_history or get_company_timeline, but the event-centric framing and the disclosure_id parameter provide enough context for an agent to select it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond those: bad symbols return an error entry without failing the whole batch, and Yahoo data is delayed for BIST. This is valuable but does not cover broader failure modes 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?

Every sentence earns its place: the first defines the payload and output fields, the second covers error isolation, and the third notes the source and BIST delay. There is no filler, and the core 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?

Given the single well-documented parameter, rich annotations, and an output schema, the description covers the essential remaining context: batch error behavior and source latency. Nothing critical 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?

Schema description coverage is 100%, so the symbol parameter is already well documented with accepted formats like THYAO, XU100, USDTRY, and GOLD. The tool description only reconfirms that data is per symbol and adds no new parameter-level semantics, making the baseline 3 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 identifies a read-only quote retrieval action with a specific resource (latest price data per symbol) and enumerates the exact fields returned. The 'per symbol' batch framing and field list distinguish it from time-series or market-overview siblings like get_price_history and get_market_overview.

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

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

The description implies usage for current snapshot quotes and lists supported symbol categories, but it never explicitly says when to use this tool versus alternatives or when not to use it. Agents must infer that historical price data belongs to get_price_history.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds the valuable detail 'No network call', which is a behavioral trait not captured by annotations, and lists the content domains. It does not describe return format, but the presence of an output schema mitigates that need.

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

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

The description is a single sentence that is front-loaded with the primary purpose ('Code tables used across tools') followed by a concise enumeration of content areas and the key behavioral note about no network call. Every element earns its place with no redundancy.

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

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

Given that there are no parameters, an output schema exists, and annotations cover safety and idempotency, the description is complete enough. It specifies what code tables are included and that no network call is made, which is sufficient for an agent to understand when and how to invoke it.

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

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

There are zero parameters, so schema coverage is trivially 100%. With no parameters to explain, the description adds no parameter-specific semantics, but it also doesn't need to. The baseline for 0 parameters is 4, and the description appropriately focuses on content rather than parameters.

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

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

The description clearly states the tool's purpose: it provides code tables used across tools, listing specific categories like disclosure types, member types, and financial field names. This is a specific verb-less but informative description that distinguishes it from sibling data-retrieval tools, which all focus on specific entities or operations.

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

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

The description implies its use case (reference/code lookup) but does not explicitly state when to use it vs alternatives, nor does it mention any exclusions. It says 'used across tools', which suggests it's a support resource, but there's no direct guidance on when an agent should call it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the diagnostic behavior (checking config/connectivity) but doesn't detail what specific checks are performed or what the output contains. With annotations covering safety, a 3 is appropriate.

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

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

Two sentences with no wasted words. The purpose is stated first, followed by actionable usage guidance. Every sentence earns its place.

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

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

For a zero-parameter diagnostic tool with an output schema and strong annotations, the description is nearly complete. It could mention what kind of output to expect (e.g., status fields, error codes), but the output schema likely covers that. The usage guidance is strong enough to make the tool safely invocable.

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 schema provides no parameter semantics. The description compensates by explaining the tool's purpose and when to call it, which is sufficient for a no-argument diagnostic tool. Baseline 4 for zero params 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 performs a configuration and connectivity check, and it distinguishes itself from data tools by framing it as a diagnostic step. It could be more explicit about what 'status' returns, but the verb 'check' and resource 'configuration and connectivity' are specific enough.

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 guidance: 'Call first when other tools fail' and explains the diagnostic purpose—distinguishing configuration problems from data problems. This is strong usage guidance that tells the agent when to use it and what it helps determine.

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 cover readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful extra behavior: exact ticker matches rank first, and the returned company_id is consumed by other KAP tools. This goes beyond the structured annotations without contradicting them.

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

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

Three short sentences, front-loaded with the main purpose, then the output value, then the routing guidance. There is no filler 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?

The tool has an output schema, strong annotations, and a description that explains purpose, usage conditions, result ranking, output relevance, and an alternative. Nothing an agent needs to decide whether to call this tool or how to use it effectively 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 50%, so the description does not fully carry the load, but it reinforces query semantics ('by ticker or name') and adds the ordering behavior ('Exact ticker matches rank first'). The remaining limit and offset parameters are self-explanatory with defaults in the schema, so the description does not need to add much.

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

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

The description uses a specific verb ('Find'), names the resource ('KAP members'), and states the searchable fields ('ticker or name') and the key output ('company_id'). It clearly distinguishes itself from get_company by noting that get_company is for the full profile.

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 an explicit trigger condition: 'Use when the user names a company.' It also names the main alternative, get_company, and the condition that redirects the agent elsewhere, which is exactly the kind of routing guidance needed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond annotations: 'Turkish-insensitive' (a search behavior) and 'return path/value pairs' (output format). It also implies efficiency ('without reading the whole body'). No contradiction with annotations.

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

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

The description is two sentences with no fluff. The core function is stated first, followed by a concise usage directive. It is front-loaded with the most important information and each sentence contributes value.

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

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

Given that an output schema exists (per context signals) and annotations cover safety and idempotency, the description is largely sufficient. It clarifies the purpose, use case, and a key behavioral trait (Turkish-insensitivity). The only missing detail is behavior regarding 'sub_report_list' and what defines a 'match' (exact vs fuzzy), but these are minor gaps for a search tool. Overall, an agent can confidently call this tool.

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

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

Schema coverage is only 25% (only 'query' has a description). The description implicitly covers disclosure_id ('disclosure's structured data'), and the schema's query description gives examples. However, the description does not explain the 'limit' or 'sub_report_list' parameters, which are not described in the schema. Given low schema coverage, the description should compensate more, but for a search tool the parameters are fairly self-explanatory (limit is a count, sub_report_list likely filters sub-reports). Baseline 3 is appropriate.

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

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

The description states a specific verb ('Find'), resource ('matching fields inside a disclosure's structured data'), and specifies the domain (financial statement line items, form fields). It also notes the return type ('path/value pairs') and a key feature ('Turkish-insensitive'). This distinguishes it from sibling tools like search_documents (which likely searches full text across documents) and get_financials (which may return entire financial 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 description explicitly tells agents when to use it: 'Use to pull single figures from an official KAP financial report or form without reading the whole body.' This implies it is preferred over get_document_text when a specific figure is needed. It does not explicitly name alternatives or exclusions, but the use case is clear enough for an agent to select it.

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

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

Beyond the annotations, the description discloses non-obvious behavior: the KAP API pages by index, wide ranges require checking scan_complete, and callers must continue with cursor or raise max_pages. It also explains the difference between metadata and content scanning and notes the per-item cost of content matching, which is valuable operational context.

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

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

Three sentences deliver a dense but efficient overview: core search capability, use cases, and a crucial paging caveat. Every sentence earns its place, and the main purpose is front-loaded before operational 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 14-parameter tool, the description is remarkably complete alongside the rich schema and output schema. It covers what the tool searches, key use cases, paging behavior, performance caveats, and the shape of returned items, so an agent has enough context to invoke 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 description coverage is 86%, so parameter semantics are already well documented. The description adds little beyond the schema: query_scope='content' is already explained in the query parameter, and since_id is already described as polling in the schema. It does not materially deepen parameter understanding, so the baseline 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 names a specific verb and resource—'Search KAP disclosures'—and immediately enumerates the filter dimensions and supported use cases. Its scope is precise enough to distinguish it from sibling tools like get_disclosure or search_documents, and the mention of monitoring by since_id and content-scoped keyword hunts gives it a clear identity.

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 lists when the tool is appropriate: latest disclosures, a company's disclosures over a period, monitoring via since_id, and cross-company topic searches. It does not name alternatives or exclusions, but the use-case coverage is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful behavioral context by promising snippets with page numbers and source_url instead of whole documents, which shapes agent expectations about the granularity of the result.

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

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

Two short sentences accomplish a lot: the first explains functionality and output format, the second gives a concrete use case. There is no filler or repetition of schema or annotation 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?

With rich annotations, an output schema, and a well-documented input schema covering 80% of parameters, the description only needs to explain the tool's purpose and distinguishing behavior. It does, so nothing essential 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 80%, so the schema already documents most parameters including query, attachment_id, context_chars, and disclosure_id. The description adds no parameter-level semantics beyond the schema, so the 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 names a specific action ('Find passages') and a specific resource ('disclosure attachments'), and it clearly defines the return shape: short snippets with page numbers and source_url instead of whole documents. This strongly distinguishes it from sibling tools that return whole documents or broader disclosure search results.

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

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

The description gives a clear use case ('what does the report say about X') and implies it is the passage-level search tool, not a document-download tool. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to route correctly.

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 safety (readOnly, idempotent, non-destructive) and open-world. The description adds behavioral nuance: it clarifies that the tool returns registry metadata only, and that passing fund_id switches to a detail record. This goes beyond the annotations without contradicting them.

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

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

Two sentences with no filler. The main purpose is front-loaded, and the exclusion of prices/returns is delivered as a concise clarification. Every word 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 7-parameter tool with an output schema and strong annotations, the description covers the essential distinctions (list vs. detail, registry vs. pricing). It doesn't explain pagination or fund_class semantics, but those are either self-evident or defined in the schema. Overall, an agent can call this correctly with the given information.

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 57% – moderate. Several parameters (query, fund_id, fund_type, fund_state) have descriptions, but limit, offset, and fund_class do not. The tool description does not elaborate on any parameter, but the mention of 'type, class, state' hints at what fund_type and fund_class filter on. This adds a little context but does not fully compensate for the gaps.

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 searches investment funds registered on KAP, lists the key fields (identity, type, class, state, founder, KAP URL), and distinguishes the list vs. detail behavior via fund_id. It also explicitly excludes prices/returns, which disambiguates it from price-focused sibling tools.

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

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

The description gives a clear context (registry data) and an implicit exclusion (prices/returns not here), which steers the agent away from using this tool for financial data. However, it does not name specific alternative tools (e.g., get_quote, get_price_history), so it stops short of explicit when-not guidance.

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