TokenBel Financial Data

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

Annotations already show readOnlyHint and idempotentHint. Description adds context: returns specific fields, and states no separate bond payout schedule is exposed. Does not contradict annotations.

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

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

Three sentences, no redundancy. Front-loaded with core action, then details, then usage guidance. Every sentence adds value.

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

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

Given annotations, output schema, and sibling tools, the description is complete: explains what the tool does, what it returns, and its limitations (no payout schedule).

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 description provides additional clarification for the uuid parameter: 'opaque hexadecimal string, usually 8 characters', not an RFC UUID.

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?

Clear description: 'Get a single BCSE exchange-listed bond by its TokenBel internal identifier'. Lists returned fields and distinguishes from sibling tools like trading_stats_get and search_by_ticker.

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 recommends using search_by_ticker first when starting from a ticker, and notes trading history is available via trading_stats_get, guiding appropriate tool 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 as true. The description adds pagination and filtering context, but does not expand significantly beyond the annotations. No contradiction.

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

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

Two sentences that are front-loaded with the core action and efficiently cover all key points without redundancy.

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

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

Given the 5 parameters, no required fields, and presence of output schema, the description covers the essential functionality, pagination, and parameter source. A minor gap is the lack of clarity on what 'active' means, but overall 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 has 100% description coverage, so baseline is 3. The description adds value by explaining how to use issuer_uuid with search_by_name and clarifying filtering options, exceeding the baseline.

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 defines the tool's purpose: listing active BCSE exchange-listed bonds with optional filters. It specifies the verb 'list', the resource 'bonds', and the scope, distinguishing it from sibling tools like company_bonds_list or share_list.

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 guidance on obtaining issuer_uuid from search_by_name results and mentions cursor-based pagination, but does not explicitly state when to use this tool over alternatives or exclude cases where other tools are more appropriate.

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

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

Annotations declare readOnlyHint and idempotentHint, which the description does not contradict. The description adds 'resolves the company' but provides no additional behavioral context beyond the annotations.

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

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

The description is two concise sentences with no wasted words, front-loading the core purpose. Every sentence adds value.

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

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

Given the tool has an output schema and the description covers input requirements, it is sufficiently complete. The mention of 'summary cards' gives a hint of output, but no major gaps exist.

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%, with detailed parameter descriptions in the schema. The description adds no extra meaning beyond 'accepts a company OR issuer id', so it meets the baseline without improvement.

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 summary cards of a company's active bonds and accepts a company or issuer ID. It distinctly differentiates from sibling tools like bond_list (which lists all bonds) and bond_get_by_uuid (single bond).

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 company or issuer ID but does not explicitly state when to avoid this tool or provide alternatives. No exclusion criteria are given, leaving room for ambiguity.

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 as true. The description reinforces this by describing a read operation ('Get') with no side effects. It adds behavioral context: issuer ids are resolved to linked companies, and the output includes both statement metrics and ratios. However, it does not explain what a 'period' is (e.g., quarterly, annual), which could be useful. Overall, the description adds value 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?

The description is two sentences: the first defines purpose and outputs, the second adds usage guidance. Every sentence is essential and informative. There is no redundancy or fluff. It is efficiently front-loaded with 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 the presence of an output schema (context signal: true), the description does not need to detail return values. It covers the parameter usage (including issuer resolution) and prerequisite step. The only minor gap is the lack of definition for 'period' (e.g., quarterly, annual), but this is likely covered by the output schema. Overall, the description is comprehensive for the tool's complexity.

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

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

