TokenBel Financial Data

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

Annotations declare readOnlyHint and idempotentHint, indicating the tool is safe and repeatable. The description adds value by specifying the bond attributes returned, the limitation to BCSE exchange-listed bonds, and clarifying the uuid format. No contradictions.

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 concise sentences: the first clearly states the core function, the second lists return fields, the third provides cross-tool usage guidance. Every sentence adds value; no fluff.

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

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

With a single parameter and an output schema, the description covers the essential aspects: what the tool does, what it returns, and how it relates to other tools. It mentions the uuid format and what is not exposed. Could potentially note error behavior, but for a read-only lookup tool this is sufficient.

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

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

Schema coverage is 100% and already explains uuid as an opaque hexadecimal string. The description reinforces this format and adds usage context ('discovered via search_by_ticker'), but does not provide significant new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a single bond by internal UUID, enumerates the returned fields, and distinguishes it from sibling tools like search_by_ticker (for ticker-based lookup) and trading_stats_get (for trading history). It is specific and leaves no ambiguity about the resource and action.

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

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

Explicit guidance is provided: 'Use search_by_ticker first when starting from a ticker.' It also references trading_stats_get for trading history and notes the absence of payout schedule information, helping the agent decide when and when not to use this tool.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds behavioral details: lists only active bonds, BCSE exchange, today-trading flag meaning, and cursor pagination. No contradictions.

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: first explains purpose and filters, second adds pagination and cross-tool guidance. No fluff, front-loaded key 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?

Given output schema exists and annotations are complete, the description covers purpose, filtering, pagination, and dependency. No gaps identified.

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

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

Schema coverage is 100%, so baseline 3. Description adds value for issuer_uuid (source from search_by_name) and clarifies is_trading meaning. Other parameters are well-described in schema already.

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 specific verb 'list', resource 'active BCSE exchange-listed bonds', and mentions optional filters (issuer_uuid, is_trading). Clearly distinguishes from siblings like bond_get_by_uuid or other list 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?

Provides guidance on using issuer_uuid from search_by_name results and mentions pagination. Does not explicitly contrast with alternatives like bond_get_by_uuid, but the context is clear.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds that it resolves the company, which is useful context but does not contradict annotations. No additional behavioral details beyond what annotations and schema 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 concise sentences, front-loaded with the verb 'List'. Every word is meaningful with no redundancy. Achieves high information density in minimal space.

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

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

Given the presence of an output schema and comprehensive parameter descriptions, the description sufficiently explains the tool's core functionality. It covers the input (company/issuer id) and output (bonds), though could mention pagination behavior briefly.

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

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

Schema description coverage is 100%, so parameters are well-documented. The description slightly clarifies the uuid parameter by mentioning it can be a company or issuer id, but this is already implied in the schema description. Baseline 3 is appropriate.

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

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

The description clearly states it lists summary cards of a company's active bonds, distinguishing it from sibling tools like bond_get_by_uuid (single bond) and bond_list (likely all bonds). The verb 'List' and resource 'company's active bonds' are specific.

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 on when to use vs alternatives. While it mentions accepting a company or issuer id, it doesn't explain when to prefer this over bond_list or other tools. Lacks explicit when-not-to-use or alternative tool references.

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

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

Annotations already declare this tool as read-only and idempotent, so the description doesn't need to repeat that. It adds behavioral context: issuer ids are resolved to their linked company, and it returns periodic metrics. It does not disclose error cases, but with annotations covering safety, this is sufficient.

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

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

The description is three sentences, each with a clear purpose: what the tool does, what it returns, and how to get the input id. It is front-loaded with the core purpose and contains no redundant information.

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

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

Given the presence of an output schema and annotations, the description is sufficiently complete. It covers the primary use case, input requirements, and output type. It could mention pagination or the default limit_periods, but the schema already defines defaults and constraints.

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 adds value for the 'uuid' parameter by clarifying it can be a company or issuer id and that issuer ids are resolved, and it recommends using search_by_name. For 'limit_periods', no additional meaning is added, but overall the description enhances understanding.

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

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

