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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely new behavioral facts: the CSV column shape (date,type,description,pdf_url) and the fallback to JSON candidate lists on ambiguous input. It does not mention pagination or result caps, but that is a minor gap.

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

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

Three sentences, front-loaded with purpose, then the exclusion/alternative, then the return shape. Every clause carries routing or format information; no filler.

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

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

No output schema exists, and the description compensates by naming the return format and its columns plus the ambiguity fallback. Combined with fully documented parameters and safety annotations, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and the schema already documents symbol typo tolerance, the candidate fallback, and the from/to defaulting rules. The description's mention of 'for a symbol' and the ambiguity behavior largely restates the schema, so the baseline 3 is correct.

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

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

States a specific verb+resource ('Get general CSE company disclosures for a symbol') and enumerates the covered disclosure types (board changes, AGM/EGM notices, listings, suspensions, name changes). It also names the sibling it is not (get_corporate_actions), so an agent can discriminate without opening either schema.

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

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

Explicitly routes dividends, rights issues, and share splits to get_corporate_actions and gives the reason (parsed structured detail vs raw text). It also tells the agent what to do when the symbol is ambiguous: surface candidates, ask the user, re-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 cover read-only/idempotent/non-destructive, and the description adds genuinely new behavior: EOD-only data, no live intraday, and the dual return mode where an ambiguous symbol yields JSON candidates instead of an image. That is exactly the kind of non-obvious behavior an agent needs 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?

Three tight sentences with zero filler, front-loading the core action and the hand-to-user instruction before the caveats. Every clause carries information the agent needs.

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 still tells the agent what comes back — a PNG image normally, or JSON candidates on ambiguity. Combined with the data-freshness caveat, nothing needed to call and interpret the result 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 each of bars, theme, interval, and symbol is already documented in the schema. The description only reinforces what the schema says (most recent `bars` periods, daily/weekly/monthly intervals) without adding syntax or default details beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource — render a candlestick + volume chart image (PNG) for a CSE symbol — and immediately distinguishes itself from the raw-data sibling get_ohlc_data by saying to hand the image to the user rather than describe price action from OHLC rows. An agent can route to it without opening the schema.

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

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

Explicitly says to use this instead of describing raw OHLC rows, and states the constraint that it is EOD-only and does not reflect today's live intraday movement — a clear when-not condition. It also documents the fallback path for ambiguous symbols (ask the user to pick from candidates and call again).

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description goes further by disclosing return format (CSV, one row per action), default ordering (oldest first), and the ambiguity fallback (JSON candidate list instead of data). The JSON-candidates behavior is a non-obvious failure mode an agent must handle, and it is stated clearly.

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

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

Front-loaded with purpose and routing before defaults and return format; each sentence carries distinct information (boundary, default behavior, scoping, output shape). No filler or restatement of the tool name.

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

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

With no output schema, the description compensates by explaining the CSV row format and the JSON-candidates edge case. Combined with complete schema descriptions for all six optional parameters, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: that symbol matches every share class rather than one, and that an omitted symbol yields a market-wide calendar. It doesn't explain the limit/offset paging interaction beyond what the schema already says, keeping it just short of a 5.

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

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

States a specific verb and resource ('Get a calendar of corporate actions') and enumerates the covered kinds (dividends, rights issues, share splits). It explicitly draws the boundary against the sibling get_announcements, so an agent can distinguish the two without opening either schema.

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

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

Names the alternative tool (get_announcements) and the exact condition that selects it (board changes, AGM/EGM notices, trading suspensions). It also gives positive guidance on the most common call pattern (omit filters to browse all, or from=<today> for upcoming).

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?

Adds substantial context beyond the readOnly/idempotent annotations: the cumulative year-to-date nature of cash-flow figures, the CSV return format with its column structure, and the candidate-list behavior on ambiguous input. These are non-obvious behavioral traits an agent would otherwise get wrong.

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?

