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

With no annotations, the description carries the burden of behavioral disclosure. It discloses the return format ('JSON array of account info objects, one per FlexStatement') and input source, which is useful. However, it does not explicitly state that the operation is read-only/non-destructive, nor does it address error handling or edge cases like malformed XML. For a parse tool, this is acceptable but not comprehensive.

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 highly concise, with only a purpose statement, an Args section, and a Returns section. Every sentence provides necessary information with no redundancy. The structure is clean and front-loaded, making it easy to scan.

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

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

For a simple tool with one parameter and an output schema, the description is largely complete. It explains the input source and the shape of the output ('JSON array of account info objects, one per FlexStatement'). It lacks explicit usage guidance relative to siblings, but given the tool's simplicity and existing output schema, this is not a major gap.

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 description adds meaningful context for the sole parameter xml_content by describing it as a 'Raw Flex XML string' and specifying it comes from flex_run_query or flex_get_statement. This goes beyond the schema's minimal title 'Xml Content' and helps the agent understand the expected format and provenance.

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

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

The description clearly states the tool's purpose: 'Extract account metadata from a Flex XML report.' The verb 'extract' and the specific resource (account metadata) make it clear. It does not explicitly compare to sibling parse tools, but the focus on account-level metadata distinguishes it from tools like flex_parse_trades or flex_parse_positions.

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 by mentioning that xml_content comes from flex_run_query or flex_get_statement, giving context on the input source. However, it does not explicitly state when to choose this tool over siblings, nor does it provide exclusions or alternative tools. Usage guidance is only inferred from the tool's purpose.

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?

With no annotations, the description carries the burden and does well: it discloses data sources (most recent equity-summary row, current open-positions snapshot), explains the worst-case reservation formula, and lists all return fields. It stops short of discussing edge cases (e.g., no short puts, negative cash) but otherwise is transparent.

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 lengthy but every section earns its place: formula, purpose, data sources, and a clear bulleted list of return fields. The formatting improves scannability and avoids redundant prose.

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

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

Given the tool's complexity (multi-step calculation, multiple outputs), the description is nearly complete—it covers inputs loosely, the formula, data sources, and all return fields. It falls short only in not addressing error conditions or input format details, and there is no usage guidance vs siblings. Still, it provides enough for an agent to invoke correctly assuming the XML input is understood from context.

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

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

The only parameter 'xml_content' has 0% schema description coverage, and the tool description does not explain what XML content should be provided or its expected format. Given the low schema coverage, the description was required to compensate, and it fails to do so beyond the parameter name itself.

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 uses a specific verb ('Calculate') and names the exact resource (free cash as percentage of Net Liq after short-put reservations). It clearly distinguishes itself from sibling analysis tools (pnl, dividends, portfolio history) by focusing on cash utilization and short-put obligations.

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

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

The description provides clear context by stating the question it answers ('Of my total Net Liq, how much of my cash is actually free...'). However, it does not explicitly mention when not to use it or reference alternative tools, so it lacks 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?