The description clearly states the verb 'Get', the resource 'financial parameters', the method (by TokenBel uuid), and the output (financial statement metrics and ratios). It also uniquely identifies itself among sibling tools by focusing on financial parameters rather than company details or bonds.

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

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

The description explicitly tells when to use the tool (with a company or issuer id) and suggests finding the id via search_by_name first. It does not provide explicit alternatives or when-not-to-use cases, but the sibling context and the tool's specific purpose make it 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 indicate readOnlyHint=true and idempotentHint=true, so the description's lack of additional behavioral warning is acceptable. The description adds value by listing the returned fields (name, full_name, UNP, etc.) and clarifying the uuid format, which annotations do not cover.

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

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

The description is two sentences but front-loads the main purpose. The second sentence is moderately long but provides necessary context. It is efficient without being overly terse.

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

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

With an output schema present and annotations covering safety, the description provides all essential information: what it does, how to use the uuid parameter, return fields, and relationship to sibling tools. No gaps.

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

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

Despite 100% schema description coverage, the description adds significant meaning: it explains that uuid is an opaque hexadecimal string (typically 8 characters, not an RFC UUID) and that it comes from search_by_name with entity_type='company'. This goes beyond the schema's minimal property description.

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

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

Description clearly states the tool retrieves a single company catalogue row by its TokenBel internal identifier (uuid). It specifies the verb ('get') and resource ('company catalogue row'). It distinguishes from sibling tools like search_by_name and other get-by-uuid 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?

Explicitly notes that companies are not always the same as securities issuers and directs users to use search_by_name to discover both. It also explains that the uuid comes from search_by_name, providing clear guidance on when to use this tool versus alternatives.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds that pagination is cursor-based, which informs the agent about stateful iteration. It also disclaims what the tool does not do, adding clarity beyond annotations.

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

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

Two sentences cover purpose, exclusion, alternatives, and pagination. Every sentence adds value; no wasted words. The description is front-loaded and easy to scan.

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

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

Given the tool has 4 optional parameters and an output schema, the description covers the core purpose, filtering, pagination, and what the tool does not do. It provides enough context for an agent to select and invoke this tool correctly, including alternatives for related queries.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context: 'optional filtering by industry' ties the industry parameter to a use case, and 'supports cursor-based pagination' explains how cursor_uuid and cursor_created_at are used together, adding meaning beyond individual schema descriptions.

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

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

The description clearly states the tool lists active company catalogue rows with optional industry filtering. It also explicitly distinguishes itself from siblings by noting it does not list security_issuer rows, which is a key differentiator.

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

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

The description provides explicit guidance: use this tool to list companies, and for issuers use search_by_name then share_list/bond_list. It also mentions cursor-based pagination, helping the agent understand how to iterate results.

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 idempotentHint. Description adds that it resolves the company id and returns summary cards, but does not detail pagination behavior beyond what schema implies. Adequate given annotation coverage.

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 concise sentences with no waste. Front-loaded verb and resource.

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?

Describes core purpose and input. Pagination is implied by cursor parameters but not explicitly mentioned. Output schema handles return structure. Slightly lacking but adequate for a read-only list tool.

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

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

Schema coverage is 100%, so parameters are documented. Description restates that uuid can be company or issuer id, which matches schema. Does not add significant new meaning beyond 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?

Verb 'list' and resource 'summary cards of active shares' are specific. Distinguishes from sibling share_list which lists all shares, and from company_tokens_list/company_bonds_list by resource type.

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?

Description clearly states input type (company or issuer id) and that it resolves to the company's shares. Does not explicitly mention sibling share_list as an alternative for unfiltered listing, but context is clear.

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

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

Annotations show read-only and idempotent. Description adds 'resolves the company', consistent with annotations. No contradictions.

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

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

Two sentences, front-loaded with purpose, no waste. Efficient and clear.

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 output schema present, description covers input and behavior (paginated, summary cards). Adequate for a list tool.

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

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

Schema coverage 100%, so baseline 3. Description adds nuance that uuid can be company or issuer ID, slightly improving understanding.

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

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