Dense but front-loaded: the core purpose leads, followed by the critical interpretation caveat and the return-format note. Every sentence carries information, though the middle YTD warning is slightly clause-heavy.

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 compensates by describing the CSV column layout and the JSON candidate alternative. Combined with the fallback explanation and the statement-type semantics, an agent has everything needed to call and interpret this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by tying the 'cashflow' enum value to its cumulative interpretation and explaining the ambiguous-symbol candidate flow. It reinforces and clarifies parameter meaning rather than merely repeating 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?

States a specific verb and resource ('Get full line-item detail for one financial statement'), names the three statement types, and scopes it to a CSE symbol with one row per line item. This clearly separates it from siblings like get_quotes, get_ohlc_data, or get_market_summary.

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

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

The description implies when to use it — one statement for one symbol, all available quarters — and gives actionable guidance on interpreting cash-flow vs income-statement figures and on the ambiguity fallback. It does not explicitly name alternative tools, so it falls 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description goes further by disclosing the CSV return format, pagination behavior, the meaning of a null pct (a known data-quality issue, not a true zero), and the fallback to JSON candidates for ambiguous symbols. It does not cover auth needs or rate limits, but the added behavioral context is substantial.

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, front-loaded with the core purpose, and every sentence contributes distinct information: instrument specificity, CSV/pagination mechanics, null-data caveat, and ambiguous-symbol fallback. There is no redundant restatement of the name or schema fields.

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 no output schema, the description must explain return values; it does so adequately by stating the result is CSV with a pct series and describes pagination and ambiguous-symbol fallback. It does not enumerate all CSV columns, but the core data semantics are clear enough for an agent to interpret the output.

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 explaining the instrument-suffix behavior (voting vs non-voting shares) and the null pct semantics, which are not fully captured in the schema. It also reinforces the from/to, limit, and offset usage in a cohesive narrative.

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 the daily foreign-shareholding percentage series for a CSE symbol,' and clarifies the scope (how much of the free float is held by foreign investors, tracked day by day). It does not explicitly name or contrast with any sibling tool, but the resource is unique enough that an agent can distinguish it from get_top20_shareholders or get_quotes without opening other schemas.

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

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

The description gives practical guidance on how to use the tool (when to pass an instrument suffix, how to page with offset, how to scope with from/to), but it never states when to use this tool versus alternatives like get_top20_shareholders or get_quotes. Usage is implied by the purpose rather than explicitly contrasted with 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 readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the exact return shape (CSV column list), the JSON-candidate fallback for ambiguous input, and the critical behavioral difference that headline indices (ASPI, S&P SL20) populate OHLC while industry sub-indices populate turnover/volume/trades and leave high/low empty.

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, with the core purpose front-loaded before the return-format and index-type caveats. The CSV column enumeration is long but earns its place since no output schema exists; nothing is redundant.

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 is responsible for describing returns and it does so thoroughly, including the column set, the JSON candidate edge case, and the headline-vs-sub-index field divergence. An agent has everything needed to call it and interpret the result.

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 documents 'from', 'to', and 'index' including format and ambiguity behavior. The description adds no parameter syntax or format detail 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?

States a specific verb and resource: 'Get historical data for a CSE market/sector index.' The word 'historical' distinguishes it from sibling tools like get_indices (current listings) and screen_indices, so an agent can route to it without opening schemas.

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

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

The description explains the ambiguity-recovery flow (ask the user to pick a candidate and call again), which is genuine usage guidance. However, it never states when to prefer this over get_indices, screen_indices, or get_ohlc_data, so the alternative-selection guidance is only implied.

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, destructiveHint=false and openWorldHint=false, so the safe-read profile is covered. The description adds genuinely new context by disclosing the return shape (CSV with symbol,name,index_code,index_name,is_main_index), which is valuable since no 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?

Two tight sentences, zero padding, with the resource definition front-loaded ahead of the optional filter and the return format. Every clause carries information an agent can act on.

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 parameterless list tool with one optional filter, annotations covering safety and an inline statement of the returned columns, nothing further is needed for correct invocation. Absence of an output schema is fully compensated by the CSV column disclosure.

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

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

Schema description coverage is 100% and the single optional parameter is fully documented, so the baseline is 3. The description's 'optionally search by name' restates what the schema already says without adding format or matching semantics.

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

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