Schema description coverage is 100% with detailed parameter descriptions (e.g., uuid as opaque hex, limit_periods with default). The tool description adds extra context for uuid, explaining it can be a company or issuer id and that issuer ids are resolved. This goes beyond the schema. For limit_periods, the description adds nothing new, but the baseline of 3 is elevated due to the additional clarity for uuid.

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 action ('get'), the resource ('financial parameters for a company or securities issuer'), and the identifier method (TokenBel internal uuid). It explicitly lists what is returned (periodic financial statement metrics and calculated ratios). The tool distinguishes from siblings by emphasizing the uuid-based lookup and resolution of issuer ids to linked companies, setting it apart from company_get_by_uuid and search_by_name.

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: 'Accepts a company id or an issuer id — issuer ids are resolved to their linked company. Find the id via search_by_name first.' This tells the agent to use search_by_name as a prerequisite. It implies the tool is for financial parameters, not general company info, but does not explicitly list exclusions (e.g., 'do not use if you need company details'). 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 indicate readOnlyHint=true and idempotentHint=true, so the description does not need to add safety warnings. It adds minor context about the data being a catalogue row and the uuid nuance, but does not disclose additional behavioral traits beyond what annotations provide.

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

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

The description is two sentences: the first states the core action and returned fields, the second adds critical context (companies vs. issuers) and an alternative tool. It is front-loaded, concise, and contains 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?

Given the tool's simplicity (one required parameter, no nested objects, output schema exists), the description adequately covers purpose, parameter usage, and differentiation from siblings. It lists return fields and clarifies identifier semantics. The only minor gap is lack of mention about authentication or rate limits, but these are common and not required for completeness here.

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%, meaning the parameter is fully documented in the schema. The tool-level description adds some redundancy (e.g., 'by its TokenBel internal identifier (field name: uuid)') but does not provide substantial new meaning beyond the schema's detailed explanation of the uuid format and origin.

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 company catalogue row by its TokenBel internal identifier (uuid). It lists the returned fields and explicitly distinguishes this tool from search_by_name for discovering both companies and issuers, thereby differentiating it from a relevant sibling.

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 when you have a uuid, and use search_by_name to find companies and issuers. It also clarifies that companies are not always the same as issuers, helping agents avoid misapplication.

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 the tool supports cursor-based pagination, which is a behavioral trait. No contradictions or missing critical behavioral info like auth or rate limits; for a read-only tool 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?

Two sentences with no wasted words. First sentence gives purpose and filtering capability. Second sentence clarifies scope and directs to alternatives. Well-structured and front-loaded.

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

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

Given the tool's low complexity, 100% schema coverage, existence of output schema, and annotations covering safety, the description is complete. It explains pagination and filtering sufficiently. Leaves no ambiguity about the tool's behavior or when to use it.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description reiterates 'optional filtering by industry' and 'cursor-based pagination', adding minimal new semantic value beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists active company catalogue rows with optional filtering by industry. It distinguishes itself from listing security_issuer rows directly, referencing sibling tools like search_by_name, share_list, and bond_list.

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

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

Explicitly says when not to use this tool (to list security_issuer rows) and directs to alternatives: search_by_name for issuers, then share_list/bond_list with issuer_uuid. Also mentions supported features like cursor-based pagination.

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 job is lighter. It adds that the tool resolves the company from either a company or issuer id, but does not detail pagination behavior beyond cursor parameters.

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

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

Two sentences with no wasted words. The description is concise and front-loaded with the core purpose.

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

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

Given the presence of an output schema, the description sufficiently covers what the tool does and input flexibility. It could mention the 'summary card' concept more, but overall 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%, and the description does not add any parameter meaning beyond what the schema provides. Baseline is 3.

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

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

The description clearly states the tool lists summary cards of a company's active shares, specifying it accepts a company or issuer TokenBel id and resolves the company. This verb+resource+scope is distinct from sibling tools like share_list, which is more general.

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 needing shares for a specific company or issuer, but does not explicitly state when not to use or provide alternatives among siblings. However, the context is clear enough for an agent to infer.

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, covering safety and idempotency. Description adds no additional behavioral traits beyond 'list summary cards', which is consistent but doesn't enhance transparency.

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

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

Two efficient sentences: first states purpose, second clarifies input flexibility. No wasted words; front-loaded with essential information.

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

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

