TokenBel Financial Data

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

Annotations already confirm read-only and idempotent behavior. Description adds detail on what fields are returned and what is not covered (payout schedule). 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?

Four sentences efficiently cover purpose, usage, and caveats without redundancy. Front-loaded with the core action.

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 1-parameter tool with output schema, the description covers all necessary context: what it does, how to use it, related tools, and limitations.

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 a description for uuid. The description further clarifies that uuid is an opaque hex string, not an RFC UUID, and how it is typically discovered, adding 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?

Explicitly states 'Get a single BCSE exchange-listed bond by its TokenBel internal identifier (uuid)' and lists returned fields. Distinguishes from siblings like search_by_ticker 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?

Provides explicit guidance: 'Use search_by_ticker first when starting from a ticker' and notes that trading history is available via trading_stats_get and no payout schedule is exposed, directing the agent to 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?

Description adds context beyond annotations by specifying bond type (BCSE exchange-listed), active status, and optional filters. No contradiction with readOnlyHint and idempotentHint.

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 covering purpose, filter details, cross-reference, and pagination with no redundant information. Front-loaded and efficient.

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

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

Given the existence of an output schema, the description adequately covers purpose, filtering, pagination, and cross-references. Slight gap in explaining the return format but acceptable.

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 description adds value by explaining how to use issuer_uuid from search_by_name results and noting cursor-based pagination, which goes beyond schema descriptions.

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

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

The description clearly states 'List active BCSE exchange-listed bonds' with specific verb and resource, and distinguishes from sibling tools like bond_get_by_uuid which retrieves a 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?

Provides explicit cross-reference to search_by_name for obtaining issuer_uuid, and mentions cursor-based pagination. Implicitly clear when to use (to list bonds), but lacks explicit exclusions or 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 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 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 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 provide read-only and idempotent hints. The description adds behavioral clarity by explaining the UUID parameter is not a standard UUID and detailing the output fields, which is beyond the schema.

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

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

The description is three sentences, front-loaded with the core action, and contains no fluff. 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?

For a single-parameter read tool with an output schema, the description fully covers what the agent needs: purpose, input nature, and output contents. No gaps remain.

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

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

The schema covers the UUID parameter with description, but the tool's description adds extra context about the UUID format (8 hex chars, no hyphens) and how to obtain it (via token_list), enhancing 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 tool retrieves a single token by its internal UUID, specifies the data returned (platform, lifecycle, pricing, etc.), and distinguishes it from list/search 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 explains what the tool does but does not explicitly guide when to use it versus alternatives like token_list or search_by_name. The distinction is implied but not stated.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not reiterate safety. The description adds that it supports cursor-based pagination, which is a behavioral trait beyond what annotations provide. However, it does not elaborate on pagination behavior or edge cases.

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

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

The description is two sentences long, front-loading the main purpose and filtering options. Every sentence adds value, and there is no redundant information. It is appropriately sized for the tool's complexity.

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 (which likely describes return fields and pagination), the description does not need to explain return values. It covers the tool's core purpose, filtering capabilities, and pagination support. With 5 optional parameters and clear schema coverage, the description is complete for effective tool selection and 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?

With 100% schema description coverage, the baseline is 3. The description does not add significant meaning beyond the schema, as the schema already thoroughly describes each parameter. The description mentions 'active tokens' but does not clarify which statuses constitute 'active' versus the full list provided in the schema.

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

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

The description clearly states the tool lists active tokens with optional filtering by platform and status. It explicitly notes that tokens do not have tickers, distinguishing it from ticker-based tools, and mentions browsing by platform/status, which differentiates it from sibling tools like bond_list, share_list, and token_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?

The description advises to use this tool for browsing tokenized securities by platform/status, implying it is for listing and filtering. While it does not explicitly state when not to use it or list alternatives, the context of sibling tools (e.g., token_get_by_uuid for single token) provides implicit guidance. A slight gap exists in specifying 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 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.