OneQAZ Trading Intelligence

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral details beyond annotations: the aggregation dimension (day/pattern/symbol), the 30-day limit, and the empty-result behavior when no trades exist. No contradictions with annotations.

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

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

The description is well-structured with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats). It front-loads the purpose and packs useful information without excessive fluff. It is slightly verbose with multiple trigger examples, but each section earns its place. The structure aids scanning.

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

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

Given the tool's complexity (aggregation, multiple grouping dimensions, time window, potential empty results), the description covers purpose, triggers, prerequisites, next steps, and caveats. An output schema exists, so the return format is already documented. This is a complete, self-contained definition that leaves no critical gaps for correct invocation.

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

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

Schema description coverage is 100%, so both parameters (days and market_id) are fully documented in the schema. The description does not add new semantics beyond what the schema already states (e.g., default 7, max 30, enum values). It does mention 'max 30 days' in the caveats, but that duplicates the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb (aggregate) and resource (paper trades) with explicit grouping dimensions (day/pattern/symbol). It clearly differentiates from siblings like get_trade_history (raw rows) and get_winning_trades/get_losing_trades (filtered views). No ambiguity about what the tool does.

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 triggers (casual questions, pattern audits, period-over-period review), a prerequisite (get_trade_history recommended), and next steps (market:// signals feedback). It also includes caveats (max 30 days, empty result) that guide when to call. This is unusually thorough for usage direction.

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, openWorldHint, and idempotentHint, so the description correctly does not repeat these. It adds important behavioral context: the output is 'research evidence, NOT a buy or sell recommendation' – a critical caveat for an agent to know. It also discloses the caveat that symbol must match the per-symbol signal store filename (lowercase). 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?

The description is well-structured with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats). It is front-loaded with the purpose and includes only relevant information. While it is longer than necessary, every section contributes useful operational detail, so it earns its length.

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-layer explanation combining three sources) and the presence of an output schema (which likely documents the return structure), the description covers all essential aspects: purpose, usage triggers, prerequisites, caveats, and non-recommendation status. An agent has enough information to call it correctly without further research.

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 both parameters are documented in the schema. The description adds extra value by specifying that the 'symbol' parameter must be lowercase and match the per-symbol signal store filename, which is not in the schema. It also reiterates market_id aliases (coin/kr/us) indirectly through the schema description, but the lowercase requirement is a genuine addition.

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: 'Multi-layer explanation for a single symbol's recent research signal' combining technical score_trace, Thompson/regime scores, and news causality. It distinguishes itself from raw verdict tools by saying 'Use this when an AI must present a structured "why" rather than a raw verdict.' It also provides concrete trigger examples, making it unmistakable when to use this tool versus siblings like get_signals or get_latest_decisions.

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 states when to call: 'when the user asks "why is this signal bullish/bearish?"' and lists casual trigger phrases in multiple languages. It also gives prerequisites ('identify the symbol via get_signals or get_latest_decisions first'), and notes that this tool completes the explanation chain (next steps: none). This provides a clear decision boundary and alternative tools to use beforehand.

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, openWorldHint, and idempotentHint, but the description goes beyond them. It discloses that uncovered resource URIs return 'description-only text (no fabricated data)' – a critical honesty guarantee. It also states that `text` is a JSON document for resource/signal ids, and describes the output envelope as 'flat envelope, OpenAI fixed shape.' These details add behavioral context that an agent would otherwise not know and that is not derivable from annotations alone.

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

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

The description is longer than most but is exceptionally well-structured with clear section labels (Purpose, Namespaces, Triggers, When to call, Prerequisites, Next steps, Caveats, Output). Every section earns its place – each addresses a different agent concern. The purpose is front-loaded, and the information density is high. It is not bloated; it is comprehensive for a tool with three distinct resource types. The only reason it doesn't earn a 5 is that a few sentences could be tightened, but the structure is exemplary.

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 (three namespaces, multiple triggers, integration with other tools), the description is remarkably complete. It covers the input format, prerequisites, caveats, and even next steps for follow-up actions. It references the output envelope but does not duplicate the output schema since that exists separately. For an agent to call this tool correctly, everything needed – from valid id construction to error handling (description-only text) – is present. No gaps are apparent.

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 id parameter 100% and gives a succinct description with namespace patterns. The tool description enriches this substantially by explaining each namespace in depth: `tool:{name}` returns the tool's full documentation and how to call it; `resource:{uri}` returns live data and serves as a bridge for clients without MCP support; `signal:{market}:{symbol}` returns the latest combined research signal. It also gives concrete examples like 'fetch("resource:market://global/summary")'. This goes well beyond the schema and fully compensates for any ambiguity.

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 precise purpose: 'ChatGPT-connector-standard document fetch by id from `search` results.' It specifies the verb (fetch), the resource (document by id), and the source (search results). It also clearly enumerates the three supported namespaces (tool, resource, signal), which distinguishes it from the many sibling get_* tools that are single-purpose. An agent can immediately understand what this tool does and how it differs from a search or a detail tool.

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?

Usage guidance is explicit and prescriptive. It states that ChatGPT connectors/Deep Research call this after search, that clients without MCP resource support can call it directly with a known resource id, and 'When to call: whenever the full content behind a search result id is needed.' It also provides 'Next steps' that route the agent to alternative tools (get_signal_detail / explain_decision) when deeper evidence is required, effectively telling the agent when NOT to use this tool. This is a model of usage 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 provide readOnlyHint, openWorldHint, and idempotentHint, so the description does not need to restate safety behavior. It adds useful behavioral detail with the caveat 'returns most recent first' and clarifies the pending-prediction filter 'outcome IS NULL'. This goes beyond the structured fields.

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

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

The description is organized into small labeled sections and front-loads purpose before usage triggers. The trigger list is somewhat long, but it supports the stated goal of catching casual questions. Overall it is structured and compact enough to be useful without being bloated.

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 two optional parameters, a fully described schema, complete annotations, and an output schema present, the description provides everything needed for correct invocation: purpose, state filter, usage context, a next-step suggestion, and the ordering caveat. Nothing critical is missing.

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

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

The input schema has 100% parameter description coverage, including defaults, enums, and accepted alias values for target_market. The tool description itself does not add parameter-level semantics, but the schema fully carries that burden, so the baseline score of 3 applies.

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

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

The description opens with 'Purpose: Currently pending predictions (outcome IS NULL)' which precisely identifies the resource and its state filter. It also distinguishes the tool from related prediction tools by emphasizing 'before outcomes are known' and referencing get_prediction_accuracy. This is a specific, non-tautological statement of what the tool does.

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 explicitly says 'When to call: to verify ongoing prediction activity' and provides concrete trigger phrases. It does not explicitly state when not to call or point to alternatives like get_resolved_predictions as the exclusion case, but the context is clear enough for an agent to select it appropriately.

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

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