Coverage is good given that an output schema exists (not shown) and parameters are fully documented. The description covers the unique company/issuer resolution. However, it could briefly mention pagination or what 'active tokens' means, but not critical.

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. Description adds value by clarifying that the uuid parameter can be either a company or issuer id and that the tool resolves it, which is not in the schema. For other parameters, no additional meaning is added.

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 action (list), resource (summary cards of active tokens), and the unique behavior of accepting company or issuer id and resolving to company. It distinguishes from sibling tools like token_list by specifying company-specific scope.

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

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

Description implies use when needing tokens for a specific company, but lacks explicit when-not-to-use or alternative tool guidance. Mentions resolution of company/issuer id, which provides some context but not full usage guidelines.

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 readOnly and idempotent. The description adds behavioral details: rates are BYN per 1 unit, only usd/eur/rub supported, and open-ended ranges bypass cache. This adds value 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?

The description is concise and well-structured, using short sentences and clear separation of modes. It front-loads the main purpose and avoids redundancy.

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

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

Given the existence of an output schema, the description does not need to detail return values. It covers all modes, parameter constraints, and special behaviors, leaving no gaps for an agent to misuse 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 coverage is 100%, so baseline is 3. The description adds meaning: date formats, mutual exclusivity, currency enum explanation, group_by requires range, and caching behavior for date_to open-ended ranges. These enhance understanding beyond the schema.

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

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

The description clearly states it gets NBRB official FX rates against BYN for USD, EUR, and RUB, specifying the source, base currency, and supported currencies. It is distinct from sibling tools which focus on bonds, companies, shares, tokens, etc.

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 different modes (latest, single date, range, grouped aggregates) and when to use which parameters. It does not explicitly state when NOT to use this tool, but the sibling tools are clearly different, so the guidance is adequate.

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 behavioral context such as entity graph resolution, enriched news with aggregated links and tags, and filtering/pagination support, which goes beyond the annotations without contradicting them.

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

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

The description is concise with four sentences, well-structured: main function, input, output features, filtering/pagination. Every sentence adds value, and the key information is front-loaded.

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

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

Given the complexity, the presence of an output schema, and annotations, the description covers purpose, scope, input, filtering, and pagination. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not provide additional parameter meaning beyond what the schema already specifies, such as the uuid being an internal identifier or the filter values.

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

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

The description clearly states the tool lists full published news events across an entity graph, specifies the scope (company, issuers, bonds/shares, emissions), and indicates it accepts a company or issuer TokenBel id. This provides a specific verb and resource, 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?

The description explains when to use this tool (for news events) and mentions the input type. It does not explicitly state when not to use or suggest alternatives, but the purpose is clear enough to differentiate from siblings like company_bonds_list or share_list.

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

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

Annotations already declare readOnly and idempotent. Description adds value: ID format (8 hex chars, not RFC UUIDs), linked_company_uuid, and that companies/issuers are separate tables. 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?

Single concise paragraph, front-loaded with core purpose, no wasted words. All information is relevant 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?

Covers search scope, result handling, ID nature, entity relationships, and linking. Given complexity and presence of output schema, description is fully adequate.

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

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

Schema coverage is 100%, but description enriches query parameter with case-insensitivity and example, and explains UNP usage. Adds practical context 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?

The description clearly states it searches companies and issuers by name/UNP, distinguishes between entity types, and specifies how to use results with other tools. It differentiates from sibling tools like search_by_ticker.

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 using results: for companies use company_get_by_uuid, for issuers use uuid in share_list/bond_list. Explains overlap and linking. Lacks explicit when-not-to-use but sufficient for distinguishing.

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, and the description adds valuable context: uuid format (opaque TokenBel internal id, 8 hex chars, not RFC UUID), returned fields (entity_type, ticker, etc.), and 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 plus a concise list of returned fields; every sentence adds value, no fluff, front-loaded with purpose.

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

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

