CeylonCharts - Colombo Stocks Exchange (CSE) data for AI Agents

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: the tool returns CSV with specific columns, returns JSON candidates for ambiguous input, and provides raw announcement text rather than parsed corporate-action details. This 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?

Three sentences, no filler. The core purpose and distinguishing detail are front-loaded, the alternative tool is named clearly, and the output format is stated compactly. 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 read-only tool with a single required parameter, this is complete: the schema fully documents parameters, annotations cover safety, and the description covers the return format, ambiguous-input behavior, and relationship to the closest sibling tool. No missing information would prevent 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 the baseline is 3. The description adds extra semantic value for the symbol parameter by noting typos are tolerated and that ambiguous input returns candidates requiring the user to pick one, with instructions to call again with the exact symbol.

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

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

The description states a specific verb and resource: 'Get general CSE company disclosures for a symbol' and enumerates concrete examples (board changes, AGM/EGM notices, listings, suspensions, name changes). It also explicitly distinguishes itself from get_corporate_actions, 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 explicit routing guidance: for dividends, rights issues, or share splits, use get_corporate_actions instead, with a reason (structured detail vs raw announcement text). It also explains what to do when the symbol input is ambiguous, covering both normal and edge-case usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: output is a PNG image (not JSON), data is EOD only (doesn't reflect live intraday), and ambiguous symbols return candidate JSON instead of an image. These go beyond the schema and give the agent a realistic expectation of return types and edge cases.

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

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

The description is a single dense paragraph that front-loads the primary purpose and then adds two important caveats (EOD-only and ambiguity handling). Every sentence contributes useful information; it's not overly long relative to the tool's complexity. The structure is logical and straightforward.

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 no output schema, so the description must fill in return type details, which it does (PNG image vs JSON candidates). It covers the key edge case (ambiguous symbol) and the data recency limitation. However, it doesn't explicitly explain how the image is delivered (e.g., file path, base64), which is a minor but potentially relevant gap for an agent. Still, for a chart tool with well-documented params, this is largely complete.

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

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

Schema coverage is 100%, so the schema already documents all four parameters with detailed descriptions. The tool description itself adds little beyond reinforcing the ambiguity handling already present in the symbol parameter. With full coverage, a baseline of 3 is appropriate; no additional parameter semantics are needed.

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 declares a specific action (render a candlestick + volume chart image) with a clear resource (CSE symbol data) and distinguishes it from describing raw OHLC rows, implicitly separating it from get_ohlc_data. It also notes the EOD-only limitation, which further clarifies what the tool is for.

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

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

It explicitly tells the agent to 'hand this to the user directly instead of describing price action from raw OHLC rows,' which provides a clear use case. It also explains the ambiguity handling (returns candidates, ask user to pick). However, it does not name alternatives or give explicit when-not-to-use conditions beyond the raw-data comparison, so it falls just short of 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, and the description adds behavior beyond that: it returns 'announcement details, not just a price-adjustment factor', returns 'CSV, one row per action', and if the symbol is ambiguous, 'returns JSON candidates instead'. This clarifies return format and edge-case behavior without contradicting 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: purpose, sibling distinction, then usage guidance, then return format and edge case. Every sentence contributes new information; there is no filler or 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 read-only list tool with no output schema, the description covers return format (CSV, one row per action), ordering (oldest first), ambiguity handling (JSON candidates), and date-range semantics. Combined with the detailed input schema and annotations, the agent has everything needed to use the tool correctly.

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

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

Schema coverage is 100% (every parameter is described in the schema). The description adds extra practical meaning: e.g., 'pass from=<today> to jump straight to upcoming ones, which is the most common need' and 'matches every one of its share classes, not just one' for symbol, which go slightly beyond the schema text to help the agent choose values correctly.

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: 'Get a calendar of corporate actions (dividends, rights issues, share splits)'. It explicitly names the types of actions and contrasts itself with the sibling get_announcements ('for other company disclosures... use get_announcements instead'), so the agent can immediately tell which tool fits the task.

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 explicit when-to-use vs alternative guidance: 'This is the tool for dividends/rights/splits specifically; for other company disclosures... use get_announcements instead.' It also provides concrete usage patterns: omit all filters to browse everything, pass from=<today> for upcoming actions, optionally scope to a company or kind. This leaves no ambiguity about when or how to invoke 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 and destructiveHint, and the description adds critical behavioral nuance: cash-flow figures are cumulative (year-to-date) while income-statement figures are per-quarter, with an explicit warning against diffing adjacent columns. It also discloses the company_type fallback behavior, entity-level scope, and the CSV/candidates return format—substantially more context than the annotations provide.

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

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

The description is compact and front-loaded: the first sentence states the main purpose, the second delivers a critical usage warning, and the third covers output format and ambiguity handling. Every sentence earns its place with no filler or repetition.

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

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

For a tool with no output schema, the description precisely explains the return format, including the column structure and ambiguity fallback. It also covers quarterly granularity, entity-level scope, and company_type fallback logic, providing an agent with everything needed to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents symbol, statement, and company_type. The description adds some high-level context about statement types and output structure, but it does not add significant parameter-level meaning beyond the schema, so the 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 the exact verb ('Get'), resource (one financial statement), scope (CSE symbol), and granularity ('full line-item detail, one row per line item'). It explicitly names the three statement types, making it distinguishable from sibling data tools.

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

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

The description clearly defines the tool's domain (financial statements) and the type of data returned, giving sufficient context for when to use it. It does not explicitly name alternative tools or exclusions, but no sibling tool overlaps with this function, so clear context without exclusions is acceptable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds substantial behavioral detail: null pct indicates data-quality inconsistency (not a true zero), ambiguous symbols return JSON candidates instead of data, and the instrument suffix is honored over the default. These are non-obvious behaviors that materially affect how the agent interprets results and interacts with the user. 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 every sentence earns its place. The core purpose is front-loaded, followed by the instrument nuance, return format, pagination, range, null handling, and ambiguity behavior. It is about 130 words, which is efficient for the level of operational detail it conveys. No filler or redundant phrasing.

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

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

For a tool with five parameters and no output schema, the description covers everything an agent needs to call it correctly: the return format (CSV or JSON candidates), the meaning of null values, the pagination semantics, the date-range behavior, the instrument suffix override, and the ambiguity resolution workflow. It also accounts for the data-quality caveat. No critical behavior is left unexplained.

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. However, the description adds significant meaning beyond the schema: it explains the semantic of a null pct value, clarifies that the symbol is typo-tolerant and that an explicit suffix overrides the default, and describes how the ambiguity fallback works. It also contextualizes limit/offset as pagination for 'most recent days'. This goes well beyond the schema's bare parameter definitions, fully compensating and then some.

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: 'Get the daily foreign-shareholding percentage series for a CSE symbol'. It clearly defines the resource scope (CSE symbol) and the data type (foreign-shareholding percentage). It also distinguishes itself from generic sibling tools by highlighting the instrument-specific nuance and the ambiguity fallback, making the tool's unique role evident even without naming siblings.

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

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

The description provides rich usage context: it explains the instrument suffix behavior, pagination via offset/limit, date-range scoping, and the ambiguity fallback that instructs the agent to ask the user for an exact symbol. It does not explicitly contrast with alternative tools or state when not to use it, but the context is clear enough for an agent to decide when this tool fits. The lack of explicit exclusions keeps it from a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds substantial behavioral value beyond annotations: the exact CSV column format, the dual-mode return behavior (data vs. JSON candidates), and the index-type-specific field population (headline indices populate OHLC, sub-indices populate sector metrics and leave high/low empty). This is rich, actionable behavioral disclosure.

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

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

The purpose is front-loaded in the first sentence and each subsequent sentence earns its place (return format, then index-type behavior). The CSV column enumeration is verbose but justified since there is no output schema to carry that information. Slightly dense but 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?

With no output schema present, the description correctly shoulders the burden of explaining return values — it covers the CSV format, the candidate-response mode, and the field-population nuance between index types. Minor gaps exist (no date-range limits, no pagination), but for a historical data tool this is reasonably 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 100%, so the schema already documents all three parameters thoroughly, including the ambiguity handling for 'index' and format details for from/to. The description reinforces the ambiguity concept but adds little parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb+resource ('Get historical data for a CSE market/sector index') that clearly distinguishes it from siblings like get_indices (listing indices), get_ohlc_data (likely for individual securities), and screen_indices (screening). The resource and scope are 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 documents the ambiguity flow ('JSON candidates if the input is ambiguous') and the schema explicitly instructs the agent to ask the user to pick a candidate and call again with the exact symbol. This is clear contextual guidance, though it doesn't explicitly route the agent to alternatives (e.g., when to prefer get_ohlc_data over this tool).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the CSV return contract (symbol, name, index_code, index_name, is_main_index) and optional name filtering, which are useful behavioral details beyond the annotations.

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

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

Two sentences with no wasted words. The description front-loads the core action and resource, then efficiently covers optional search behavior and the CSV output contract.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description provides the essential invocation details: the resource scope, search behavior, and CSV columns. The only notable gap is sibling differentiation, which is captured under usage guidelines rather than missing invocation 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?

The input schema already provides full documentation for the query parameter with an example, and schema description coverage is 100%. The description repeats 'Optionally search by name' without adding new meaning, so the baseline of 3 applies.

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

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

The description states a specific verb ('List') and a concrete resource ('CSE market/sector indices') with examples like ASPI and S&P SL20. This makes it clearly distinct from sibling tools like get_index_data or screen_indices, which focus on data retrieval or screening.

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

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

No guidance is given on when to use this tool versus alternatives such as get_index_data or screen_indices. 'Optionally search by name' only clarifies the parameter's behavior, not the tool-selection context.

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

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

The description adds useful behavioral context beyond the annotations: it discloses the return format (CSV with date/value) and the ambiguity fallback (JSON candidates). Since readOnlyHint=true already covers safety, the added details about output and disambiguation are meaningful and do not contradict annotations.

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

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

The description is a single, tight sentence that fronts the main action and immediately mentions the return format and ambiguity handling. There is no wasted wording or unnecessary detail.

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 read-only tool with three params and no output schema, the description adequately explains what the tool returns (CSV or JSON candidates) and the special ambiguity case. It does not elaborate on optional date-range semantics, but these are covered by well-described schema fields, so the overall picture 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 100%, so the baseline is 3. The description adds little beyond the schema, as it repeats the ambiguity behavior already documented in the series_id parameter. It does not introduce new parameter meaning or clarify from/to usage.

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

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

The description clearly states the verb 'get' and the resource 'macroeconomic data for a specific series', making the core purpose understandable. However, it does not differentiate from the sibling tool 'get_macro_series', which likely serves a similar or overlapping purpose, so it does not fully distinguish itself.

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 guidance on when to use this tool versus alternatives such as get_macro_series. The mention of ambiguous input returning candidates hints at a disambiguation workflow, but it does not state conditions for choosing this tool over siblings or prerequisites beyond a series_id.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not responsible for stating safety. It adds value by specifying the return format (CSV with fields id,name,description,frequency,unit,source) and the optional search behavior. This goes beyond the annotations and gives the agent a concrete expectation of the output.

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

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

The description is three short sentences with no filler. The purpose is front-loaded, the search option is stated, and the return format is listed efficiently. Every sentence earns its place, and the structure is ideal 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?

For a low-complexity tool (one optional parameter, no output schema), the description covers the essential points: what it lists, the optional filter, and the exact CSV columns. The only minor gap is not explicitly stating that this returns definitions rather than actual data values, but the word 'definitions' makes that clear. Given the simple nature of the tool, this is adequately complete.

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

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

The schema description covers the single parameter (query) at 100%, explaining its purpose and providing examples. The description repeats the optional-search notion but adds no additional meaning beyond the schema. Since the schema already handles parameter semantics well, 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 states a specific verb ('List') and a clear resource ('macroeconomic series definitions'). It is clear what the tool does. However, it does not explicitly distinguish itself from the sibling tool get_macro_data, which likely retrieves actual data, leaving the differentiation to inference. A name reference would have made it fully 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 provides no explicit guidance on when to use this tool versus alternatives such as get_macro_data or get_indices. It only mentions an optional search by name, which is a usage detail but not a decision rule. The agent is left to infer that this lists definitions rather than data, and there is no mention of when not 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 and destructiveHint=false, so the safety profile is known. The description adds valuable behavior beyond that: mid-period weekly/monthly summaries cover period-to-date (Monday–today example), the isPartialPeriod field explains which case applies, and the JSON-not-CSV note clarifies the response shape. This is exactly the kind of nuance an agent needs to interpret results correctly.

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 zero filler. The first sentence front-loads the purpose and contents, the second clarifies a subtle time-window behavior, and the third preempts a format misconception. 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 read-only aggregation tool with full schema coverage and clear annotations, the description covers the what (contents), when (daily/weekly/monthly), edge cases (mid-period), and response format (JSON). No output schema exists, but the description compensates by naming the key field (isPartialPeriod). Nothing essential is missing.

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

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

Schema description coverage is 100%, and the schema already explains the date reference semantics, limit default/max, and period enum. The description adds no new parameter-level meaning; it is consistent with the schema but does not go beyond it. Baseline 3 applies.

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

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

The description states the verb 'Get' and the resource 'market-wide overview', and enumerates specific contents (top gainers/losers, volume/turnover/crossings, ASI/S&P SL20, sectors). This clearly distinguishes it from sibling tools like get_index_data (single index) or screen_stocks (screening), which an agent could otherwise confuse it with.

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: this is the market-wide snapshot tool, not a per-symbol or per-index tool. However, it does not explicitly say 'use this when X, not when Y' or name alternative tools. The 'not CSV' note addresses format, not usage, so a small gap remains.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavior beyond that: split adjustment by default (but not rights/dividends), 50-day default, paging disclosure, CSV return format preceded by resolution/corporate-action notes, and the JSON-candidates fallback for ambiguous input. This richly discloses behavior without contradicting 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 a single dense paragraph that front-loads the purpose and packs in adjustment defaults, paging, return format, and disambiguation behavior. Nearly every clause earns its place for a tool of this complexity; it is only slightly long, which is justified by the behavioral richness it conveys.

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 no output schema, the description correctly shoulders the burden of explaining the return format (CSV with date,open,high,low,close,volume), the note-preceded behavior, paging, adjustments, and ambiguous-input fallback. The schema covers parameters; the description covers everything else an agent needs to call and interpret the tool correctly. Complete for a tool this complex.

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 schema already documents every parameter thoroughly, including the detailed symbol semantics and the when-to-enable guidance for adjust_dividends. The description adds a little framing ('clean price action', 'total-return series') and confirms defaults, but does not materially add meaning beyond the schema — the schema carries the heavy lifting.

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

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

The description opens with a specific verb+resource: 'Get OHLCV (open, high, low, close, volume) data for a CSE symbol.' It distinguishes itself from siblings like get_index_data, get_macro_data, and get_technicals by scoping to CSE symbols with OHLCV, and clarifies the exchange. The purpose is unambiguous and differentiated.

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

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

The description gives clear operational context: defaults to the most recent 50 trading days, explains how paging back via offset works, and describes the disambiguation flow (returns JSON candidates when ambiguous). It does not explicitly name sibling alternatives or state when NOT to use this tool, which keeps it from a 5, but the usage guidance is concrete 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 and destructiveHint=false, but the description adds substantial behavioral detail beyond that: intraday vs. closing-price fallback, the CSV return format (one row per symbol), and the partial-failure behavior (bad symbols return empty fields rather than failing the whole batch, plus a trailing note listing not-found or ambiguous symbols with candidates). This is exactly the kind of context the description should provide.

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

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

The description is a single well-organized paragraph that front-loads the core purpose, then flows through timing, return format, and error handling. Every clause earns its place—there is no filler. The length is proportionate to the tool's moderately complex behavior (fallback, partial success, trailing note), and the structure makes it easy to scan.

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

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

For a read-only tool with no output schema and only two parameters, the description is nearly complete. It covers the return format (CSV, one row per symbol, with price/change/change%), the trailing note, timeliness, and the follow-up action for ambiguous symbols. Nothing an agent needs to call and interpret the response is missing. The absence of an output schema is compensated by the explicit CSV description.

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 fully documents both `all` and `symbols`, including their mutual exclusivity, format, typo-tolerance, and limit of 50. The description reasserts the 'one or more symbols, or every CSE stock' concept but adds no new parameter-level meaning beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Get a live price snapshot for CSE stocks -- price, change, and change%'. It clearly states the scope (one or more symbols, or all) and differentiates from a single-symbol lookup via an explicit comparison. While it doesn't name sibling tools, the purpose is unambiguous and distinct from the other get_* tools (e.g., announcements, chart, OHLC).

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 temporal usage context: 'During market hours (09:30-14:30 IST)... outside market hours it falls back to the last session's closing price.' It also instructs the agent to 'call again with the exact symbol' when results are ambiguous. However, it does not explicitly name alternative tools for excluded scenarios (e.g., historical data should use get_ohlc_data), so it lacks 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds a useful behavioral detail: it returns CSV with a specific column set, and it indicates filters are optional. It does not contradict the annotations.

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

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

Two short sentences place the core action first and then list the return format. Every sentence adds value, with 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?

For a simple optional-filter list tool with no output schema, the description is complete: it states the resource, the optional filters, and the exact CSV columns. No required parameters or nested objects increase complexity, and annotations cover the safety profile.

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 covers 100% of parameters with clear descriptions, so the baseline is 3. The phrase 'and/or' adds the minor insight that query and sector can be combined, but the description otherwise repeats schema content. No enums or nested objects require additional explanation.

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 action and resource: 'List available CSE symbols with metadata.' This clearly distinguishes it from data-series siblings like get_ohlc_data, get_indices, and get_announcements. The optional search terms add useful filter context without creating ambiguity.

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

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

No when-to-use guidance or exclusions are given. The description only states what the tool does and that filters are optional, leaving an agent to infer when to choose get_symbols over screen_stocks or get_indices. This is effectively no guidance about alternatives.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses several behavioral details: output format (CSV), row ordering (most recent last), default window (50 days), pagination via offset with a note about how to page further back, and the fallback to JSON candidates for ambiguous input. These are substantial and actionable.

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 opens with the purpose, then covers return format, default behavior, pagination, and ambiguity handling in separate clauses. Every sentence adds value, and there is no redundancy or 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 there is no output schema, the description does a thorough job of setting expectations: CSV format, one row per day, most recent last, default limit, pagination mechanism, and ambiguity resolution. This is sufficient for an agent to invoke the tool correctly without further guessing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical context: the default of 50 trading days aligns with the limit default, and it explains how offset enables paging. It also clarifies the ordering (most recent last) which interacts with limit/offset. This goes slightly beyond the schema's parameter descriptions.

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

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

The description states a specific verb ('Get') and a specific resource ('pre-computed daily technicals'), listing concrete components (moving averages, relative-strength rating, 52-week range, volume anomalies). It explicitly covers both CSE stocks and indices, calling itself 'one tool for both,' which distinguishes it from siblings like get_ohlc_data or get_index_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?

It clearly states the tool's coverage (stocks or indices) and that it returns technicals rather than raw data, which implies it is the right choice when those specific metrics are needed. However, it does not explicitly name alternative tools (e.g., get_ohlc_data for raw price data) or state when not to use it, leaving some inference 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?

Even with readOnlyHint=true and destructiveHint=false annotations, the description adds meaningful behavioral disclosure: returns CSV with exact column order, defaults to latest quarter, ignores instrument suffixes, and returns JSON candidates on ambiguous symbols. This goes well beyond the annotations and enriches the agent's mental model.

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 dense sentences carry the full purpose, return format, parameter semantics, default behavior, and ambiguous-symbol handling without redundancy. Front-loaded with the primary purpose and free of 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?

With no output schema, the description fully covers the return format (CSV columns), the parameter combinations, the default behavior, and the ambiguity fallback. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description enhances this by framing all=true as useful for spotting ownership changes and quarter as a historical snapshot, and by reinforcing the entity-level suffix behavior. This is additional practical meaning beyond the schema's already-solid parameter 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 opens with a specific verb ('Get') and resource ('top-20 ranked shareholder list for a CSE company'), which clearly identifies the data being returned. It also states the entity-level nature and references the sibling get_financial_statement, distinguishing this tool from others in the family by the unique shareholder-list resource.

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

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

Gives clear parameter usage context: default latest quarter, all=true for all quarters, quarter for a specific snapshot, and the precedence of quarter over all. It does not explicitly list when-not-to-use scenarios or alternative sibling tools for shareholder data, but the tool's unique purpose makes the usage context clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context: no 52-week-range or volume filtering because those are not tracked for indices, and the output is a CSV with one row per matching index. 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?

Every sentence earns its place: the first defines scope and criteria, the second states exclusions, the third gives use-case and sibling distinction, and the fourth states return format. It is concise, front-loaded, and free of 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 a complex 12-parameter tool with no output schema, the description covers the essential context: what is screened, what filters exist and which do not, how it differs from related index tools, and what the return format is. The schema handles parameter-level details, so nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by framing the filter parameters as the same pre-computed technical criteria used by screen_stocks and explicitly noting what filters are absent. This helps the agent understand the parameter set's collective purpose, even though individual parameters are already well-described 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 names a specific verb ('Screen'), a specific resource ('CSE sector/headline indices'), and the core criteria (moving-average position, relative-strength rating). It also distinguishes itself from get_indices/get_index_data by contrasting screening with single-day performance, so an agent can tell exactly 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?

It explicitly states when to use the tool ('Use this to find which sectors are in a sustained uptrend/downtrend') and explicitly contrasts it with get_indices/get_index_data, which show a single day's performance. The reference to screen_stocks as the shared methodology further clarifies the filtering family.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses key behavioral semantics: every filter is optional and AND-combined, omitting a filter leaves it unconstrained, and the output is a CSV with one row per matching stock. This gives the agent practical expectations without contradicting 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 front-loaded with the core purpose, then states filter semantics, gives three illustrative examples, and closes with the output format. Every sentence earns its place; the examples are dense but directly improve usability.

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 20-parameter, fully optional tool with no output schema, the description covers the essential missing context: filter combination logic, representative queries, and return format. Parameter-level details are already fully documented in the schema, so nothing critical is left unexplained.

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 value above the schema by explaining the AND-combination behavior and giving concrete filter combinations (above_ema50=true & above_ema200=true & rs_rating_min=80, is_52w_high=true, vol_vs_sma50_pct_min=100), which helps the agent compose valid queries.

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: 'Screen CSE stocks by pre-computed technical criteria', naming the exact screening dimensions. It clearly distinguishes this from sibling tools like screen_indices and get_technicals by framing it as a multi-criteria stock screener that returns matching rows.

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

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

The description establishes clear context: it is for screening stocks by optional, AND-combined technical filters, with three concrete examples showing realistic use cases. It does not explicitly name alternatives or state when not to use it, so it falls short of a full 5, but the intended usage is unambiguous.

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