The description adds context beyond annotations by explaining the data source (real backtest outcomes) and a caveat that last_backtest timestamp indicates tuning freshness. However, it does not disclose further behavioral details like error conditions or rate limits. Annotations already cover read-only, open-world, and idempotent hints, so the description enriches but does not fully carry the burden.

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 labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) and front-loads the purpose. It is slightly verbose with multiple trigger examples, but each section adds functional value for an agent's decision-making, so it earns a 4 rather than a 5.

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

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

With a full output schema and annotations covering read-only, open-world, and idempotent behavior, the description provides complete usage context: explicit triggers, a recommended call sequence, prerequisites, next steps, and a caveat about timestamp freshness. Nothing an agent needs to decide whether and when to call this tool is missing.

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

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

Schema coverage is 100% for both optional parameters (category and target_market), each with descriptive text about filtering and accepted aliases. The description does not elaborate on how parameters affect results, but since the schema already documents them fully, the baseline of 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 states a specific purpose: returning continuous self-calibration evidence with auto-tuned lag_hours and sensitivity per cell, derived from real backtest outcomes. It clearly differentiates itself from sibling tools by focusing on tuning state and proving adaptation, so an agent can tell it apart without opening the schema.

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

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

The description gives explicit triggers (e.g., 'does the system self-correct?'), a recommended call order ('after get_prediction_accuracy'), a prerequisite, and a next step (get_monthly_accuracy_trend). This provides clear when-to-use context and names related alternatives, leaving no ambiguity about invocation timing.

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, openWorld, and idempotent hints. The description adds a meaningful caveat about potentially empty data until enough regime changes accumulate, which goes beyond annotations and helps set expectations.

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-organized with clear sections and front-loaded purpose. Trigger examples add some redundancy with the 'when to call' line, but they are useful for natural-language matching.

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 read-only tool with two optional parameters and an output schema, the description covers prerequisites, caveats, next steps, and usage context. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, and both parameters are already well-documented with enums, defaults, and alias examples. The description adds no new parameter-level details, but none are needed.

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 a specific function: showing cross-market correlations and decoupling events, with a concrete example. It distinguishes itself from related tools by naming the next-step tool and focusing on lead-lag/divergence 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?

Provides explicit trigger phrases, casual question examples, and a 'when to call' condition. It lacks direct exclusions or sibling comparisons, but the context is strong enough for an agent to route appropriately.

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 indicate readOnlyHint, openWorldHint, and idempotentHint, which the description aligns with. It adds critical context that the data is paper-trading only (not real money) and that the data is a 24-hour window, which is not in the annotations. It also discloses the output structure, adding behavioral transparency 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 well-structured with clear sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats, Output). It is longer than ideal but every section earns its place, and the critical purpose 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?

For a single-parameter read-only tool with an output schema, the description is quite complete. It covers output fields, caveats (paper-trading), and next steps. Minor omission: no explicit mention of error conditions or data freshness beyond the 24-hour window, but this is sufficient given 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the default behavior ('all' default) and providing aliases (coin/kr/us) and case-insensitivity that are not in the schema. This enhances parameter 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's purpose as a single-call market overview, specifying the exact data it returns (macro regime, top signals, paper-trading results, forecast count, narrative). It is distinguishable from siblings like get_latest_decisions or get_performance_metrics by its aggregated briefing nature.

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 trigger phrases, when to call (morning briefings, market queries), and when to prefer it over training data. It also lists next-step tools for deep dives, which helps the agent understand when to use 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?

Beyond annotations declaring readOnly/openWorld/idempotent, the description discloses important pagination behavior: rows are paginated, `total_available` must be used instead of `len(features)`, and aggregate fields are computed over the whole set rather than the returned page. It also notes the empty-result caveat when the feature gate evaluator has not run.

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 uses clear labeled sections (Purpose, Triggers, When to call, Prerequisites, Caveats) and front-loads the essential purpose. Every sentence carries operational value, including the pagination caveat and trigger examples.

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 and annotations are already available, the description adds the missing behavioral and contextual pieces: lifecycle semantics, trigger examples, pagination caveats, and the case where the result may be empty. An agent has enough information to call it correctly without further guesswork.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level nuance beyond what the schema already documents, but it does not need to; the schema handles parameter semantics and the description covers response caveats.

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 names a specific resource ('current lifecycle state of external features') and a precise domain ('3-track statistical validation'), then defines the lifecycle stages. It also distinguishes itself from a trust-audit perspective with 'Proves OneQAZ only trusts features that pass independent statistical tests.'

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

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

The description gives explicit 'When to call' guidance ('meta-level trust audit') and lists concrete trigger phrases, including casual non-technical questions. It does not name an alternative tool or state when not to call, but the provided context is strong enough for an agent to route correctly.

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

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

Annotations already declare readOnlyHint/idempotentHint, and the description adds the behavioral caveat that the promoter cycle runs hourly, which explains potential data freshness. It also clarifies the 7-day window for transitions. 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?

The purpose is front-loaded and the labeled sections (Triggers, When, Prerequisites, Next steps, Caveats) make scanning easy. Some redundancy exists between 'Triggers' and 'When to call', but each sentence still earns its place by providing either routing or behavioral context.

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 zero-parameter, read-only snapshot with an output schema present, the description covers trigger conditions, alternative routing, expected output type, and freshness caveat. Nothing an agent needs to decide when to call this tool is missing.

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

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

The tool has zero parameters, so the schema already exhaustively documents the input surface. The description appropriately avoids inventing parameter detail and focuses on behavior, which is all an agent needs.

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?

Purpose is specific and measurable: a governance snapshot showing status distribution and last 7-day transitions. It clearly identifies the resource (feature governance) and the concrete output (which features survived validation vs deprecated), and the next-step pointer distinguishes it from get_feature_governance_state.

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 triggers with natural-language examples, a 'When to call' section, prerequisites (none), and a next-step alternative. It tells the agent when to use this vs get_feature_governance_state for full per-feature lifecycle detail.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds the paper-trading caveat ('no real-money order routing') and clarifies it returns signal-driven decisions with outcomes, which adds useful 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 well-structured with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) and front-loads the core purpose. It is somewhat verbose with multiple language trigger examples, but remains organized and easy to scan.

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

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