States a specific verb (List) and resource (CSE market/sector indices), and names concrete instances (ASPI, S&P SL20, industry sub-indices) so an agent knows exactly what is covered. It does not explicitly distinguish itself from the closest sibling get_index_data, which is the only gap keeping this below a 5.

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 says the query parameter is optional and used to search by name, which is implicit usage guidance for the one parameter. It never states when to use this list tool versus get_index_data or screen_indices, so the agent must infer the boundary between them.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes beyond them by disclosing the return format (CSV date,value) and the candidate-list fallback on ambiguous input. This is meaningful behavioral context the annotations do not provide.

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

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

Two tight sentences that lead with the core action and immediately cover the two possible response shapes. No filler, nothing redundant.

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 usefully explains both possible return shapes (CSV data vs. JSON candidates), which is enough for correct invocation. It stops short of describing pagination or how large the returned CSV might be.

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 series_id, from, and to thoroughly, including typo tolerance and the date format. The description adds nothing beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb (Get) and resource (macroeconomic data) scoped to 'a specific series', which clearly separates it from sibling listing-style tools. However, it never names or contrasts with get_macro_series, the closest sibling, leaving the boundary between 'data' and 'series' to inference.

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 ambiguity flow ('ask the user to pick one and call again') gives implied operational guidance, but there is no explicit statement of when to use this tool versus get_macro_series, get_index_data, or other data endpoints. Usage is inferable but 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context by disclosing the return format (CSV with id,name,description,frequency,unit,source), which the annotations do not provide.

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

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

Two compact sentences with zero waste: action first, optional filter second, return shape last. Every clause 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 low-complexity, single-optional-param list tool with no output schema, the description covers action, filtering, and the return columns. It could be marginally stronger by routing to the data-fetch sibling, but 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%, so the single 'query' parameter is already fully documented with examples in the schema. The description's 'search by name' merely restates it without adding syntax or matching behavior, so the baseline 3 applies.

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

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

States a specific verb and resource ('List available macroeconomic series definitions'), and the word 'definitions' distinguishes it from the sibling get_macro_data, which presumably returns observations. It does not name that sibling explicitly, so differentiation is implicit rather than stated.

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?

'Optionally search by name' implies the filtering use case, but there is no explicit guidance on when to choose this over get_macro_data or other siblings. Usage is only weakly implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds value beyond them by disclosing the return format (JSON, deliberately not CSV, and why) and by surfacing the isPartialPeriod response field that governs interpretation of weekly/monthly results. It does not mention rate limits or auth, keeping it short of a 5.

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

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

Front-loaded with the resource and its contents, then the two disambiguating facts (partial-period semantics, JSON-not-CSV). Slightly redundant: the partial-period rule is repeated almost verbatim in the period parameter description, costing a little density but not clarity.

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 carries the return-value burden and does so: it names the response shape (a bundle of small lists), the format (JSON), and the key interpretive field (isPartialPeriod). Combined with full schema coverage and annotations, an agent has everything needed to call and interpret this correctly.

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

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

Schema description coverage is 100%, so the schema already documents date, limit, and period semantics, including the mid-period behavior for weekly/monthly. The description restates the period/partial-period interaction rather than adding syntax, bounds, or format details the schema lacks; 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?

States a specific verb ('Get') and resource ('market summary') and enumerates exactly what the bundle contains: top gainers/losers, volume/turnover/crossings, ASI and S&P SL20 performance, and sector performance. This clearly separates it from siblings like get_index_data (single index) and screen_stocks (filtering), so an agent can route without opening schemas.

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

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

Gives clear context for the tricky case — a weekly/monthly summary requested mid-period covers the in-progress period, not the prior complete one — which is exactly the ambiguity an agent would otherwise guess wrong on. It stops short of naming alternatives (e.g. when to prefer get_index_data or screen_stocks instead), so it is clear context without explicit exclusions.

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

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

Goes well beyond the annotations: default adjustment policy (splits on, rights/dividends off), the 50-day default and offset paging, CSV shape, note prefixes for name resolution / other instruments / corporate actions, and the JSON-candidates behavior on ambiguous input. That is exactly the extra context annotations cannot carry.

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

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