Given the tool's simplicity, clear annotations, and presence of output schema in description, the description fully covers purpose, exclusions, usage of results, and sibling differentiation.

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

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

Schema coverage is 100%, so baseline 3. The description adds context about uuid meaning and downstream tool usage, which indirectly enriches understanding of the query parameter's purpose.

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

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

The description clearly states the tool searches BCSE exchange-listed shares and bonds by ticker (case-insensitive substring match) and explicitly excludes tokens, making its purpose highly specific and distinct from siblings.

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

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

The description tells when to use (search by ticker for shares/bonds), when not to use (tokens excluded), and what to do with the returned uuid (use with other tools like share_get_by_uuid, etc.), providing clear guidance and differentiation from 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 readOnly and idempotent, so the bar is lower. The description adds clarifying details about returned fields, notably that is_trading refers to trading today, not historical liquidity, which goes 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 concise sentences with no wasted words. The main purpose is front-loaded, and the usage guidance follows succinctly.

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 simple input (1 param), good annotations, and listed return fields, the description fully covers necessary context: what the tool does, how to find the identifier, and what outputs to expect.

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%, baseline 3. The description adds significant context: uuid is an opaque hex string (usually 8 chars, no hyphens) and is typically discovered via search_by_ticker, which is not in 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 the tool retrieves a single BCSE exchange-listed share using a specific internal identifier (uuid). It distinguishes from siblings like share_list and search_by_ticker by specifying the identifier type and return fields.

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 advises to use search_by_ticker first when starting from a ticker, providing a clear alternative and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe reads. The description adds behavioral details about pagination (cursor-based, cursor_uuid and cursor_created_at), filter parameters, and the opaque hexadecimal format for identifiers. This enriches the agent's understanding 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?

The description is two sentences, front-loaded with the core purpose, and covers filters and pagination without unnecessary words. Every sentence earns its place.

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

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

With an output schema present, the description does not need to explain return values. It fully covers filtering, pagination, parameter usage, and includes a cross-reference to search_by_name. The tool is well-documented for an agent to use correctly.

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

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

The input schema has 100% coverage with descriptions for all 5 parameters. The description adds value by explaining the format of uuid fields (opaque hexadecimal, not RFC UUID) and how to source issuer_uuid from search_by_name. It also mentions the default limit of 50. This goes beyond the schema's basic 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 BCSE exchange-listed shares with optional filtering by issuer_uuid and is_trading flag. It specifies the resource (shares), action (list), and scope (active, BCSE exchange-listed). This distinguishes it from sibling list tools for bonds, companies, tokens, etc.

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 guidance on using issuer_uuid from search_by_name results with entity_type='issuer', and mentions cursor-based pagination. However, it does not explicitly state when not to use this tool or when to use alternatives like share_get_by_uuid or other list tools. The context is clear but excludes explicit when-not conditions.

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

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

Annotations already declare readOnlyHint and idempotentHint true. The description adds substantial context: clarifies how summary money totals are calculated (declared events only), explains that dividend_yield_pct is a nominal-based proxy not market-price yield, and details event status meanings.

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 detailed but every sentence serves a purpose. It front-loads the main action and identifier, then provides necessary clarifications. Could be slightly more concise, but not wasteful.

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

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

Given the output schema exists (not shown but signaled), the description doesn't need to cover return values. It fully explains usage, prerequisites, parameter, and tricky behavioral aspects. 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?

Schema coverage is 100% for the single parameter 'uuid'. The description adds significant meaning beyond the schema by clarifying that the uuid is an opaque hexadecimal string, not an RFC UUID, and typically 8 characters without hyphens. This prevents confusion from the field name.

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 starts with a clear verb 'Get' and specific resource 'dividend/payout history and an aggregate summary for a single share'. It immediately mentions the identifier 'uuid' and distinguishes from the sibling tool 'search_by_ticker' which is used to discover the 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?