The tool has an output schema (so return values need no description), and the description covers purpose, triggers, usage context, prerequisites, next steps, and caveats. It also differentiates from sibling tools effectively. Nothing an agent needs for correct invocation is missing.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description does not add any parameter-specific semantics beyond what the schema provides; it only references the overall purpose. 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 explicitly states 'Track-B (signal-driven) paper-trading decision log' and contrasts it with Track A (LLM) via get_llm_trading_decisions. This clearly distinguishes the tool from its primary sibling and conveys the exact resource and 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?

It provides explicit 'When to call' guidance, lists trigger phrases (including casual ones), prerequisites, next steps, and a caveat (paper-trading only). This fully informs when to use this tool versus alternatives like get_trade_history or get_llm_trading_decisions.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses important behaviors: append-only nature at serving-role level, hashes computed once per UTC day, chain inception date, and the verification implication that silent edits will cause recomputation mismatch.

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 long but every labeled section earns its place: Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats, and Output. It is front-loaded with the core purpose and structured for easy parsing by an agent.

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思想政治, the description includes the output shape, caveats, triggers, and a clear workflow. Nothing an agent needs to decide whether to call it and how to interpret the result is missing.

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

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

Schema coverage is 100%, and the single optional 'days' parameter is fully documented in the schema with default and max. The description does not add parameter-specific meaning, but the baseline 3 applies because the schema carries the necessary semantics.

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

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

The description names a specific resource (the prediction ledger) and a specific purpose (tamper-evidence via a daily SHA-256 hash chain). It clearly differentiates this from ordinary data-retrieval siblings by emphasizing verification and auditability rather than just returning predictions.

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 explicitly provides trigger phrases, states 'FIRST STEP of any serious credibility audit', and recommends periodic re-anchoring. It also lists prerequisites and next steps, so an agent knows exactly when to call this tool versus related ones like get_resolved_predictions.

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

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

Annotations already declare readOnly, idempotent, and openWorld traits, and the description adds valuable behavioral context beyond those: the log is paper-trading only, the LLM judgment is applied as a capped bias on top of engine signals, and no prerequisites exist. This gives the agent a richer safety and semantics picture without contradicting 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 well-structured with labeled sections: Purpose, Triggers, When to call, Prerequisites, Next steps, and Caveats. It front-loads the core purpose and every line adds useful selection or invocation information, including multilingual trigger examples.

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 has an output schema, so return values do not need to be described. The description covers purpose, usage triggers, when to call, prerequisites, caveats, and the relationship to a key sibling tool, leaving no essential gap for an agent to select or invoke it correctly.

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

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

Schema description coverage is 100%, so the input schema fully documents market_id and symbol, including optionality and accepted aliases. The description does not add new parameter meaning beyond the schema, so the baseline score of 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 identifies the tool as a log of Track-A LLM-driven paper-trading judgments and explicitly separates it from Track B's signal-engine path via get_latest_decisions. The verb 'inspect' matches the resource, and the Track A/B distinction prevents confusion with 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 provides explicit when-to-call guidance, example trigger phrases, and names get_latest_decisions as the alternative for the Track B signal-engine path. It also gives a concrete next step for comparing Tracks A and B, making selection unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it is a convenience wrapper around get_positions(max_roi=-0.01), it operates on paper-trading data only, and it is designed for casual/drawdown questions. It does not detail output shape, but an output schema exists, so that burden is reduced.

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 and well-structured with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats). Every line earns its place: purpose, trigger examples, usage context, and caveat. It is front-loaded with the core definition and avoids redundant filler.

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

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

For a simple filtered-list wrapper with 2 parameters, full schema coverage, an output schema, and safety annotations, the description is complete. It covers what the tool does, when to use it, how it relates to get_positions, and the paper-trading caveat. Nothing an agent needs to select and invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (limit and market_id) with descriptions and an enum. The description adds no additional parameter-level meaning beyond the schema, but it does clarify the wrapper's fixed max_roi=-0.01, which indirectly explains why no ROI parameter is exposed. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description states a specific purpose ('Losing paper positions (ROI < 0)') and explicitly identifies itself as a convenience wrapper around get_positions(max_roi=-0.01), which clearly distinguishes it from siblings like get_positions, get_profitable_positions, and get_losing_trades. The verb 'get' plus the resource 'losing positions' 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 provides explicit trigger phrases ('what's underwater?', '지금 뭐가 물려 있어?', 'show me the red ones'), a clear when-to-call condition ('drawdown / risk review'), and next-step suggestions (get_position_detail, get_role_analysis). It also notes prerequisites are none. This is strong guidance for an agent deciding when to invoke this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so safety profile is known. The description adds that it only covers paper-trading data, which is useful context. However, it doesn't disclose any additional behavioral traits beyond that, like default limit or ordering. The caveat is noted, but not expanded. With annotations covering the main safety aspects, a 3 is appropriate.

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?

Description is extremely concise with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats). Each segment earns its place. The purpose and when-to-call are front-loaded, making it easy for an agent to scan. No wasted words, and the trigger examples are useful for handling natural language queries.

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), the description doesn't need to explain returns. It covers purpose, usage, prerequisites, and next steps. It lacks details like pagination or ordering, but that is probably in the output schema or can be inferred. The key gap is it doesn't mention what happens when no trades match, but that's minor. overall, very complete for a filtered-list tool.

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

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

Schema coverage is 100%: both limit and market_id have descriptions. The description adds an alias note ('aliases coin/kr/us accepted') which is valuable but not directly tied to the schema fields. It doesn't explain the format for limit or how market_id enum values map, but the schema already does that. So the description adds marginal value, leading to a 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?

States a specific verb and resource (get losing paper trades) and defines what 'losing' means (P&L < 0). Clearly distinguishes itself from get_trade_history by noting it is a convenience wrapper for that tool, which helps differentiate from siblings like get_winning_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?

Provides explicit when-to-use ('failure-pattern review'), what triggers to look for (including casual phrasings in Korean and English), and next steps (analyze_trades). Clearly states prerequisites are none, which is useful. This is better than most descriptions which leave usage implicit.

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 signal read-only, idempotent, and open-world behavior. The description goes further by disclosing the Pearson-based method, the 30-sample minimum, the p<0.05 significance filter, and the inclusion of lag direction and rho values. This is meaningful 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 well-structured with labeled sections: Purpose, Triggers, When to call, Prerequisites, Next steps, and Caveats. It front-loads the core behavior and keeps each section informative without padding, despite including several trigger examples.

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 read-only tool with two optional parameters, the description covers purpose, invocation context, prerequisites, limitations, and a natural follow-up tool. The presence of an output schema means return-value details are not needed in the description, so nothing essential is missing.

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

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