Front-loads purpose and defaults, then layers edge cases; nearly every clause carries information (adjustment policy, paging, ambiguous-input path). It is dense and somewhat clause-heavy, but not padded.

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 carries the return-format burden and does so fully: CSV columns, the leading note variants, and the JSON-candidates substitute response. 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema states only piecemeal: the default split-only adjustment posture and the interaction that offset + limit page backward through history. It stops short of adding format details 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?

States a specific verb and resource ('Get OHLCV data for a CSE symbol') and immediately scopes it with adjustment semantics and the default window. An agent can separate this from get_quotes (snapshot) and get_chart (visual) without opening any schema.

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

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

Gives real conditional guidance: adjust_dividends for total-return questions, offset for paging further back, and the ambiguity fallback ('ask the user to pick one'). It never names a sibling tool as the alternative for a competing task, so it stops 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?

Despite annotations already covering read/safe/idempotent, the description adds substantial behavioral context: market-hours intraday tick vs out-of-hours closing-price fallback, and the batch-tolerance behavior (a bad symbol yields empty price fields rather than failing the call). It even documents the trailing not-found/ambiguous note and the retry path — genuinely useful beyond the structured fields.

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

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

Front-loaded with the core purpose, then market-hours nuance, then return format, then edge-case handling. It is dense but every sentence carries distinct information; the batch-error sentence is long but justified by the non-obvious behavior it discloses.

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 carries the return burden and does so: CSV format, one row per symbol, and the trailing note listing unresolved/ambiguous symbols. Combined with timing and error semantics, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both `all` and `symbols` are already fully documented including mutual exclusion and typo-tolerance. The description restates the one-vs-all usage but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a live price snapshot for CSE stocks') and names the exact fields returned (price, change, change%). It clearly reads as a current snapshot tool, distinguishing it from historical siblings like get_ohlc_data or get_chart.

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?

Explains the two usage modes ('one or more symbols, or every CSE stock at once') and gives the retry instruction for unresolved symbols. It stops short of explicitly naming sibling alternatives (e.g. get_ohlc_data for historical), so it is clear context without full exclusion 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds little beyond that profile — it implies a full enumeration when no filters are given but does not state whether results are paginated or capped.

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

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

Three short sentences, front-loaded with the core purpose, then the optional filters, then the return shape. 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?

With no output schema, the description usefully enumerates the CSV columns (symbol,name,sector,industry,is_active,last_updated), which is the key missing structured information. Minor gaps remain around result size or completeness guarantees, but the definition is sufficient to invoke 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% and both parameters are documented there with examples and substring-match behavior, so the schema carries the load. The description only adds that both filters are optional, which is the baseline expectation.

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

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

States a specific verb ('List') and resource ('available CSE symbols with metadata'), plus the return format. It is clearly the symbol-universe tool and not confusable with quote/chart siblings, though it never explicitly differentiates itself from the closer-sounding screen_stocks or screen_indices.

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?

'Optionally search by company name and/or sector' implies the filtering use case, which is adequate context. There is no explicit when-to-use/when-not guidance and no mention of alternative tools (e.g., screen_stocks) for broader screening.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on non-obvious behavior: CSV output shape ('one row per trading day, most recent last'), the 50-day default, self-disclosure when more history exists, and JSON candidate fallback on ambiguity. That is exactly the extra context annotations cannot convey.

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

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

The single dense paragraph is front-loaded with the core purpose and output format, then tacks on defaults and ambiguity handling. Nearly every clause carries information, though the symbol-vs-index and ambiguity points could be separated for faster scanning.

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 steps in to describe the return format, row ordering, default window, and the JSON-candidates alternative response, plus how to page. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds end-to-end meaning: it ties limit/offset to chronological vs most-recent-first ordering and explains what happens when symbol resolution is ambiguous (candidates returned, re-call with exact symbol). This goes beyond the per-parameter text.

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

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