With no annotations provided, the description carries full behavioral disclosure burden. It outlines the output structure (JSON with totals and breakdown), but does not disclose side effects (likely none since it's an analysis), error handling, or limitations. The output description adds some transparency 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 exceptionally concise, with a clear one-line purpose, an annotated Args section, and a brief summary of return values. Every sentence earns its place with no filler or redundancy.

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

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

The tool is simple (one parameter) and the description covers purpose, parameter meaning, and output structure. It does not mention error handling or prerequisites beyond raw Flex XML, but for an analysis tool of this scope, it is adequately complete.

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

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

The schema description coverage is 0%, so the description must compensate. It explains 'xml_content' as 'Raw Flex XML string', providing meaning beyond the type 'string' in the schema. This is sufficient for a single parameter, though it lacks details like format or size constraints.

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

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

The description clearly states the tool's function with a specific verb ('Summarize') and resource ('dividend income and withholding taxes from cash transactions'). It effectively distinguishes itself from sibling parsing tools like flex_parse_cash_txns by focusing on dividend analysis.

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 context through 'from cash transactions' but does not explicitly state when to use this tool over alternatives or provide exclusions. No mention is made of sibling tools or use cases where this analysis is 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by stating the closing-trade filter, the date/asset filters, the group-by options, and the return format (JSON totals plus a breakdown sorted by realized_pnl descending). It stops short of discussing error handling or malformed input, but the core behavioral traits are transparent.

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

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

The description is well-structured: a single purpose sentence, an important note about closing trades, then a clear Args list, and a Returns line. Every sentence adds value without redundancy. It is appropriately sized for a tool with five parameters.

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 that an output schema exists (though not shown in the prompt), the description need not explain return values in depth, but it still summarizes the return shape. It covers all parameters, the behavioral rule about closing trades, and the available grouping/filter dimensions, making it 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 0%, but the description fully compensates by documenting every parameter with names, types, defaults, examples, and format requirements (e.g., 'YYYY-MM-DD', 'STK, OPT, FUT', allowed group_by values). This is exactly the kind of semantic enrichment the rubric rewards.

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 uses a specific verb and resource: 'Aggregate realized P&L from trade records in a Flex XML report.' It also clarifies a key filtering rule ('Only closing trades... contribute'), which clearly distinguishes this tool from sibling analysis tools focusing on dividends, cash utilization, or portfolio history.

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

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

The description gives clear context for when to use the tool: for realized P&L aggregation from trade records, with only closing trades contributing. It does not explicitly mention alternatives or exclusions, but the intended use case is sufficiently clear given the sibling tool names and the stated filter behavior.

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?

Without annotations, the description carries the full burden of behavioral disclosure. It explains the computation logic (daily chain-linking, Modified Dietz), what the result includes (time-series, annualised and period returns, total net external cash flow), and the effect of cash flows on each method. It does not explicitly state that the operation is read-only, but the 'analyze' verb and the nature of the tool make that a safe inference. Overall, it provides strong behavioral context 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?

The description is well-structured with clear sections: a one-sentence purpose, a 'Return methods' section, and an 'Args' section. Every sentence earns its place, providing necessary detail without fluff. The markdown formatting (headings, bullets) improves scannability. It is appropriately sized for the complexity of the tool.

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 covers all essential aspects: purpose, return methods, parameters, and return value. Since an output schema exists, the exact JSON structure need not be spelled out, but the description summarizes the output contents. Given the moderate complexity (3 parameters, no nested objects), this is complete enough for an agent to select and correctly invoke the tool.

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

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

The schema provides no descriptions (0% coverage), so the description must explain each parameter. It does so thoroughly: xml_content is described as 'Raw Flex XML string'; metric lists valid values ('total', 'cash', 'stock', 'options', 'futures', 'bonds') and its default; return_method is explained with each option and its default. This fully compensates for the bare schema and adds meaningful semantic context.

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

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

The description opens with a specific, action-oriented statement: 'Show how the portfolio NAV changed over time and compute a return figure.' This clearly identifies the resource (portfolio NAV history) and the action (analyze/return), making it easy to distinguish from sibling analysis tools like flex_analyze_pnl or flex_analyze_dividends. The additional method details (TWR vs MWR) further reinforce a unique purpose.

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

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

The description provides clear guidance on when to use each return method: 'Use this to evaluate the *strategy* independent of cash-flow decisions' for TWR and 'Use this to evaluate overall portfolio performance' for MWR. This helps the agent choose the correct option. However, it does not explicitly compare against sibling tools (e.g., 'use flex_analyze_pnl when...'), leaving tool selection somewhat implied rather than explicit.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It discloses polling behavior, timeout limits, and the return format. It also notes that token overrides an environment variable. It doesn't cover error handling or rate limits, but the key behaviors are clearly stated.

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 efficient and well-organized: a one-line purpose, a one-line explanation of polling, a structured Args list, and a Returns line. Every sentence earns its place 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 polling complexity and four parameters, the description covers what the tool does, how it behaves, what parameters mean, and what it returns. The presence of an output schema is not strictly needed since the Returns line explicitly shows the JSON shape.

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 description adds significant meaning to all four parameters: it explains that reference_code comes from flex_send_request, token overrides an env var, and provides defaults for polling/timeout. This goes well beyond the bare schema, which has no 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 starts with a specific verb and resource: 'Download a completed Flex report using its reference code.' This clearly distinguishes it from siblings like flex_send_request (which creates a request) and flex_parse_* (which parse data). The purpose is unambiguous.

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

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

The description implies the workflow by stating the reference code comes from flex_send_request, making it clear this tool is used after a request is submitted. It doesn't explicitly name alternatives or exclusions, but the context is strong enough for correct selection among siblings.

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

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

No annotations are present, so the description carries the transparency burden. It discloses input parameters, return structure, and case-insensitive filtering, but does not mention edge cases, error behavior, or confirm it is read-only. For a parsing tool, this is moderate 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?

The description is well-structured: a one-sentence summary, common values list, parameter list, and return format. Each section earns its place with no filler, making it easy to scan.

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

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

Given the tool's complexity (5 parameters, no annotations, no detailed output schema shown), the description covers the essential aspects: purpose, all parameters, and return JSON structure. It lacks explicit usage guidance relative to siblings and error handling, but is largely complete for selecting and invoking 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 0%, and the description fully compensates by explaining each parameter in detail, including filter semantics, date format (YYYY-MM-DD), and case-insensitive substring matching for transaction_type. It also provides common transaction_type values, adding significant 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 uses a specific verb 'extract' with a clear resource ('cash transaction records from a Flex XML report'), which immediately distinguishes it from sibling tools that parse trades, positions, etc. The mention of common transaction types further clarifies 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?

Provides clear context for when to use the tool (extracting cash transactions from Flex XML) and describes filtering options. Does not explicitly mention alternatives or exclusions, but the context is sufficiently clear for 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?

Since no annotations are provided, the description carries the full burden. It sufficiently discloses input expectations (raw Flex XML string), optional date filtering, and output format (JSON with count and equity_summary). It implies a read-only parsing behavior, which is appropriate for this tool, though it does not cover error handling 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 concise and well-structured. The purpose statement is front-loaded, followed by a clear Args list and return format. Every sentence contributes useful information without unnecessary verbosity.

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

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

Given the tool's simplicity (3 parameters, output schema present), the description covers the essential aspects: input, output, and date filtering. It could be slightly more complete by mentioning that the input must be a valid Flex XML report and that only equity summary rows are extracted, but it is largely sufficient 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 schema description coverage is 0%, but the description compensates fully with an Args block that defines each parameter: xml_content is the raw Flex XML string, from_date is the earliest report date in YYYY-MM-DD (optional), and to_date is the latest report date in YYYY-MM-DD (optional). This adds significant 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 action ('Extract') and the specific resource ('daily NAV / equity summary rows from a Flex XML report'). It distinguishes itself from sibling parse tools like flex_parse_trades and flex_parse_positions by focusing on equity/NAV summary data.

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

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

The description implies usage through its purpose statement but lacks explicit guidance on when to choose this tool over alternatives. It does not mention exclusions or provide context for when to use the optional from_date and to_date parameters beyond their basic meaning.

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?

No annotations are provided, so the description carries full responsibility. It discloses the return JSON structure and parameter behaviors (case-insensitive symbol filtering, optional filters), but does not mention error handling, behavior on empty results, or whether the XML is validated. This adds useful context but omits some behavioral details.

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: a one-sentence purpose, a clearly labeled Args block, and a Returns line with the exact JSON shape. No filler or redundant information—every sentence contributes to understanding the tool.

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 covers purpose, parameters, and output format, which is sufficient for a relatively simple parsing tool. It does not mention how to obtain the XML (e.g., via flex_send_request) or potential limitations, but these are not critical gaps given the presence of an output schema and sibling context.

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

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

Schema description coverage is 0%, and the description fully compensates by explaining each parameter: xml_content is 'Raw Flex XML string,' symbol is 'Filter by ticker symbol (case-insensitive, optional),' and asset_category is 'Filter by asset category e.g. STK, OPT, FUT (optional).' This adds essential semantic meaning beyond the bare schema types.

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 begins with 'Extract FIFO realized/unrealized P&L summary from a Flex XML report,' which uses a specific verb ('Extract'), resource ('Flex XML report'), and output ('FIFO realized/unrealized P&L summary'). This clearly differentiates it from sibling tools like flex_parse_trades or flex_analyze_pnl by focusing on FIFO P&L specifically.

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 context by indicating it works on Flex XML reports and supports filtering, but it does not explicitly state when to choose this tool over alternatives (e.g., flex_analyze_pnl). No exclusions or alternative references are provided, leaving the agent to infer based on the tool name and description.

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?

With no annotations provided, the description carries the full burden of disclosing behavior. It states the return format ('Returns JSON: {"count": N, "positions": [...]}') and mentions that symbol filtering is case-insensitive, which are useful behavioral details. However, it does not address edge cases like invalid XML or empty results, and it does not explicitly confirm read-only behavior, though 'extract' implies it.

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, starting with a one-line summary, followed by a bulleted parameter list, and ending with a return format. There is no filler, and all sentences are information-dense.

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 relatively simple parsing tool with three parameters and a straightforward return format, the description covers the essential aspects: purpose, parameters, and return structure. It does not elaborate on invalid input handling or the exact fields within each position object, but given the presence of an output schema (per context signals), this is 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?

The input schema has 0% description coverage, so the description is the only source of parameter meaning. It explains xml_content as 'Raw Flex XML string,' symbol as 'Filter by ticker symbol (case-insensitive, optional),' and asset_category with examples ('STK, OPT, FUT'). This adds significant semantic value beyond the bare schema types and titles.

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

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

The description opens with 'Extract open position records from a Flex XML report,' which clearly states the action (extract), the resource (open position records), and the input source (Flex XML report). This distinguishes it from sibling tools like flex_parse_trades and flex_parse_cash_txns, which focus on other data types.

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 by stating it extracts open positions, but it does not explicitly contrast with alternatives or mention when not to use it. The filter parameters (symbol, asset_category) provide additional context for refining usage, but there is no direct guidance on choosing this over flex_parse_trades or flex_parse_equity. Clear context is present, but exclusions/alternatives are 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?

No annotations are provided, so the description carries the full burden. It discloses the return format (JSON with count and trades) and mentions filtering options, but does not discuss error handling, malformed XML behavior, or performance characteristics.

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 with an Args section and Returns line. Every sentence provides value, and there is no fluff.

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

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

The description covers purpose, parameters, and return format, which is adequate for a straightforward parsing tool. However, it lacks error-handling details and explicit usage context, slightly reducing completeness.

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 has no descriptions (0% coverage), but the tool description provides detailed parameter explanations: symbol filtering is case-insensitive, asset_category includes examples, and date format is YYYY-MM-DD. This adds significant 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 'Extract trade records from a Flex XML report' uses a specific verb and resource, clearly stating the tool's function. It distinguishes from sibling tools like flex_parse_positions by focusing on 'trades'.

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 purpose implies usage for parsing trade records, but there is no explicit guidance on when to use this tool versus alternatives or mention of exclusions. The description lacks contrast with sibling parsing tools.

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

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

With no annotations, the description carries the full burden. It discloses the polling behavior ('poll_interval_seconds', 'max_wait_seconds'), the wait-for-completion semantics, and the return format ('Returns JSON: {"xml_content": ...}'). It also mentions environment variable overrides for credentials. This provides substantial transparency beyond the schema, though it lacks details on error handling or side effects.

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

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

The description is compact, with a one-line purpose, a note on composition, a structured list of arguments, and a return-type line. Every sentence earns its place; no filler or redundant information. The structure is clean 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 moderate complexity (4 parameters, composite workflow, no annotations), the description is fairly complete: it covers what the tool does, how it works (polling), parameters, and return format. It could be improved by noting that the output is raw XML and that parsing tools exist for further analysis, but for its core function it is sufficient.

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

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

Schema coverage is 0%, so the description must fully explain the parameters. It does so effectively: each parameter is listed with its purpose and default behavior (e.g., 'query_id: Flex Query ID (overrides IBKR_FLEX_QUERY_ID env var)'). This adds meaning beyond the schema, which only provides types and defaults. The parameter explanations are clear and concise.

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

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

The description opens with a clear action: 'Send a Flex query and wait for the complete XML report.' It explicitly names the composite nature by stating 'Combines flex_send_request + flex_get_statement in one call,' which distinguishes it from its sibling tools. This gives a specific verb and resource, and differentiates it effectively.

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

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

The description clearly indicates this tool is a combination of two sibling tools, implying it should be used when a single call is preferred over sequential calls. However, it does not explicitly state when not to use it or provide direct exclusions for alternatives. The usage context is clear but not exhaustive.

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

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

With no annotations, the description provides some transparency by explaining that query_id and token override environment variables and by documenting the return JSON structure. It does not disclose potential side effects, error statuses, or whether the operation is read-only, leaving gaps.

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 brief and front-loaded, with a clear first sentence, followed by a compact argument list and return format. Every sentence adds value 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?

For a tool with two optional parameters and no annotations, the description covers purpose, parameter semantics, and return format adequately. It does not detail potential error cases or alternative flows, but is largely complete for its simplicity.

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 description gives meaningful explanations for both parameters, including their purpose and environment variable overrides. Since the schema has 0% description coverage, this fully compensates and adds significant value.

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 initiates a Flex query and returns a reference_code, which is a specific verb+resource. It indicates the output is used with flex_get_statement, providing some differentiation from sibling tools, though it does not explicitly contrast with flex_run_query.

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 context by mentioning the reference_code is for use with flex_get_statement, suggesting a two-step workflow. However, it does not explicitly state when to use this tool vs alternatives like flex_run_query, nor does it provide exclusions.

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