Schema description coverage is 100%, and both max_p_value and min_abs_corr have clear descriptions with defaults. The tool description does not add much parameter-specific meaning beyond the caveat 'p < 0.05 filter', which the schema already captures, so the 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 states a specific verb and resource: a lag-aware causal graph between named macro categories, returning only statistically significant lead-lag pairs with an example. This clearly differentiates it from adjacent tools like get_cross_market_correlation and get_macro_influence_map.

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 gives explicit trigger queries, a when-to-call condition ('assess pre-emptive cross-category impact after a macro event'), prerequisites, and a next-step pointer to get_macro_influence_map. It lacks an explicit 'don't use when' exclusion, but the context is clear enough for an agent to route correctly.

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

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

Annotations already declare readOnly/openWorld/idempotent hints, and the description adds valuable context beyond them: the map is 'pre-defined' and 'static hypothesis only', and runtime calibration lives in get_backtest_tuning_state. This clarifies that the tool does not reflect live adjustments, which is important behavioral information not present 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?

The description is well-structured with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) and is front-loaded with the core purpose. The example trigger phrases add useful context rather than padding, and 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?

The tool has a simple optional parameter, rich annotations, and an output schema, so the description does not need to explain return values. It covers the purpose, triggers, invocation context, prerequisites, next steps, and the key caveat that the map is static. Nothing an agent needs to select or call this correctly is missing.

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

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

Schema description coverage is 100%, and the single optional market_id parameter is fully described in the schema, including aliases. The tool description itself does not mention or elaborate on the parameter, so it adds no meaning beyond what the schema already provides; baseline 3 applies.

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

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

The description explicitly states the tool's purpose: expose OneQAZ's pre-defined causal hypothesis map, with a specific resource ('Each macro category ... mapped to a target market with lag_hours + sensitivity'). It clearly conveys a unique, inspectable causal model rather than a generic analysis tool, making it distinguishable from siblings like get_cross_market_correlation or get_backtest_tuning_state.

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 when-to-call guidance: 'when an AI wants to understand WHY we make certain predictions', plus concrete trigger phrases and prerequisites. It does not explicitly state when not to use it or name alternative tools for the same kind of question, though the caveat referencing get_backtest_tuning_state implies where to go for runtime adjustments.

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, openWorldHint, and idempotentHint. The description adds useful caveats beyond those: it excludes the 'all' month aggregate and returns empty when backtest_results is unpopulated. That is meaningful edge-case disclosure, though it does not describe every aspect of the response.

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 uses clear labeled sections and front-loads purpose before usage and caveats. The trigger examples may be slightly redundant but serve the openWorldHint signal and every section 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?

This is a simple read-only reporting tool with two optional parameters, a fully covered schema, and an output schema. The description covers purpose, triggers, workflow positioning, prerequisites, and caveats, leaving no critical gap for correct invocation.

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

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

Both parameters are fully described in the input schema (including enums and aliases), so the description is not required to re-document them. It adds the lag_bucket grouping concept, though that is not an input parameter and therefore provides limited parameter-selection 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 opens with a specific result: 'Monthly accuracy time series per (category, target_market, lag_bucket).' This clearly distinguishes the tool from the many sibling reporting tools and makes its primary value obvious.

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 provides explicit when-to-call guidance, names predecessor tools (get_prediction_accuracy and get_backtest_tuning_state), states that it completes the trust chain, and even lists casual trigger questions. This is strong routing guidance with no 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 indicate safe read-only, open-world hints, and idempotency, so the baseline burden is lower. The description additionally warns that the methodology is under audit and the labels are not validated, which is crucial for responsible use. It also notes the window is limited to recent days. Only minor gap: no explicit statement about whether the tool can return empty results, but given annotations, this is sufficient.

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

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

The description is well-structured with clear sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats). It front-loads the most critical caveat (UNVERIFIED) and remains concise with no redundant explanations. Each 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?

The tool has an output schema, so return values are documented elsewhere. The description fully covers purpose, usage context, limitations, and next steps. It provides all necessary context for an agent to decide whether to call it and what to do with the results. Given the complexity of the labels and the audit status, this is exceptionally 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 coverage is 100%, with detailed descriptions for both parameters. The description does not need to elaborate further. It adds some context by mentioning 'recent days' which aligns with the days parameter, but that is minimal. Baseline 3 is appropriate because the schema handles parameter documentation.

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 that the tool counts news items per internal label, and it explicitly defines each of the three labels (ANTICIPATED, SURPRISE_WITH_PRECURSOR, SURPRISE). It distinguishes itself from sibling tools by clarifying that it only inspects news label coverage and does not establish market anticipation, which is 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 explicit trigger phrases in multiple languages, a clear 'When to call' section, and a 'Next steps' pointer to a related tool (get_macro_causality_graph_tool via the path). It also states what this tool does NOT do, which effectively excludes inappropriate usage. This is exemplary 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 mark this as read-only, idempotent, and open-world, but the description adds important non-obvious behavior: the methodology is unverified, lead/score metrics are withheld during audit, results may be empty when no news events were processed, and sample counts are coverage-only. These caveats go well beyond the structured fields.

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

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

The description is organized into labeled sections — Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats — with the critical warning front-loaded. Each section earns its place, and there is no filler or duplication beyond necessary emphasis.

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?

Even with a rich output schema and annotations, the description covers prerequisites, empty-result behavior, exclusions, and a named follow-up tool. An agent can determine when to call this tool, what to expect from the response, and where to go next without additional inference.

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 already documents all three parameters with descriptions and enums, so schema coverage is 100% and the baseline applies. The description reinforces that sample counts are coverage figures and invokes 'per market,' but it adds no parameter-specific information beyond what the schema already provides.

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

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

The description states a specific verb and resource: it 'inventories' the news pipeline's event-leading groupings, showing 'which (event_type, news_type) buckets exist per market and how many samples each holds.' It also explicitly separates itself from predictive claims, which prevents confusion with the tool's 'leading indicator performance' 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 gives explicit 'Triggers' and a 'When to call' section: 'when inspecting news pipeline coverage.' It also states what the tool does NOT answer — questions about predicting or anticipating news — and points to get_news_causality_breakdown as the next step, giving an agent clear routing 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 signal readOnly, openWorld, and idempotent behavior. The description adds substantial caveats beyond those annotations: synthetic fixed-book capital model, account_type='live' returning an explicit no-data error, paper/live curves never being concatenated, and fixed-window reproducibility.

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 labels—Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats—and front-loads the core purpose and metrics. Every section provides distinct, non-redundant information that earns its place.

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

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