Explicitly instructs to first use 'search_by_ticker' to find a share, then call this tool with the returned uuid. Also explains the meaning of period_type and event statuses, guiding correct usage.

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

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

Annotations already indicate readOnly and idempotent behavior. The description adds value by specifying the return content (platform, lifecycle status, pricing, coupon rate, company info), which is not in 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 key information, no redundant text. Every sentence adds value.

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

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

The description explains the domain, identifier, and return fields. With an output schema available (context signal), it sufficiently covers the tool's behavior without being overly verbose.

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 description does not need to add much. It reiterates that uuid is the identifier but provides minimal additional insight beyond the schema's detailed description of the uuid format.

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 action (Get), the resource (single token), and the identifier (TokenBel internal uuid). It distinguishes from sibling tools like token_list and bond_get_by_uuid by specifying TokenBel-native tokens.

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 that tokens are TokenBel-native and not BCSE-listed, providing context for when to use. However, it does not explicitly contrast with sibling retrieval tools like bond_get_by_uuid or share_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 read-only and idempotent hints. The description adds pagination behavior and cursor usage, complementing the annotations without contradiction.

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

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

Two concise sentences front-load purpose and filters, with no wasted words.

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

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

With complete schema descriptions, read-only annotations, and an output schema, the description covers all needed context: purpose, filtering, pagination, and usage guidance.

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% with detailed parameter descriptions. The description provides a high-level summary but adds limited new meaning 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 lists active tokens with filtering by platform and status, distinguishes from ticker-based tools like search_by_ticker, and provides specific verb+resource.

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

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

It explains when to use this tool (browsing tokens without tickers) and implies alternatives like search_by_ticker, but does not explicitly list 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 declare readOnlyHint and idempotentHint true, which the description supports by describing a read-only operation. The description adds behavioral context beyond annotations: primary-market scope, date range defaults, and the fact that the UUID is not an RFC UUID. 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 two sentences plus a single clarifying note about secondary-market. It is front-loaded with the core purpose, efficiently covers usage, parameters, and limitations without redundancy. Every sentence adds essential information.

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

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

Given the presence of an output schema, the description summarizes return values sufficiently (per-day series, range totals, token snapshot). It covers prerequisites, date range behavior, and data scope. Could optionally include error handling, but is complete for a read-only 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% with descriptions for all three parameters. The description adds value by clarifying the UUID's nature (opaque hex, not RFC UUID) and date behavior (defaults, inclusive). This goes beyond the schema, warranting a 4 (baseline 3 for complete 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 tool name and description clearly state it retrieves primary-market sales statistics for a token using its internal UUID. It specifies the verb 'Get', the resource type, and distinguishes from sibling tools by explicitly stating 'Secondary-market data is not included' and referencing token_list for discovery.

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 instructions on date range usage: omit both for last 30 days or provide date_from/date_to. It also directs users to find the UUID via token_list first. While it doesn't explicitly list when not to use, the exclusion of secondary-market data implies 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 idempotent and read-only. Description adds valuable behavior: cache bypass for ranges ending today, null fields in range mode, daily_series structure. No contradiction with annotations.

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

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

Single paragraph front-loads purpose and then details modes. Efficient but could be broken into clearer subsections. No wasted words.

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

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

Given output schema exists, description covers input behavior, modes, return fields, and caching. Agent has sufficient information 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 coverage is 100%, but description adds context: uuid is not RFC UUID, 8-character hex, discovered via search_by_ticker; date parameters mode rules. Enhances understanding beyond schema alone.

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 gets trading statistics for a BCSE exchange-listed share or bond by uuid, distinct from sibling tools that get entity details. Specific verb 'Get' and resource 'trading statistics' with required prerequisite step (use search_by_ticker).

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 instructs to use search_by_ticker first. Describes two modes (latest_30d vs range) with conditions on date parameters, including that one bound is rejected. Does not explicitly state when not to use, but context from siblings implies alternatives.

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