AIsa Equities

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

Annotations already declare destructiveHint=true and openWorldHint=true, so safety is covered. The description adds valuable behavior: independence of items (one failure doesn't cancel others) and per-call billing. These are not derivable from annotations and help the agent set expectations.

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 with zero filler. The action and limit are front-loaded. The phrase 'tool-router's batch_use' is redundant since it restates the tool name, but it's a minor flaw. Overall it is concise and well-structured.

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

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

With annotations covering destructive behavior and an output schema presumably describing results, the description covers the key operational aspects: concurrency limit, independence, and billing. It doesn't mention error reporting formats, but those likely live in the output schema. It is sufficiently complete for a batch tool.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds no parameter-specific details. The calls parameter's description already explains the structure and batching context, so the baseline of 3 applies; the description doesn't need to compensate.

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 clear action (execute) and resource (operations) with a concrete limit (up to 20) and concurrency. It doesn't explicitly name the sibling 'use' for single operations, but the distinction is clear enough from the concurrency and limit. The redundancy of 'tool-router's batch_use' is minor.

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 no guidance on when to use this tool versus the sibling 'use' tool. The schema note about 'steps at the same execution_level of a plan go in one batch' is helpful, but it lives in the schema, not the description. The description only implies batching via concurrency but doesn't state when to choose it over the single-operation alternative.

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 idempotentHint=true, but the description adds valuable behavioral context: it returns `total_filings` and `returned` so a filtered view cannot be mistaken for the whole day, it does not rank results, and it provides measured payload sizes (112 KB unfiltered, 73 KB with listed_only, ~10 KB with doc_type_code). These details go beyond generic annotations and inform the agent about response characteristics and data volume.

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 the core purpose and then elaborates with relevant details. It is longer than minimal, but every sentence earns its place: upstream comparison, field list, filtering behavior, size measurements, and return fields. The structure is logical, moving from general purpose to specifics. A slightly tighter wording could improve it, but it remains efficient.

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

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

The description is thorough for an agent to invoke correctly. It explains the filtering semantics, the return fields (`filings`, `total_filings`, `returned`), the relationship to the upstream tool, and the date format. Since an output schema exists, it need not detail return structure. Nothing critical is missing; the description covers all necessary operational details.

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

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

Schema coverage is 0% (no descriptions in the schema), so the description must fully explain parameters. It does: `date` is YYYY-MM-DD, `listed_only=true` keeps filings with a secCode (~two thirds of a day), and `doc_type_code` matches exactly with concrete examples (120, 140, 160, 350). This gives the agent complete semantic understanding of all three parameters, far exceeding what the schema provides.

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

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

The description states a specific verb and resource: 'One day of Japanese EDINET filings as a scannable list, with the filtering upstream lacks.' It clearly identifies the tool's function and differentiates it from the sibling `get_edinet_documents` by highlighting the filtering capability. The mention of six fields and the explicit contrast with the upstream tool leaves no ambiguity about what this tool does.

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

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

The description names the sibling `get_edinet_documents` and contrasts it: the upstream has no filter parameters and returns raw fourteen-field records, while this tool provides filtered six-field records. It also states 'It does NOT rank or select beyond your filters,' clarifying scope. However, it does not explicitly say 'use this when you need filtered results, use the upstream when you need full records,' leaving the decision slightly 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context: it is free, stops before any spend, and explains how price.model varies (quoted, list, dynamic, composed). It also clarifies that suggested_max_price_usd has headroom. This goes beyond the annotation flags and gives the agent a clear model of what happens.

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

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

The description is moderately long but well structured: it opens with the core purpose, then explains the price model in a dedicated paragraph. No redundancy or filler. It front-loads the most critical information (contract fields) and then gives necessary detail about price semantics. Slightly dense but not overly verbose.

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

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

The tool has an output schema, so return values need no description. The description covers the key behavioral aspects (no spend, pricing models, max_price headroom) and clarifies edge cases like routes without a price. For a read-only informational tool, this is complete enough for an agent to use it correctly.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds some nuance, such as how arguments affect pricing and that required parameters may be needed before a price can be quoted. It also clarifies with_quote's purpose (one round trip, spends nothing). These are useful but not essential given the schema's completeness.

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

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

The description states a specific purpose: returning the full contract of one or more operations, including schemas, read_only, side_effects, price, and known_pitfalls. It clearly distinguishes this from executing operations (use, batch_use) and from discovery (search, list_categories). The verb 'get' and the noun 'details' align with the title, and the first sentence is explicit.

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

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

The description implies the tool is used to assess an operation before spending (e.g., 'A quote authenticates like a call but stops before any spend'), and the schema says 'One operation_id from search', hinting at a flow. However, it never explicitly states when to choose this over siblings like use or search, nor does it give exclusions. The guidance is implied, not stated.

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

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

Beyond annotations that already mark it read-only, idempotent, and non-destructive, the description adds meaningful behavioral context: the typical payload size (612 KB), the impossibility of filtering, the data distribution around secCode, and the downstream use of docID. This helps an agent anticipate cost and output shape before calling.

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 sentence earns its place: it states the core action, explains both response modes, warns about payload size, notes data characteristics, and links to the next logical tool. The most important scoping information is front-loaded.

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

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

For a two-parameter, read-only API with an output schema, the description covers everything needed to call it correctly: required date, type differences, return locations, size/performance caveat, absence of filters, and onward data flow. Nothing an agent needs is left to guesswork.

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 well beyond the schema by explaining exactly what each type value returns, where the count lives in type=1, and which fields appear per filing in type=2. It also reinforces the required date format, making parameter choice unambiguous.

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

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

The description opens with a specific verb and resource: 'Lists every disclosure filed with Japan's EDINET on one date.' It also clarifies the lack of filters, which differentiates it from any filtered disclosure tool and explicitly connects docID to the downstream download 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 gives clear operational guidance: date is required, type=1 gives count and metadata, type=2 returns the full filing list, and users should check the count first when in doubt. It does not explicitly name alternatives among siblings like edinet_filings_digest, so it falls short of full when-not/alternative 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, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context: it is forward-looking consensus, deliberately narrow in scope, and excludes certain data types. This goes beyond the annotations and sets clear expectations about the data's nature, though it doesn't mention any rate limits or auth requirements (not essential for a read-only financial tool). 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?

Three sentences with no filler. The first sentence front-loads the core function and output fields; the second gives parameter semantics; the third states scope and directs to the sibling. Every sentence earns its place, and the structure is immediately 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?

Given the output schema exists (covering return values) and the input schema fully documents parameters, the description provides all additional context an agent needs: the nature of the data, the required parameter, the period/limit semantics, and the alternative tool for actuals. Nothing critical is missing for a tool of this complexity.

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

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

Schema coverage is 100% so the baseline is 3. The description adds meaning beyond the schema: it clarifies that ticker is required, explains that 'period' selects annual vs quarterly, and that 'limit' caps the number of periods returned. It also previews the response fields. The description effectively reinforces and expands on the schema, earning a 4.

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

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

The description states a specific verb ('get'), resource ('forward analyst consensus for one stock'), and enumerates the exact fields returned ('fiscal_period', 'period', 'revenue', 'earnings_per_share'). It explicitly contrasts itself with get_financial_earnings, making the distinction between estimates and actuals unmistakable. This is a clear, non-tautological purpose statement.

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

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

The description provides explicit usage guidance: 'Use it for what the street expects' and directs to get_financial_earnings for actual reported results and beat/miss. It also states the deliberate narrowness (no names, ratings, targets, dispersion), telling the agent exactly when NOT to use it. This fully satisfies the when/when-not requirement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by specifying the exact data returned (identity and classification fields) and explicitly stating 'No prices and no fundamentals at all,' which prevents misuse. It also notes the input flexibility (either ticker or cik), but does not discuss potential error cases or rate limits—though these are not critical given the annotations and simple nature of the tool.

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

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

The description is concise and well-structured. It front-loads the core purpose with the field list, then adds the negative scope (no prices/fundamentals), and finally gives concrete usage examples. Every sentence contributes information, and there is no redundancy or fluff.

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

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

The tool is simple with only two optional parameters, and it has an output schema (indicated by 'Has output schema: true'), so the description doesn't need to explain return values. It covers the input alternatives, the data scope, and typical use cases. Nothing is missing for an agent to correctly invoke 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?

The input schema has 100% description coverage for both parameters (ticker and cik). The description adds the semantic nuance that the tool accepts either ticker or cik, implying they are alternatives rather than both required. This clarification goes beyond the schema's individual parameter descriptions and helps the agent understand the relationship between the two 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 function: retrieving identity and classification data for one company. It enumerates specific fields (name, ticker, cik, sector, etc.) and explicitly excludes prices and fundamentals, distinguishing it from financial data tools. The mention of resolving a ticker to cik also sets it apart from sibling tools like get_financial_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?

The description provides explicit usage guidance: 'Use it to resolve a ticker into the cik that the filings tools accept, or to confirm what sector a company is actually classified under before comparing it to peers.' This clearly states when to use the tool and gives an alternative purpose. It also implicitly states when not to use it (no prices/fundamentals).

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 clear. The description adds value by detailing the response structure: each entry carries report_period, fiscal_period, filing_date, filing_url, accession_number, a quarterly block with revenue/estimated_revenue/revenue_surprise/revenue_surprise_pct, the same for earnings_per_share, year-over-year change fields, and signals with flags like EPS_BEAT. It also notes that ticker is required and the only parameter. This goes beyond the annotations to explain what the agent will receive and how the data is organized. It doesn't mention rate limits or pagination, but for a single-ticker snapshot with an output schema, this is sufficient.

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

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

The description is well-structured and front-loaded: it starts with the core purpose, then details the response fields, then gives usage guidance. Every sentence adds value. It is appropriately sized for the complexity of the tool, covering the key output structure and the routing rule without unnecessary fluff.

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

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

Given the tool has one required parameter, a rich output schema, and clear annotations, the description is complete. It explains what the tool returns in detail, names the alternative for forward-looking estimates, and confirms the only parameter. An agent has everything needed to invoke it correctly and interpret the result. The output schema exists, so the description doesn't need to explain return values further.

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% (the only parameter, ticker, is described as 'The ticker symbol.'). The description adds context by stating 'ticker is required and it is the only parameter,' which reinforces the schema. It also implies the ticker identifies the stock whose earnings are returned. Since the schema already covers the parameter fully, the description's additional emphasis on it being the only parameter is helpful but not extensive. Baseline 3 is appropriate, and the explicit statement about it being the only parameter nudges it to 4.

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

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

The description clearly states the tool's purpose: 'Reported earnings for one stock, actuals against estimates.' It specifies the resource (earnings for one stock) and the verb (get/report), and distinguishes it from the sibling tool get_financial_analyst_estimates by explicitly noting the difference between actuals and forward-looking estimates. This makes it easy for an agent to select the correct 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 explicitly says 'Use it for what a company actually reported. For forward-looking consensus that has not happened yet use get_financial_analyst_estimates instead.' This provides clear when-to-use and when-not-to-use guidance, naming the alternative tool. This is exactly the kind of routing information an agent needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns a list/index rather than contents, and each entry carries specific fields. It doesn't mention pagination or rate limits, but the core behavior is well disclosed.

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 and front-loaded: it states the core purpose in the first sentence, lists return fields, then covers parameters and usage guidance. Every sentence earns its place with no fluff.

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

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

The tool has an output schema, so return values are already documented. The description covers purpose, scope, parameters, and the sibling tool for next steps. It lacks explicit mention of pagination or default behavior beyond limit's default, but the description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds a little context by mentioning ticker/cik, filing_type narrowing, and limit capping, but it doesn't add meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns the SEC filing index for one company, explicitly distinguishing it from filing contents. It lists the exact fields returned and names the sibling tool for reading filing text, making its purpose unambiguous.

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

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

The description explicitly says to use this tool to find which filing you want and get its accession_number, and directs users to get_financial_filings_items for reading text inside a filing. This provides clear when-to-use guidance and an explicit alternative.

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 valuable behavioral context beyond the annotations: the large payload warning ('a 10-K comes back as roughly 19 items of full prose') and the return structure (items with number, title, text, plus filing_url and accession_number). This goes beyond what the annotations provide, though it doesn't address auth, rate limits, or error cases.

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

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

The description is four sentences with no redundant phrasing. It front-loads the purpose, then concisely covers required vs. optional parameters, return shape, a practical size caveat, and the sibling-tool pointer. 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 output schema already documents the return shape, the description still adds the crucial size warning and the routing to get_financial_filings. It tells the agent exactly when to use this tool, how to narrow the request, and what to expect in terms of payload size. No critical information is missing for a read-only retrieval tool.

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

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

Schema description coverage is 100% – every parameter already has a description in the schema, including which filing types each parameter applies to (e.g., quarter for 10-Q, accession_number for 8-K). The description merely restates the required parameters and the optional narrowing parameters without adding new semantic details. It meets the baseline but doesn't significantly enhance parameter understanding beyond the schema.

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

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

The description opens with a specific verb and resource: 'The full text of the numbered items inside one SEC filing.' It clearly differentiates from the sibling get_financial_filings by stating that the sibling is for finding which filing to open, while this tool retrieves the items within a filing.

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 names the alternative get_financial_filings and states when to use it ('To find which filing to open in the first place'). It also gives actionable guidance on when to request a specific item vs. the whole document via the size warning ('request a specific item rather than pulling everything unless you truly need the whole document').

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 behavioral context beyond that: it specifies the output structure (about 49 ratios per period, stamped with report_period and fiscal_period) and the requirement that period is mandatory, with ticker or cik as identifiers. This is useful extra context about the data shape and invocation constraints, though it does not discuss pagination or limit behavior, which is acceptable given the output schema 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 longer than average but each part earns its place: it lists key ratios, specifies the period stamping, states the required parameter, and gives usage guidance with an alternative. It is front-loaded with the core purpose and does not waste words, though the list of ratios could be trimmed for brevity without losing 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?

With an output schema present, the description does not need to detail return values. It adequately explains what the tool returns (ratios over time), the period requirement, identification methods, and the alternative snapshot tool. It does not mention pagination or limit behavior, but the schema has a limit parameter and the output schema likely covers structure. Overall, it is complete enough for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so every parameter is documented in the schema. The description mostly reiterates what the schema already says: period is required, and ticker or cik can be used for identification. It does not add new meaning about parameter values or formats beyond the schema. Therefore, the baseline of 3 applies, as the description adds minimal extra semantic value.

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

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

The description clearly states it returns computed ratios for one company over time, enumerating many specific ratios (market_cap, enterprise_value, etc.). It also distinguishes itself from the snapshot sibling by noting the snapshot is one row and much smaller. This is a specific verb+resource description that allows an agent to understand exactly what the tool provides.

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 'Use it to trend a ratio across periods' and contrasts with the snapshot tool for current values only. This gives clear when-to-use guidance and names the alternative, leaving no ambiguity about which sibling to select.

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 readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful behavioral context: it returns a single snapshot object, is current-only, takes no period argument, and can use either ticker or cik.

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 and well-structured: it front-loads the comparison to the sibling, lists representative fields briefly, then states usage and the alternative. Each sentence earns its place, and no material is repeated from the schema or annotations.

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

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

The output schema already covers return value structure, and the description supplies the remaining context: what the snapshot represents, what fields to expect, when to use it, and which sibling to use instead for history. An agent has everything needed to select and 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?

The input schema already covers 100% of the parameters, so the baseline is 3. The description adds value by clarifying that only ticker or cik are accepted, that no period argument exists, and that either identifier can be used, which helps the agent pick the 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?

Says exactly what the tool returns: a current-only snapshot of the same ratio set as get_financial_financial_metrics, with about 41 fields grouped by category. It clearly distinguishes it from its historical sibling by name and behavior, so an agent can disambiguate immediately.

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 when-to-use statement ('Use it to size up a company right now') and an explicit when-not-to-use with the alternative ('For history... use get_financial_financial_metrics'). It also notes the absence of the period argument, so the agent knows it is not for time-series analysis.

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 return structure (financials object with three arrays, each matching dedicated tool shapes) and clarifies that period is required and company identification via ticker or cik. This enriches behavior beyond annotations without contradiction.

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

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

Two sentences with zero waste. The first sentence states purpose and return shape; the second gives usage guidance and alternatives. Information is front-loaded and 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, the 100% schema coverage, and the description covering the primary use case plus alternatives, nothing essential is missing 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 description coverage is 100% with every parameter documented. The description repeats period requirement and ticker/cik usage but adds no new semantic detail beyond what the schema already provides. Baseline 3 applies for high schema coverage.

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

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

States a specific verb 'get' and resource 'all financial statements' (all three for one company), and clearly distinguishes from dedicated statement tools and search line items by naming them. The scope 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?

Explicitly says when to use it: when you need the full picture and would otherwise make three calls. It also names the alternatives (dedicated statement tools, search line items) and the conditions that select them, leaving no inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable behavioral context: it enumerates the ~36 fields returned, notes that the result is per company, and mentions the report/fiscal/currency stamps. It does not describe pagination or limit behavior, but that is minor given the output schema and annotations. 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 zero filler. The first sentence front-loads the return content (fields and structure), and the second sentence gives usage guidance. Every word adds value, and the structure is clean and efficient.

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

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

Given the tool has a well-defined output schema and 100% schema parameter coverage, the description covers the essential purpose, usage, and return content. It addresses the primary decision point (balance sheets vs. metrics) and notes the required period. There is nothing an agent needs to know to call it correctly that is missing; the schema and annotations fill the remaining gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context about the return fields and usage but does not materially enhance parameter understanding beyond the schema. It restates that period is required (already in schema) and does not explain the enum values or the ticker/cik requirement (the schema handles those). Thus it 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 states a clear verb+resource: it returns balance sheets for one company, and enumerates the key fields included. It distinguishes itself from the sibling get_financial_financial_metrics by explicitly noting that tool covers ratios computed from these numbers, and it also implicitly differentiates from income/cash flow statements by naming the financial statement type. An agent can immediately understand what this tool does.

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

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

The description explicitly tells when to use it ('for capital structure and liquidity') and directs the agent to the alternative for ratios ('For the ratios already computed off these numbers use get_financial_financial_metrics'). It also states that period is required, which guides usage. This is clear, actionable guidance with a named sibling and exclusion condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds context about the data scope (about 27 fields per period, field names, and that results are stamped with report_period, fiscal_period, and currency) which helps set expectations about output shape 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 efficiently structured with the main purpose front-loaded, followed by a list of notable fields and usage guidance. While the field enumeration is long, it is informative and directly aids an agent in understanding what the tool returns. The backtick formatting improves readability. No redundant or filler content.

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

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

Given the complexity (9 parameters) and the existence of an output schema, the description is complete: it states what the tool returns, when to use it, and where to go for related metrics. Required parameters are flagged, and the output schema handles return details. 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 coverage is 100%, so all parameters are already described in the input schema. The description only reiterates that 'period' is required (already in the required array) and gives context about the return fields, but does not add parameter-specific semantics beyond the schema. This matches the baseline of 3 for high coverage.

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

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

The description uses a specific verb ('Get') and resource ('cash flow statements for one company'), enumerates the key fields, and differentiates itself from the sibling tool get_financial_financial_metrics by explicitly stating that derived figures like free cash flow yield live there. This makes its purpose unambiguous and distinguishes it from related financial statement 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 provides clear when-to-use guidance ('Use it to see cash generation rather than accounting earnings') and names the alternative tool for derived metrics ('Free cash flow yield and similar derived figures live in get_financial_financial_metrics'). It also highlights that 'period' is required, which is essential for invocation. Exclusions and alternatives are 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 safety is covered. The description adds context about the output structure (fields and stamps) and the required period parameter, which goes beyond the annotations and helps the agent understand what to expect.

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

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

The description is a single well-organized sentence that front-loads the purpose, lists key fields, mentions the stamps, and then gives usage guidance. Every part 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?

The tool has a rich schema and an output schema (as indicated), and the description covers purpose, usage, and field details. It doesn't explicitly state that a company identifier (ticker or cik) is needed, but the schema makes that clear. Overall, it's complete enough 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 description coverage is 100%, so all 9 parameters are already documented in the schema. The description adds little beyond what the schema provides, though it does highlight that `period` is required and lists its enum values. This meets the baseline for high coverage.

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

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

The description explicitly states the tool returns income statements for one company and enumerates the key fields, making the purpose unmistakable. It also distinguishes itself from siblings by noting that for all three statements at once, one should use get_financial_financials, so an agent can tell them apart without inspecting 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?

It gives a concrete use case ('Use it for the revenue-to-earnings walk') and explicitly names the alternative tool for combined statements. This is clear guidance on when to use this tool vs. its siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so safety is covered. The description adds meaningful behavioral context: data is Form 4 transactions, scoped to one ticker, with a required ticker and available filters. It does not contradict annotations, and it provides enough operational detail without overclaiming.

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 with the core purpose. The field enumeration is long but organized into logical groups (person, trade, position, filing), and the filtering sentence is compact. It earns its length by clarifying output shape and usage, though some field details are redundant with 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 the rich input schema, output schema, and annotations, the description is complete for agent invocation. It states the data domain, required parameter, output row composition, and filter options, all in one coherent block. An agent can select and call this tool correctly without needing additional context.

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

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

Schema description coverage is 100%, so the schema fully documents all nine parameters, including examples and date formats. The description adds modest grouping value by naming ticker as required, highlighting name/transaction_type filters, and grouping the filing-date bounds, but it does not substantially exceed the schema's parameter documentation.

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

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

The description opens with a specific verb-resource pair: 'Form 4 insider transactions for one stock.' It clearly distinguishes the tool from general financial filing or market-data siblings by focusing on insider trades and enumerating the exact per-row content (person, trade, resulting position, filing). An agent can immediately understand what this tool returns.

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 an explicit use case: 'Use it for who inside the company bought or sold and when.' This gives clear context for when to select the tool. However, it does not name alternative siblings or state when NOT to use it, so it stops short of full routing guidance.

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

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

Annotations already declare read-only and idempotent behavior, and the description adds beyond that: the uppercase case-sensitivity trap, the misleading HTTP 404 'No data found' result, and the list of valid bank codes. This extra behavioral context is highly valuable and goes well 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 compact and front-loaded: it opens with the data shape, moves to required parameter behavior, and then gives the critical edge case. The valid-code list slightly overlaps the enum, but it earns its place by supporting the actionable uppercase warning.

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 annotations covering safety and an output schema present, the remaining needs—required parameter, valid codes, case sensitivity, date binding, and the snapshot alternative—are all addressed. Nothing essential is missing for an agent to call 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 coverage is 100%, so the schema already documents the parameters. The description still adds meaning by explaining the relationship between `bank`, `start_date`, and `end_date`, and by emphasizing the case-sensitivity warning that affects how the agent interprets failures.

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 operation: retrieving one central bank's policy rate over time, and names the exact output shape (`interest_rates` array of `bank`, `name`, `date` and `rate`). It also distinguishes the tool from its sibling `get_financial_macro_interest_rates_snapshot` by noting the snapshot lists valid codes, so an agent can tell them apart.

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

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

It clearly says `bank` is required, explains the date-bounding relationship, and directs the user to the snapshot tool for listing valid codes. It does not explicitly state when not to use this tool versus other financial siblings, but the context is strong enough for correct selection.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive, so the safety profile is fully covered. The description adds useful behavioral context beyond the annotations: the exact array structure, that omitting `bank` returns all ten, and that the response surfaces valid bank codes. This is solid additional transparency.

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

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

Three sentences, no filler: the first states purpose and output shape, the second explains the optional parameter and discovery mechanism, and the third gives the sibling alternative. Every sentence contributes directly to correct selection and invocation.

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

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

For a tool with one optional parameter, rich annotations, an output schema, and a close sibling, the description covers purpose, invocation behavior, alternatives, and return structure. Nothing needed for correct selection or calling 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 schema description coverage is 100% and the enum already enumerates all valid codes. The description does add that omitting `bank` returns all ten and that this is also how codes are discovered, but this largely mirrors what the input schema already communicates. The added value is real but modest, so baseline 3 is appropriate.

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

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

The description names a specific verb and resource: it returns current policy rates for the ten tracked central banks, and clarifies the output shape as an `interest_rates` array. It also explicitly distinguishes itself from the sibling `get_financial_macro_interest_rates`, so an agent can tell them apart without inspecting 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?

It states when to use this tool ('Use it for the current rate backdrop') and when not to, by directing the agent to `get_financial_macro_interest_rates` for a single bank's rate path over time. It also explains the omission behavior for retrieving all ten banks, leaving no ambiguity about invocation strategy.

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. The description adds behavioral constraints beyond that: headlines only (no body, follow url), no full-text search, no date filter, and the ability to omit ticker for broad market news (though schema mentions this, the description reinforces it). 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 dense but not excessively long. It front-loads the core purpose and output, then adds limitations and alternatives. Each sentence contributes value, though it could be tightened slightly by merging the ticker/limit clarification.

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 two optional parameters, the description fully covers what an agent needs: output structure, limitations, and alternative tools. The output schema presence is acknowledged, but the description itself specifies the returned fields. No missing information 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%, so both parameters are documented. The description adds value by explaining how to use limit as a narrowing mechanism given the lack of search/filter, and clarifies ticker's role. It doesn't introduce new semantics beyond the schema but provides usage context.

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

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

The description explicitly states the tool returns recent news headlines for a stock, listing the exact fields (title, source, date, url, ticker) in a news array. It clearly differentiates from siblings by noting the absence of full-text search and date filter, and contrasts with get_financial_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?

It provides explicit guidance: 'Use it for recent coverage of a company you have already identified,' and gives a specific alternative for filings ('use get_financial_filings'). It also explains how to narrow results via limit instead of query, covering when-not 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?

The annotations already establish a safe read-only, idempotent operation. The description adds useful behavioral context beyond that: all four inputs are mandatory, there is no shortcut, and the response is wrapped in a `prices` array with an echoed `ticker`. Minor gaps remain, such as date-inclusivity, timezone handling, or market-adjustment policy, but these are secondary for a read-only OHLCV tool with an output schema.

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

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

Four sentences, each earning its place: purpose, parameter constraints, response shape, and usage routing. The most important information is front-loaded, and there is no filler or redundant expansion beyond what is needed.

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 full input schema, output schema, and annotations, the description is nearly complete for both selection and invocation. It covers required parameters, response format, and sibling routing. A small gap is the lack of explicit date-boundary behavior (e.g., whether start and end dates are inclusive, timezone assumed), which could matter when measuring a move across a known window, but this is minor and does not block correct tool selection.

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 every parameter already has a clear description, including the interval enum and date format. The description repeats that all parameters are required and enumerates interval values, but does not add meaning beyond the schema, such as inclusive/exclusive date semantics or how intervals map to bar boundaries. 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 opening line, 'Historical OHLCV bars for one stock', states a specific verb-resource pair and scope. It further distinguishes itself from `get_financial_prices_snapshot` by contrasting historical bars with the latest price, and mentions the response fields, leaving no ambiguity about what the tool returns.

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: 'Use it to chart or to measure a move across a known window.' It also gives an exclusion and alternative: 'For just the latest price use get_financial_prices_snapshot.' It additionally warns that all four parameters are required with no trailing-window shortcut, preventing an agent from making an invalid invocation.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds performance context ('cheapest and fastest way') and clarifies it returns real-time snapshot data. It does not mention pagination or limits, but for a simple single-stock snapshot this is acceptable. 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 efficiently structured: it front-loads the return fields, then states the required parameter, gives usage guidance, and names alternatives. No filler or redundant phrases. Every clause contributes to the agent's decision or call correctness.

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

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

With an output schema present, the description doesn't need to explain return values, yet it still lists the fields. It covers the sole parameter, provides usage context, and differentiates from related tools. For a simple read-only snapshot tool, everything an agent needs to invoke it correctly is present.

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

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

Schema description coverage is 100%: the only parameter `ticker` is fully documented in the schema ('The stock ticker symbol (e.g. AAPL, MSFT).'). The description repeats that `ticker` is required, which adds no new meaning beyond the schema. A baseline score of 3 is appropriate given exhaustive schema docs.

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

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

The description clearly states the tool returns the current price of one stock with specific fields (`price`, `day_change`, `day_change_percent`, `time`). It explicitly distinguishes itself from sibling tools: `get_financial_prices` for historical series and `get_financial_financial_metrics_snapshot` for valuation multiples. The verb 'get' and resource 'financial prices snapshot' are specific, 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 explicit when-to-use guidance: 'Use it whenever the question is "what is it trading at now"'. It also provides direct alternatives for different use cases, naming `get_financial_prices` for date range bars and `get_financial_financial_metrics_snapshot` for valuation multiples. This clearly tells the agent when to choose this tool and when not to.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: the tool is free, requires no key, and can direct users to a category-specific endpoint that lists tools directly rather than through search.

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

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

The description is moderately detailed but every sentence adds useful information: output scope, cost/auth, sibling differentiation, and endpoint usage. It is slightly longer than strictly necessary but remains well-structured and front-loaded with the core purpose.

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

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

For a zero-parameter, read-only tool with an output schema and safety annotations, the description is complete. It covers what the tool returns, the free/no-key access model, and provides the category endpoint for specialized use, leaving no essential gap 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?

The tool has zero parameters, so the baseline is 4. The description includes a <category> placeholder only in the endpoint examples, not as a tool parameter, which is appropriate supplementary guidance rather than a parameter-semantics gap.

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 what the tool does: it presents the AIsa catalogue at a glance, including categories, servers, tool counts, and a dedicated category endpoint. It also distinguishes itself from search by explaining that the endpoint lists tools directly instead of via search.

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 usage context: use list_categories for a catalogue overview, and use the provided endpoint when you only need one category. It explicitly contrasts with search ('instead of via search') and notes tool-router has no equivalent, although it does not exhaustively cover all sibling 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 include destructiveHint=true and readOnlyHint=false, but the description adds value by clarifying it returns only requested fields and is a read-like search despite the destructive hint. It describes the output structure (search_results with one row per ticker and period) and notes it avoids pulling full statements, which is useful behavioral context.

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

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

The description is concise and well-structured, with the key points front-loaded. It explains the purpose, then parameters, then output, then usage guidance, with no redundant filler. Every sentence adds value.

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

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

The output schema and annotations provide some context, but the description fills gaps by explaining the shape of the result and how to handle uncertainty about line item names. It is complete for an agent to decide when to use this tool and what to expect from it.

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

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

The schema has 100% coverage, but the description reinforces key parameter semantics: it explicitly mentions tickers and line_items are required arrays, and the period values (annual, quarterly, ttm) and limit. It also clarifies that item names match statement field names, aiding correct parameter usage beyond schema descriptions.

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

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

The description clearly states it pulls named financial line items across multiple companies in a single call, distinguishing it from sibling tools like get_financial_financials. It specifies the resource (financial line items) and the action (search), and contrasts with single-company 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 provides explicit usage context: it's for building comparison tables across companies and mentions that for a single company you should use get_financial_financials. It also suggests looking up field names in the statement tools if unsure, offering clear guidance on when to use this tool.

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

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

The description presents the tool as a search/filter operation that 'finds' tickers and 'returns results', implying no side effects. However, the annotations declare destructiveHint=true and readOnlyHint=false, creating a direct contradiction. No effort is made in the description to reconcile this or disclose destructive behavior.

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

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

The description is compact and front-loaded: it states the core purpose, mentions the request shape, describes the result shape, and gives workflow guidance in a few sentences. There is only minor redundancy, such as re-emphasizing the ticker choice, but overall it is efficient.

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

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

Given that there is an output schema, 100% schema coverage, and 3 enumerated parameters, the description is sufficiently complete for the main search workflow. It covers the candidate-list use case and output content, so the agent is unlikely to misunderstand how to invoke the tool; the main unresolved issue is the annotation contradiction.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add some value by explaining the filter structure (field/operator/value) and pointing to get_financial_financial_metrics as the source of filterable fields, but it does not deeply extend the schema-provided parameter meaning.

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

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

The description clearly states the tool's purpose: find tickers matching numeric conditions. It also distinguishes it from siblings by noting it is the only tool here that works without knowing a ticker in advance, which is actionable differentiator.

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: to build a candidate list, then pull details on each name with statement or metric tools. It also tells the agent that all other tools require a ticker, so the intended workflow is clear.

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

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

The description discloses meaningful behavior beyond annotations: search spans the entire AIsa catalogue, candidates may belong to modules other than the current one, multiple providers for the same metric are surfaced, and no API key is required. This gives the agent a clear picture of scope and output behavior.

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

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

The description is front-loaded with the core purpose and is dense with useful information: scope, no-auth requirement, response shape, and relationship to the catalogue. Each sentence adds operational value, and the structure makes the tool's behavior predictable.

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 discovery tool with output schema, the description is unusually complete: it explains the response modalities, candidate fields, direct pass-through to `use`, full-catalogue search behavior, and cross-provider visibility. An agent has enough context to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining that the category parameter is not a hard boundary—search spans the full catalogue—and that queries are plain-language task descriptions, which clarifies how to use the tool effectively.

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 finds AIsa data operations across many categories via a plain-language query. It distinguishes itself from siblings like get_details and use by emphasizing that search covers the full catalogue, not just the pinned category.

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 conveys when to use search: when you need to discover operations across the full catalogue, even those not in the current tools/list. It also implicitly contrasts with get_details by noting that returned candidates already include input_schema, so they can be passed directly to `use` without an extra call.

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 readOnly=false, openWorldHint=true, and destructiveHint=true. The description adds valuable behavior beyond that: billing per call, the BatchCallResult response shape, and the error structure with retryable status. It does not spell out side effects, but the destructive flag is already carried by annotations, so the additional context is sufficient.

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

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

Three short sentences, each earning its place: purpose, cost, response shape, and routing guidance. Key behavioral facts are front-loaded, and nothing is redundant with the schema or annotations.

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 and all parameters have descriptions, the tool description is complete enough for correct invocation. It covers cost, return/error contracts, and how routing to this tool differs from calling pinned tools directly, leaving no practical 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 description coverage is 100%, and each parameter is already clearly documented: operation_id as returned by search, search_id provenance, arguments matching input_schema, and max_price_usd as a spend guard. The description does not need to add parameter detail, so baseline 3 is appropriate.

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

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

The description opens with 'Execute one AIsa operation,' a specific verb+resource statement. The word 'one' distinguishes it from the sibling batch_use, and the closing note distinguishes it from calling pinned tools directly. An agent can tell what this tool is for immediately.

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 states when to use the tool: 'this is the way to call anything found through search.' It also gives the alternative: 'Pinned tools in tools/list can also be called directly.' This is clear when-versus-alternative guidance with no ambiguity.

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