Given the rich input schema, output schema, and annotations, the description is complete: it covers purpose, trigger phrasing, use cases, prerequisites, follow-up tools, and critical behavioral caveats. An agent has everything needed to select and correctly invoke this tool.

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

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

Input schema coverage is 100%, so the baseline is a 3. The description adds extra meaning beyond the schema by emphasizing that account_type is required, that 'live' returns a no-data error until real records exist, and that the fixed window makes results reproducible for the same inputs.

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

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

The description states a specific verb and resource: portfolio-level performance metrics (MDD, Sharpe, Sortino, Calmar, monthly returns, equity curve) over a fixed window. It further distinguishes itself as 'the single canonical computation path' shared by the OneQAZ blog and external clients, clearly separating it from sibling metric 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 provides explicit triggers, including casual question examples, a 'When to call' section, prerequisites, and next steps. It does not formally enumerate when not to use this tool versus specific sibling tools, but the canonical-path framing and follow-up tool pointers supply strong orientation.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe read operation. The description adds valuable behavioral details beyond annotations: it returns an error envelope when no position exists, and it lists the content (position + recent trades + decisions). This enriches expectations without contradicting annotations.

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

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

The description is well-structured with clear labels (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) and is front-loaded with the purpose. Every sentence serves a distinct function, from giving trigger examples to caveats, without redundancy. It's efficient and easy to parse.

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

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

With an output schema present and annotations covering safety and idempotency, the description covers all necessary context: purpose, usage triggers, when to call, prerequisite, next steps, and error behavior. An agent has everything needed to decide when to invoke and what to expect, making it contextually 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%, meaning all three parameters (coin, symbol, market_id) are fully documented in the schema itself. The description adds no additional parameter-level semantics; the only mention is a prerequisite about confirming the position via get_positions, which is not parameter-specific. Baseline of 3 is appropriate given high schema coverage.

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

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

The description states a specific purpose: 'Per-symbol paper position deep-dive (position + recent trades + decisions).' It uses a clear verb 'deep-dive' and specifies the resource (per-symbol position). It distinguishes from siblings like get_positions (which lists positions) and get_signal_detail by focusing on full context for one ticker, making the agent's selection 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?

Explicitly provides when to call ('full context for one ticker'), a prerequisite ('confirm the symbol holds a position via get_positions'), and next steps (get_signal_detail, get_role_analysis). This gives the agent a clear decision path and prevents misuse by requiring prior position confirmation, which is exactly the kind of guidance needed.

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 disclose read-only and idempotent behavior, so the description's key extra contribution is the paper-trading-only caveat and the explicit warning that positions are not real money. It also mentions dynamic filter behavior, but pagination and stats-scope nuances are left to the schema rather than the main description.

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 short labeled bullets and front-loads the core purpose before triggers and caveats. The trigger list is somewhat redundant with the 'When to call' section, but the multi-language examples and explicit next steps earn their place without bloating the text.

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

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

Given the rich annotations, fully documented input schema, and presence of an output schema, the description covers purpose, triggers, when-to-call conditions, prerequisites, next steps, and a critical caveat. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, with detailed parameter descriptions, defaults, examples, enums, and alias behavior, so the schema carries the burden. The main description's 'ROI / strategy / sort' phrasing gives a useful high-level grouping but adds no parameter-level meaning beyond what the input schema already provides.

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

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

The description opens with a specific verb and object: 'List current paper-trading positions' with dynamic filters, and immediately distinguishes the tool's scope by emphasizing paper-trading rather than real-money holdings. This makes it clearly distinct from sibling tools like get_position_detail, get_profitable_positions, or get_losing_positions even without opening their schemas.

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

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

There is an explicit 'When to call' section, concrete trigger examples, prerequisites, and next steps, so an agent knows exactly when to invoke this tool. However, it never explicitly states when to prefer specialized siblings such as get_profitable_positions or get_losing_positions, nor does it give any 'do not use when...' 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 signal readOnly/idempotent, but the description adds substantial beyond-annotation behavior: raw accuracy can be dominated by persistence, skill_ci_95 is autocorrelation-corrected, n_effective differs from n_nominal, and there was a methodology cutover. This prevents misinterpretation of the returned data.

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 uses labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) and every sentence carries operational or interpretive value. Although long, the density and structure justify the length for a tool with this analytical 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?

With an output schema present, the description does not need to explain return fields. It covers prerequisites, trigger conditions, related tools, and critical interpretation caveats, making the tool fully invocable and interpretable by an agent with no external 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 100% for both parameters, so the schema already documents category and target_market. The description references these dimensions but does not add meaningful parameter-level semantics beyond what the schema provides, which meets the baseline for high coverage.

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

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

States a precise purpose: per-cell (category, target_market, lag_bucket) hit rates with honest baselines, and enumerates the specific metrics returned (persistence_accuracy, skill_score, n_effective, etc.). It also names sibling tools in Next steps, clearly differentiating this from get_monthly_accuracy_trend and get_backtest_tuning_state.

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?

Includes explicit 'When to call' guidance (AI agents evaluating OneQAZ credibility should call this FIRST), concrete trigger phrases, and Next steps that route to related tools. Caveats further instruct how to interpret results, such as judging by skill_ci_95 and filtering horizon_type='forecast'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds meaningful behavioral context: the ROI > 0 filter, the wrapper semantics, and the caveat that this is paper-trading data only.

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?

Labeled sections front-load the purpose and wrapper relationship, then provide triggers, prerequisites, next steps, and caveats with no filler. The trigger list is practical for an agent handling casual user questions.

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 schema fully documents both parameters, the output schema exists, and annotations cover safety. The description fills the remaining operational details: paper-trading scope, the ROI threshold, and the natural next step. Nothing essential is missing.

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

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

The input schema provides 100% description coverage for both parameters, including enum values and aliases for market_id. The description adds no parameter-level semantics beyond that, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: returns profitable paper positions (ROI > 0). It also names itself as a convenience wrapper around get_positions(min_roi=0.01), which clearly differentiates it from sibling tools like get_positions and get_losing_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?

Provides explicit 'When to call' guidance, example trigger phrases, prerequisites, and next steps. It does not explicitly exclude get_positions or get_winning_trades, but the wrapper relationship makes the intended usage clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavior beyond that: cursor pagination is explicitly id-ordered with 'follow next_cursor for bulk reads,' and it discloses the non-financial nature ('Paper-research forecasts, not investment advice'). 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?