The description gives a specific verb and resource ('Get pre-computed daily technicals') and enumerates the payload (moving averages, relative-strength rating, 52-week range, volume anomalies). It also states the dual coverage (CSE stock OR sector/headline index), which separates it from raw-data siblings like get_ohlc_data and index-only siblings like 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 frames when the tool applies ('for a CSE stock OR a sector/headline index ... one tool for both') and explains paging ('how to page further back with offset') and the ambiguous-input fallback. It stops short of naming an explicit alternative for raw price history, so the routing guidance is strong but not exhaustive.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: exact return shape ('CSV (quarter,rank,name,shares,pct)'), that instrument suffixes are ignored, that `quarter` overrides `all`, and the non-obvious fallback of returning JSON candidates on ambiguity. These are traits an agent cannot infer from annotations or 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?

Front-loaded with the core purpose and return shape before mode details, with no filler sentences. It is somewhat dense across several clauses, but every clause carries operational information.

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

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

With no output schema, the description steps in to specify the exact return columns and the JSON-candidates fallback, and it covers default scope, override precedence, and symbol matching. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema itself already documents the `all` semantics, the `quarter` precedence over `all`, and the ambiguity behavior. The description largely restates those rules rather than adding format or syntax beyond them, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the top-20 ranked shareholder list for a CSE company'), plus filing cadence and entity-level scoping. It explicitly cross-references get_financial_statement for the same entity-level semantics, letting an agent distinguish it from siblings without opening schemas.

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

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

Gives clear default behavior (latest quarter only) and the conditions that select each alternative mode ('all=true to see every quarter', 'quarter to see one specific historical snapshot'). It also flags the ambiguous-symbol path. It stops short of naming sibling tools that are alternatives for adjacent questions (e.g., get_foreign_holdings), so no explicit when-not-to-use.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral context beyond them: which criteria the screener evaluates, which screen_stocks filters are absent for indices, and the return shape ('Returns CSV, one row per matching index').

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, tightly front-loaded: purpose/scope first, exclusions and alternatives second, return format last. No filler or restated name/title, and each sentence carries distinct information.

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

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

For a 12-parameter, all-optional screener with no output schema, the description covers scope, criteria, exclusions, sibling routing, and return format, and the schema carries the parameter detail. It slightly under-delivers on how the boolean MA filters combine with the RS/change ranges, but 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%, so the schema already documents all 12 parameters with formats, ranges, and examples; the baseline is 3. The description adds only a high-level mapping of the filter family (moving-average position, RS rating) and flags which filter dimensions do not exist, but no per-parameter syntax or interaction detail.

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

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

Opens with a specific verb+resource ('Screen CSE sector/headline indices'), names the concrete index families (ASPI, S&P SL20, industry sub-indices) and states the criteria used. It explicitly distinguishes itself from screen_stocks (same criteria) and from get_indices/get_index_data (single-day performance).

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?

States the use case directly ('find which sectors are in a sustained uptrend/downtrend') and names the alternative tools for the other use case (single-day performance via get_indices/get_index_data). It also gives an explicit exclusion: no 52-week-range or volume filter here.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds the return contract ('Returns CSV, one row per matching stock') and the optional-AND-filter semantics, which the annotations do not convey. It omits any note on rate limits, result caps, or screening-date behavior, keeping it from a 5.

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, front-loaded with purpose, then combinatorics, then compact worked examples, then the return format. No filler and every sentence carries distinct information.

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

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

For a 20-parameter screening tool with no output schema, the description covers purpose, filter semantics, examples, and the CSV return shape, while the schema fully documents each parameter and its defaults. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds value beyond the schema: it explains filter-combination semantics (optional, AND-combined) and gives concrete examples with expected interpretations (above_ema50 & above_ema200 & rs_rating_min=80 = market-leading uptrends; vol_vs_sma50_pct_min=100 = 2x average volume).

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

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

States a specific verb+resource+domain ('Screen CSE stocks by pre-computed technical criteria') and enumerates the criterion families (MA position, RS rating, 52-week range, unusual volume). This clearly distinguishes it from siblings like get_technicals (single-symbol) and screen_indices (indices rather than stocks).

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 explains the combinatorics ('every filter is optional and AND-combined; omit a filter to not constrain on it') and gives three worked filter combinations showing intended usage. It does not name a sibling alternative or state when NOT to use this tool (e.g., versus get_technicals for a single symbol), so it stops 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.