Clearly states action (list), resource (company's active tokens), and scope (active). Distinguishes from siblings like token_list (all tokens) and company_shares_list (shares).

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?

Indicates use for listing tokens of a specific company via company or issuer ID. Implicitly different from token_list but lacks explicit when-not-to-use or alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that rates are BYN per 1 unit, only usd/eur/rub are supported, BYN is implicit base, and open-ended or today-bounded ranges bypass cache. These behavioral details go beyond annotations and provide useful operational context.

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

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

The description is two concise sentences with no redundant words. It front-loads the core purpose and then lists modes and constraints efficiently. Every word earns its place.

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

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

Given the presence of an output schema (not shown but known), rich annotations, and clear parameter constraints, the description is complete. It covers all usage modes, supported currencies, cache behavior, and base currency. No additional information is needed for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying mutual exclusivity of date vs date_from/date_to, that group_by requires a range, and that open-ended ranges bypass cache. It also reinforces currency filtering and base currency. This extra context aids parameter selection.

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

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

The description clearly states it retrieves NBRB official FX rates against BYN for USD, EUR, and RUB. It specifies the exchange rate format and distinguishes from sibling tools (none of which are FX rate tools). The verb 'get' combined with resource 'NBRB official FX rates' is specific and 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 explains four modes (latest, single_date, range, grouped weekly/monthly) and which parameters activate them. It implicitly guides when to use each, but does not explicitly state when not to use or compare to alternatives. However, the context is clear enough for agent decision-making.

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 confirm readOnlyHint and idempotentHint, and the description adds value by detailing that it resolves entities and returns enriched events with aggregated links/tags. No contradictions.

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: purpose, resolution/return, and filtering/pagination. Front-loaded and efficient with no redundant information.

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

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

Given an output schema exists, the description covers all essential aspects: input, entity graph scope, filters, pagination. It is complete for an 8-parameter tool with good annotations.

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 3 applies. The description adds overall context (entity graph resolution) but doesn't significantly enhance individual parameter semantics beyond what the schema already provides.

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

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

The description clearly states it lists full published news events across an entity graph (company, its security_issuers, bonds, shares, emissions). It distinguishes from siblings like bond_list or share_list by focusing on news events and entity resolution.

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 when to use this tool (to get news for a company/issuer) and mentions filtering capabilities, but doesn't explicitly state when not to use it or list alternative tools. The context is clear enough for correct selection.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to cover safety. The description adds value by explaining the opaque ID format (8 hex chars, not RFC UUIDs), entity type tags, and the relationship between companies and issuers, which are beyond the annotations.

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

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

The description is concise, consisting of two information-dense sentences. Every sentence adds value: the first covers purpose and entity types, the second covers ID format and entity relationships. No wasted text.

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

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

Given the tool's complexity (searching two entity types, mapping to different subsequent tools), the description covers all necessary context: how to interpret results, ID format, relationships, and linked_company_uuid. With an output schema present, return values need not be detailed.

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 adds extra context: query can be a name or UNP, case-insensitive, with an example. It reinforces the schema but doesn't add new parameter details beyond that.

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 specifies the verb 'search' and the resources 'companies AND securities issuers', distinguishing it from sibling tools like search_by_ticker. It also explains the output tags and entity type differentiation.

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

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

The description provides explicit guidance on how to use results: for 'company' results use company_get_by_uuid, for 'issuer' results use uuid as issuer_uuid in share_list/bond_list. It also notes the difference between companies and issuers and the linked_company_uuid. Lacks explicit when-not-to-use compared to siblings, but still strong.

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

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

Annotations (readOnlyHint, idempotentHint) are already present; description adds meaningful context: case-insensitive substring match, uuid format (opaque 8 hex char id), and return fields including is_trading.

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, every sentence earns its place with no unnecessary words.

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

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

For a simple search tool with output schema, the description fully explains input parameters, output fields, token exclusion, and how to use the results with other tools.

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%; description repeats parameter descriptions but adds an example ('MTB' matches 'MTBank') and context about token exclusion, which is already implied. Minimal added value beyond 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?

Description clearly states it searches BCSE exchange-listed shares and bonds by ticker with case-insensitive substring matching, and explicitly excludes tokens, distinguishing it from sibling tools.

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

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

Provides explicit guidance on when to use (ticker search), what not to use (tokens excluded), and how to use the returned uuid with specific other tools like share_get_by_uuid and bond_get_by_uuid.

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 idempotentHint (safe, idempotent). Description adds behavioral context like 'traded today, not historical liquidity' and identifier format, exceeding annotation coverage.

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 concise sentences, each adding distinct value: action, output details, and usage guidance. No redundancy.

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

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

For a simple one-param tool with full schema coverage, output schema, and annotations, the description fully covers usage and behavior.

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?

Single parameter with 100% schema description coverage providing format details. Description restates schema info but adds no new semantic meaning beyond 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?

Clearly states 'Get a single BCSE exchange-listed share by its TokenBel internal identifier', specifies resources and output fields, and is distinguishable from siblings like bond_get_by_uuid.

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

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

Provides explicit guidance to 'Use search_by_ticker first when starting from a ticker', indicating when to use an alternative tool. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds behavioral details about cursor-based pagination and filtering, which go 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: first states purpose and key filters, second gives cross-reference, third mentions pagination. No redundant information.

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

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

Given annotations and full schema coverage, the description is largely complete. It could explicitly state it returns a list of share objects, but output schema likely covers that.

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%, but the description adds cross-tool guidance for issuer_uuid (from search_by_name) and clarifies pagination parameters (cursor_uuid). This provides context beyond the schema.

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

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

The description clearly states the verb 'List', the resource 'active BCSE exchange-listed shares', and optional filtering by issuer_uuid and today-trading flag. It distinguishes from siblings like company_shares_list (which lists shares per company) by specifying exchange-level listing.

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

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

The description implies usage for listing exchange-listed shares with filters and gives specific guidance on obtaining the issuer_uuid from search_by_name. However, it does not explicitly mention when not to use this tool or directly name alternative tools.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable context: summary money totals use declared events only, and dividend_yield_pct is a nominal-based proxy, not market-price yield. No contradictions.

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

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

The description is longer than necessary but well-structured: it starts with the main purpose, then usage hints, then parameter and output details. Every sentence provides useful information, though some details (like status meanings) could be slightly condensed.

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

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

Given the presence of an output schema, the description covers key aspects: the identifier, event types, status meanings, and important caveats about the summary and dividend_yield_pct. It also provides a usage workflow. No missing information for this tool's context.

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

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

Schema coverage is 100% and the schema description already explains the uuid parameter in detail. The description reinforces that it is the TokenBel internal identifier and how to obtain it, adding value beyond the schema.

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

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

The description clearly states it gets dividend/payout history and an aggregate summary for a single share by its unique internal identifier (uuid). It distinguishes from other tools like search_by_ticker by specifying the workflow.

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

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

The description provides explicit guidance: first use search_by_ticker to find the share, then call this tool with the returned uuid. It also explains event period_type and status meanings, helping the agent understand when to use each piece of data. However, it does not explicitly list alternative tools or exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it is safe and idempotent. The description adds behavioral context by listing return fields (platform, lifecycle status, pricing, coupon rate, company info), which is valuable beyond annotations.

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

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

Two sentences, front-loaded with the action 'Get a single token', and each sentence adds critical information without redundancy. Efficient and well-structured.

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

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

Given the presence of an output schema (not shown but indicated true), the description does not need to detail return format. It covers what the tool does, how to identify the token, and the kind of data returned. Complete for a single-token retrieval tool.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds significant meaning: it explains that uuid is a TokenBel internal identifier, opaque hexadecimal, not an RFC UUID, typically 8 characters, and discovered via token_list. This clarifies usage beyond the schema description.

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

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

The description clearly states it retrieves a single token by its internal identifier (uuid). It distinguishes from sibling tools like bond_get_by_uuid and share_get_by_uuid by specifying 'TokenBel-native tokenized corporate securities' and contrasting with BCSE-listed tickers.

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

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

The description implies usage when you have a token UUID, and mentions that tokens are typically discovered via token_list. However, it does not explicitly state when not to use this tool or list alternatives, though the sibling context helps.

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 idempotentHint, indicating safe, non-destructive behavior. The description adds cursor-based pagination, a key behavioral detail. No contradictions. For a read tool, this is sufficient transparency beyond annotations.

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

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

Two dense sentences: first states core function and constraints, second adds pagination. No filler, front-loaded, every word earns its place. Excellent structure.

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 5 parameters with full schema coverage, output schema present, and annotations, the description covers the essential context: what the tool does, key filters, and pagination support. It doesn't explain return data, but the output schema suffices. 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?

Schema description coverage is 100%, with detailed descriptions for all 5 parameters. The description adds no new parameter semantics beyond summarizing filter capabilities. Baseline of 3 is appropriate as schema carries the load.

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

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

The description clearly states the tool lists active tokens with optional filtering by platform and status. It explicitly distinguishes from ticker-based search by noting tokens lack tickers, and positions this as the browsing tool. Differentiates well from sibling list tools like bond_list, share_list, and individual get tools.

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

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

The description gives clear usage context: use this to browse tokenized securities by platform/status when you don't have a ticker. However, it does not explicitly state when to avoid this tool or mention sibling search tools (e.g., search_by_ticker) as alternatives. Implicit guidance but not comprehensive exclusions.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, and the description reinforces that it is a read-only operation returning statistics. It adds behavioral context by listing the returned fields and distinguishing primary from secondary market data. No contradictions 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 three sentences, each serving a clear purpose: stating the core function, listing return content, and providing usage instructions. No extraneous words; all information is essential and front-loaded. Highly concise and well-structured.

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

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

Given the tool's simplicity (3 parameters, all well-documented, output schema exists), the description covers all necessary context: prerequisites (token_list), parameter usage, data scope, and limitations (no secondary market). It is fully complete for an agent to understand and invoke the 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 baseline is 3. The description adds significant value beyond the schema by explaining date defaults (omission = last 30 days, date_from defaults to date_to minus 30 days, date_to defaults to today) and clarifying that uuid is an opaque hexadecimal string (not an RFC UUID). This extra context justifies a score of 4.

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

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

The description clearly states the tool's purpose: 'Get primary-market sales statistics for a token by its TokenBel internal identifier.' It distinguishes itself from siblings by specifying 'primary-market' and explicitly excluding secondary-market data. The description provides specific details about the returned data (per-day series, range totals, token snapshot), making the purpose unambiguous.

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

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

The description gives explicit usage guidance: find the token id via token_list first, explains how to use date parameters (omit both for last 30 days, provide date_from and/or date_to), and clarifies the data scope (primary-market only, no secondary). This helps the agent select the correct tool and use it correctly.

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

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

The description adds significant behavioral details beyond the annotations (readOnlyHint, idempotentHint): it explains that latest_30d reads a materialized view, range mode aggregates live data, which fields are null in each mode, and the structure of daily_series. No contradictions 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 well-structured and front-loaded with the primary purpose. It is somewhat lengthy but each sentence provides necessary detail. A slight reduction could improve conciseness without losing 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?

Given the tool's complexity (two modes, multiple fields, daily_series), the description covers all key aspects: mode behavior, field availability, uuid clarification, and cache behavior. With an output schema present, the description is complete and sufficient for an agent 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%, so baseline is 3. The description adds extra meaning: uuid is opaque hex not RFC UUID, dates must be both present or both absent, and ranges ending today bypass cache. This adds value beyond the schema.

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

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

The description clearly states the tool gets trading statistics for a BCSE exchange-listed share or bond by a specific identifier (uuid). It distinguishes two modes (latest_30d and range) and explicitly directs users to use search_by_ticker first, making the purpose very clear and distinguishable from sibling tools like token_trading_stats_get.

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

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

The description provides clear guidance on when to use each mode: omit both dates for latest_30d, provide both for range, and that one bound is rejected. It also tells users to use search_by_ticker first. However, it does not explicitly compare against sibling tools, which would enhance guidance.

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