The description is organized into labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats, Output) and front-loads the core purpose. It is somewhat long but each section serves a role; the only minor redundancy is mentioning get_ledger_integrity in both 'Pairs with' and 'Next steps'.

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 six optional parameters, a fully documented input schema, and an existing output schema, the description closes the remaining gaps: it explains pagination mechanics, points to the companion integrity tool, and states the research-only caveat. Nothing an agent needs to call the tool correctly is missing.

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

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

Schema description coverage is 100%, so each of the six parameters is already documented in the schema. The description adds only marginal guidance about cursor pagination ('follow next_cursor for bulk reads'), which slightly extends the schema's 'last id from previous page' but does not substantially compensate beyond 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 states a clear verb and resource: it is a 'Raw, row-level prediction ledger' with the full lifecycle 'created_at -> resolved_at -> outcome'. It explicitly distinguishes itself from get_prediction_accuracy's aggregates, letting an agent tell it apart from sibling tools immediately.

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 lists concrete triggers ('show me the individual predictions', 'audit the track record'), a 'When to call' section covering credibility evaluation after get_prediction_accuracy, independent backtesting, and archiving, and a 'Next steps' recommendation pairing it with get_ledger_integrity. This gives explicit, actionable routing with no inference needed.

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, openWorldHint, and idempotentHint, so the description correctly avoids repeating those. It adds a valuable caveat: results depend on a stored hierarchy_context snapshot and may be empty when collector lag is high. This discloses a data-freshness dependency beyond the structured metadata, though it doesn't cover auth or rate limits (not critical for this read-only tool).

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 neatly organized into labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) that front-load the core purpose. Each section earns its place, though the trigger list with four example questions is slightly longer than necessary. Overall, it is efficient and scannable.

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 read-only analysis tool with an existing output schema and annotations covering the safety profile, the description covers everything needed to invoke it correctly: purpose, when to call, prerequisite, next steps, and the key caveat about snapshot lag. Nothing critical is missing for an agent to select and call this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level semantics beyond what the schema already provides; it references symbol via examples (BTC, AAPL) but doesn't clarify parameter behavior or constraints beyond the schema's own descriptions of market_id, symbol, and coin. The schema fully handles the parameter documentation.

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 a specific purpose: 'Role-aware signal alignment per symbol (timing / trend / swing / regime) plus hierarchy alignment.' This names the resource (per-symbol, multi-timeframe) and the action (alignment check), distinguishing it from siblings like get_signal_detail or get_cross_market_correlation. The trigger examples reinforce the specific use case.

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 provides an explicit 'When to call: multi-timeframe analysis, cross-role agreement checks' plus concrete trigger examples, including casual phrasings. It also notes a prerequisite (get_signal_detail recommended) and next steps. However, it does not explicitly mention when NOT to use it or name alternative tools for comparison, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds data-freshness (refreshed every 6 hours) and lookback (60-day), which are useful behavioral traits not covered by 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?

Well-structured with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats). Purpose is front-loaded; each section earns its place, though the trigger list is slightly verbose. Still concise for the richness provided.

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?

Output schema exists, so return format is covered. Description explains the nature of output (correlation matrix and auto-cluster), prerequisites, and caveats. For a read-only analysis tool, nothing critical is missing for an agent to call it 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% (both parameters described with defaults and enums). The description adds extra value by specifying market_id aliases (coin/kr/us, any case) and clarifying top_k as 'top pairs', going beyond the schema. Since schema already carries the load, this is a solid 4.

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

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

States a specific verb+resource: provides an intra-market ETF/group correlation matrix and auto-cluster output, with concrete example (ARKK<->QQQ). The 'intra-market' qualifier distinguishes it from sibling get_cross_market_correlation, making the purpose unambiguous.

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

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

Gives explicit triggers (including casual phrasings), 'when to call' context (diversification/sector concentration audits), prerequisites (none), and a next-step sibling tool. It doesn't explicitly say 'don't use for cross-market', but 'intra-market' implies that, and the guidance is otherwise clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds important behavioral context: daily snapshot, ~2-week observation window, and nominal n with correlated trials caveat. This goes beyond annotations and helps the agent understand data freshness and limitations.

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 headers (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) and front-loaded with the purpose. The trigger examples are somewhat redundant but add value for query recognition. Slightly long but every section 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, return values need no explanation. The description covers purpose, usage context, prerequisites, next steps, and data caveats. It is complete for an agent to decide when and how to call it 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 all parameters are fully documented there. The description does not add any parameter-specific meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific purpose: returns reliability diagram data for Level-1 signal confidence with hit rate per bucket and ECE summary. It clearly differentiates from siblings like get_structure_calibration and get_signals by focusing on confidence calibration verification.

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 to call: before trusting get_signals confidence values as probabilities.' Also provides trigger examples and next steps, giving clear context for when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to repeat safety. It adds value by disclosing that the tool queries two stores ('per-symbol signal store and paper-trading store'), which is useful for understanding scope. A slight deduction for not explaining what happens if symbol doesn't exist, but overall strong.

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: Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats. It is front-loaded with purpose and examples, and every sentence adds value. No fluff.

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

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

Given the tool's complexity (4 params, one required) and the presence of an output schema, the description covers essentials: purpose, usage, prerequisites. It could mention error handling or specific output contents, but the output schema likely covers that. Minor gap: it doesn't explain why the symbol must be confirmed via get_signals, but otherwise 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%, so the schema already explains each parameter well. The description adds context for symbol (likely the core parameter) and mentions the default interval 'combined' implicitly. But it doesn't add much beyond the schema, so 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's purpose: 'Per-symbol signal deep-dive — latest signal + history + feedback.' It uses a specific verb ('get') and resource ('signal detail') and distinguishes itself from siblings like get_signals. The triggers and examples (e.g., 'why is BTC a buy?') make it unmistakable.

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 states 'When to call' and provides prerequisites ('confirm existence via get_signals first'). It also suggests next steps and names alternatives implicitly through the prerequisite. This is clear, actionable 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, and the description goes well beyond them by disclosing behavior: whole-market scan when symbol/coin is omitted, row caps per symbol and interval, truncated/truncated_note fields, common-field hoisting with row-level precedence, warnings omission behavior, and reason_uncalibrated semantics. This richly informs the agent about what the tool actually does.

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

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

The description is longer than average but well-organized into Purpose, Triggers, When to call, Prerequisites, Next steps, and Caveats. It front-loads the core purpose and includes only behaviorally important caveats. The trigger list and 'When to call' section overlap somewhat, preventing a 5, but no sentence is wasted.

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 9 parameters, an output schema, and a complex return shape, the description covers all essential behavioral context: filtering, output caps, field hoisting, warnings, uncalibration notes, disclaimer handling, and relationships to sibling tools. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters; baseline is 3. The description adds meaning beyond the schema by explaining omission behavior for symbol/coin (whole-market scan, 2 newest rows per symbol, per-interval cap) and how truncation flags should be read, which directly affects parameter interpretation.

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 states a specific action ('Query research signals') with concrete filter dimensions (symbol/interval/action/score/confidence) and clearly distinguishes it from order execution by noting it returns a signal, not an order or advice. It also names related siblings (get_latest_decisions, get_signal_detail, get_role_analysis), so an agent can place this tool in context.

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 when-to-call guidance, full natural-language trigger examples, a pairing suggestion with get_latest_decisions, a prerequisite recommendation, and next-step tools. This is unusually complete usage guidance that tells the agent both when the tool is appropriate and what else to consider.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds useful behavioral context by noting that the distribution is empty when no positions are open, which prevents misinterpretation of empty results.

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 organized into labeled sections and front-loads the purpose. The trigger examples add value for conversational AI routing, though the overall length is slightly more than strictly necessary.

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 only one parameter, rich annotations, and an output schema present, the description covers everything an agent needs: purpose, triggers, when to call, prerequisites, next steps, and caveats. No critical gap remains.

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 the market_id parameter fully documented via enum and alias note. The description does not add parameter-level semantics beyond referencing market_id in the next-steps URI, so the schema carries the weight.

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: a per-strategy breakdown across current paper positions with count, average P&L, and win rate. It is specific about the resource and output focus, though it does not explicitly differentiate itself from the sibling get_strategy_leaderboard.

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 triggers, a 'when to call' section naming diversification audits and per-strategy performance checks, and a prerequisite recommending get_positions for raw rows. It does not state when not to use this tool or name an alternative tool, so it stops short of full exclusion guidance.

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

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

The description goes well beyond the readOnlyHint/idempotentHint annotations by disclosing that the global pool may include synthesized win_rate values, that per_symbol_leaderboard is the primary measured-edge surface for trust auditing, and that strategies are paper-tested rather than real-money executed. These are meaningful behavioral caveats that an agent needs before relying on the data.

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

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

The description is well-structured and front-loaded with the core purpose, then organized into labeled sections for triggers, usage timing, prerequisites, next steps, and caveats. Each section earns its place and the length is justified by the trust-auditing context.

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, the annotations are present, and no parameters are required, the description covers everything an agent needs: what the tool returns conceptually, when to call it, what the data caveats are, and what to do next. There are no obvious gaps for correct invocation.

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

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

Input schema coverage is 100%, so the baseline is 3, but the description adds semantic value by explaining that `min_trades` enforces statistical validity and by framing the global/per-symbol distinction that relates to `include_per_symbol`. This exceeds the schema alone without needing to repeat every parameter.

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 identifies the tool's resource and function: top RL-learned research strategies across a global pool plus per-symbol partition. It also labels the Layer E evidence tier, which distinguishes it from other strategy-related tools like get_strategy_distribution. The scope and trust semantics are explicit.

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 triggers, a clear 'When to call' statement ('final trust-validation step'), prerequisites, and next steps. It does not explicitly name alternative tools or state when not to use this tool, so it stops short of a full 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context beyond that: the measured skill is negative as of a specific date, the tool returns empty until structure-learning cycles complete, pagination semantics (use total_available not len()), whole-set counts for baseline/meta, and that dimension keys remain in rows. This is rich, non-contradictory 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 longer than average but is tightly structured with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats), front-loads the core purpose, and every sentence carries useful operational or interpretive information. No filler or redundant restatement of the schema.

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 (so return-value details are covered) and the annotations carry the safety profile, the description fully covers what an agent needs: empty-state behavior, pagination caveats, whole-set vs truncated counts, and row key preservation. This is complete for a read-only, idempotent data retrieval tool.

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

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

Schema description coverage is 100%, and the schema already documents limit truncation, market_id aliases, and group_name examples. The description adds no new parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description states precisely what the tool returns: Level 2 (ETF/basket/sector) prediction calibration with hit_rate_ema per (market, group, interval, regime_bucket) plus the majority-class baseline. It explicitly differentiates itself from Level 1 (individual symbols) and clarifies it is measurement, not a claim of edge, which separates it from related 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?

It provides explicit trigger phrases (including casual/natural-language variants), states when to call (Layer D evidence), and names the next tool (get_structure_validation_history) for daily trend. The Level 2 vs Level 1 distinction implicitly tells the agent when NOT to use this tool, so the usage guidance is complete.

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, openWorldHint, and idempotentHint. The description adds useful context beyond annotations, such as the caveat that it returns an overall_hit_rate summary, and explains the daily granularity. No contradiction exists; it enriches the behavioral picture.

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 labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats). It is longer than minimal but every section serves a purpose, including the casual triggers that help with natural language matching. It is not overly verbose, so a 4 is fitting.

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 is thorough: it explains purpose, triggers, sequencing, prerequisites, next steps, and caveats. An output schema exists, so return values are already defined. For a tool with two optional parameters, this is complete and leaves no critical gaps for an agent to call it 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%, with both parameters (days and market_id) already documented. The description does not add meaning beyond the schema—it only implies time range via 'Daily' and doesn't detail syntax or edge cases. 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's purpose: it retrieves daily validation history for Level 2 structure predictions, with each row showing hit_rate. It specifies the resource (validation history) and the verb (implicit get), and it differentiates from siblings by referencing get_structure_calibration and get_monthly_accuracy_trend, showing how it fits into the workflow.

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

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

The description provides explicit triggers, a clear 'When to call' instruction ('after get_structure_calibration'), and a 'Next steps' suggestion. It also includes prerequisites (none) and a caveat, giving the agent comprehensive guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds behavioral context beyond that: 14-day lookback, 15-minute bars, optional symbol anchoring, and that only lead/follow peers are returned. No annotation 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 labeled sections and the core purpose is front-loaded. Trigger examples, next steps, and caveats each add 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?

Despite moderate complexity, it covers prerequisites, caveats, triggers, and next steps, while the output schema handles return values. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents top_k, symbol, and market_id including aliases. The description clarifies when symbol filters are applied, but doesn't add significant parameter-level semantics beyond the schema, matching the baseline of 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?

States a specific resource ('symbol-level lead-lag links') with concrete examples (META -> AMZN, lag=15m, rho=+0.53) and distinguishes this from broad market/correlation tools by emphasizing the symbol anchor. The verb and output expectation are clear.

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 trigger phrases, including casual/multilingual questions, a 'When to call' statement, prerequisites, and next steps, which is strong guidance. It does not name alternatives or explicitly say when not to use this tool, so it stops short of 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is known. The description adds the critical caveat that data is paper-trading only (not real money) and notes the limit cap of 1000, which is useful behavioral context beyond the annotations. It doesn't repeat what annotations cover, and it doesn't contradict them. The extra disclosure about paper-trading justifies a 4.

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 headings: Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats. The purpose is front-loaded, and every section earns its place — even the trigger examples and next-step tools are useful for an agent deciding when to call and what to do after. There is no fluff, and the formatting aids scannability.

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 7 parameters, an output schema, and rich annotations, the description is complete: it covers the operation's purpose, usage contexts, prerequisites (none), follow-up tools, and caveats (paper-trading scope, limit cap). It doesn't need to explain return values because an output schema exists. The only minor gap is explicit differentiation from siblings, but that is not required for completeness given the clear purpose.

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% — every parameter (limit, symbol, max_pnl, min_pnl, market_id, hours_back, action_filter) has a detailed description, including defaults, aliases, and the stats_scope nuance. The tool description only summarizes filters ('action / P&L / time / symbol') and does not add meaning beyond the schema. Per the rubric, with high schema coverage the baseline is 3, and the description adds no extra parameter insight.

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 'Query paper-trading history with dynamic filters (action / P&L / time / symbol)', which clearly identifies the verb (query), resource (paper-trading history), and scope (filters). It does not explicitly differentiate from siblings like get_winning_trades or get_trade_outcomes_bulk, but the name and the filter list make its general-purpose nature evident. It could be a 5 with an explicit 'for specialized trade subsets, use X' note, so 4 is appropriate.

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 'When to call' section lists concrete scenarios (past trade review, single-symbol post-mortem, win-rate audits) and the 'Triggers' section provides natural-language examples that help an agent recognize user intents. It does not explicitly state when NOT to use this tool or point to alternatives like get_winning_trades, but the listed contexts are clear enough to guide selection. A 4 reflects strong guidance that stops short of explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, establishing safety. The description adds crucial behavioral context beyond annotations: linkage is temporal matching not a foreign key (with a pointer to meta.linkage), paper trading only, per-page disclaimer, and the pagination contract (follow next_cursor until has_more=false). 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?

The description is structured with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats, Output) that front-load the most important information and organize details efficiently. Every section adds value; there is no filler or redundancy. The use of section headers makes it scannable for an agent.

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 is unusually complete for a bulk-export tool: it covers purpose, triggers, usage context, prerequisites, next steps, caveats, and even a full output structure. With an output schema present, return-value documentation is optional, but the description still provides it. An agent has everything needed to invoke the tool correctly and interpret results.

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 provides 100% coverage with detailed descriptions for each parameter (days, limit, cursor, market). The tool description does not add additional semantics about these parameters beyond what the schema already offers; the schema itself explains defaults, bounds, and the cursor's role. Baseline 3 is appropriate given the schema's completeness.

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 precise purpose: 'Cursor-paginated bulk export of the prediction -> trade -> outcome chain.' It specifies what the tool returns (paper trades with realized P&L, linked to signal predictions) and explicitly names the sibling it is not ('For the prediction ledger itself use get_resolved_predictions'). This is a specific verb+resource with clear differentiation from siblings like get_trade_history and get_resolved_predictions.

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 includes an explicit 'When to call' section listing concrete scenarios (offline verification, periodic ingestion, auditing signal-to-outcome translation). It also states 'Prerequisites: none' and routes the user to get_resolved_predictions for the prediction ledger, directly addressing when not to use this tool. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds important non-obvious behavioral context: paper-trading data only, the P&L > 0 filter, and that this is a thin wrapper around another tool. This goes beyond what annotations and schema provide, though rate limits or auth are not mentioned, which is acceptable given the simple read-only nature.

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 organized with labeled sections and front-loads the core purpose. Trigger examples are useful but somewhat repetitive, including multilingual variants, which adds length without changing meaning. Still, every section earns its place and there is no fluff, so it remains concise.

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, read-only wrapper tool, the description covers purpose, triggers, when to call, prerequisites, caveats, and next steps. An output schema exists, so return-value details are not required. Nothing an agent needs to decide when to use this tool is missing.

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

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

Schema coverage is 100%: both limit and market_id have descriptions, defaults, and enum values. The description does not add parameter-level detail beyond mentioning the underlying min_pnl=0.01 threshold, which is not a parameter on this tool. With full schema coverage, 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 first line states exactly what the tool does: returns winning paper trades only (P&L > 0), and clarifies it is a convenience wrapper around get_trade_history(min_pnl=0.01). This precisely distinguishes it from siblings like get_losing_trades and get_trade_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 explicit trigger phrases ('what worked?', 'show me the winners'), a clear 'When to call: success-pattern review', and a next-step hint (analyze_trades). It does not explicitly state when NOT to call (e.g., use get_losing_trades for losses), but the positive-only framing and wrapper relationship make the usage context sufficiently clear.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds concrete behavior: the corpus is 'rebuilt at most every 10 minutes', empty results mean no match, and the output envelope includes disclaimer/is_investment_advice/data_classification. It also states that results are ids for `fetch`, clarifying the tool's role in a multi-step workflow.

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 labeled sections and front-loaded purpose. Most content earns its place, especially the caveats and next-step guidance. It is slightly verbose with some overlap between 'Triggers' and 'When to call', but the redundancy is mild and the labels make it easily parseable.

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 one-parameter search tool with rich annotations and an output schema, the description covers purpose, triggers, alternatives, prerequisites, next steps, freshness caveats, and result interpretation. Nothing an agent needs to decide whether to call it or how to interpret an empty result is missing.

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

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

Schema coverage is 100%, and the query parameter is already described as a free-text string supporting English/Korean and symbols like BTC/AAPL. The description adds context about what gets searched (tools, resources, signals) and gives example queries, but it does not materially expand the parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'discovery search over OneQAZ's live surface — tools, resources, and the latest strong combined signals across crypto / kr_stock / us_stock.' It also clarifies the return contract ('result ids consumable by the fetch tool') and distinguishes itself from sibling tools by positioning search as the entry point while fetch retrieves full documents.

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

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

The description explicitly says when to call it: 'first step of connector-style discovery' and 'keyword entry point when unsure which tool/resource to call.' It also names alternatives: MCP-native clients can 'browse tools/list + resources/list directly', and result ids should be passed to `fetch`. This gives an agent clear routing guidance.

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