OneQAZ Trading Intelligence

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 genuinely useful behavior beyond that: a 30-day cap and the fact that an empty result is returned when no trades fall in the window. It does not describe aggregation granularity or ordering, which keeps it from a 5.

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 (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) make it skimmable and purpose is front-loaded. The bilingual trigger list is bulky but functional; it is slightly longer than strictly needed.

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 handling return values and annotations handling safety, the description fills the remaining gaps: prerequisites, downstream signal feedback link, and the empty-window/30-day limits. Nothing an agent needs to invoke 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 coverage is 100% and both parameters are fully documented in the schema, including the days default/max and the market_id enum with aliases. The description restates the 30-day cap but adds no syntax or semantics beyond the schema, 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?

States a specific verb and resource plus the three grouping dimensions: 'Aggregate paper trades by day / pattern / symbol'. An agent can distinguish this from get_trade_history (raw rows) and the various position/accuracy siblings 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?

Provides explicit triggers (including colloquial phrasings), a 'when to call' section for pattern audits and period-over-period reviews, and a prerequisite routing to get_trade_history for raw rows. The condition selecting the alternative is stated, not inferred.

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 cover the read-only/idempotent/open-world profile, but the description adds meaningful context beyond them: the layered composition of the output and the caveat that results are research evidence, NOT a buy/sell recommendation. It also notes the symbol must match the per-symbol store filename (lowercase). Strong, though return-format detail is left to the output schema.

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

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

Front-loaded with Purpose and cleanly sectioned (Triggers, When to call, Prerequisites, Next steps, Caveats), so an agent can skim it. Slightly redundant: the Triggers list and the 'When to call' line restate the same condition, and 'Next steps: none' is low-value 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?

An output schema exists, so return values needn't be explained. Prerequisites, trigger phrasing, the symbol-format caveat, and the non-recommendation disclaimer together cover everything an agent needs to invoke this 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 both parameters (symbol, market_id enum) are already documented, establishing a baseline of 3. The description adds non-obvious meaning on top: symbol must match the per-symbol signal store filename and be lowercase, which the schema does not state.

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 (multi-layer explanation for a single symbol's recent research signal) and enumerates exactly what it combines: score_trace, Thompson + regime scores, and news causality context. An agent can distinguish it from siblings like get_signal_detail and get_latest_decisions without opening either 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?

Gives explicit when-to-call conditions, multilingual trigger phrases, prerequisites (identify the symbol via get_signals or get_latest_decisions first), and a next-steps declaration. The alternative routing is spelled out rather than inferred.

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, but the description adds real behavioral context beyond them: uncovered resource uris return description-only text with no fabricated data, and `text` is a JSON document for resource/signal ids. The only weak spot is that the output-envelope listing partly restates what the existing output schema already provides.

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?

Front-loaded with labeled sections (Purpose / Namespaces / Triggers / When to call / Prerequisites / Next steps / Caveats / Output), which makes it scannable despite its length. Some output-envelope detail duplicates structured data and could be trimmed, but nearly every line carries routing or behavioral value.

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

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

For a single-parameter fetch tool with an output schema and full annotations, the description covers purpose, id namespaces, triggers, prerequisites, follow-up tools, and data-fidelity caveats. Nothing an agent needs in order to 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning by explaining what each namespace's id actually resolves to (`tool:{name}` → full docs, `resource:{uri}` → live data, `signal:{market}:{symbol}` → latest combined signal) and notes core resources are resolved server-side.

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 (fetch document by id) and immediately distinguishes itself from the sibling `search` by noting it operates on search-result ids. It also enumerates the three id namespaces (`tool:`, `resource:`, `signal:`), so an agent can tell exactly what kind of document this returns 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?

Explicitly says when to call ('whenever the full content behind a search result id is needed'), who calls it (ChatGPT connectors / Deep Research after `search`), the alternative path for clients without MCP resource support, prerequisites (a valid id), and next steps (tools/call, get_signal_detail, explain_decision). This is a complete routing guide to sibling tools.

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

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

Annotations already declare readOnly/openWorld/idempotent, so safety is covered. The description adds real behavioral context on top: the 'outcome IS NULL' filter meaning, no prerequisites/auth needed, and 'returns most recent first' ordering. It does not describe result volume or pagination, keeping it short of a 5.

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?

Nicely front-loaded and labeled (Purpose/Triggers/When to call/Prerequisites/Next steps/Caveats). However, the promotional sentences ('Demonstrates that OneQAZ is actively publishing forecasts in real time', 'proves the system goes on record before outcomes are known (no cherry-picking)') sell the product rather than help selection, and the multilingual trigger list is bulky.

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 two-parameter read-only tool with an output schema, everything an agent needs is present: purpose, trigger conditions, prerequisites, ordering caveat, and a follow-up tool. Return values are covered by the output schema, so nothing material 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 parameters (limit, target_market with enum and alias handling) are fully documented in the schema itself. The description adds nothing about parameters, 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?

States a specific verb+resource and pins the exact semantics: 'Currently pending predictions (outcome IS NULL).' That definition implicitly and cleanly separates it from get_resolved_predictions and get_prediction_accuracy, so an agent can pick it without opening a 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?

Explicit 'When to call: to verify ongoing prediction activity', a 'Prerequisites: none' line, and a 'Next steps: get_prediction_accuracy' handoff. It gives clear context and routes onward, but never states a when-not or names get_resolved_predictions as the alternative for finished 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 readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuine context beyond that: the data is auto-tuned from real backtest outcomes, and the `last_backtest` timestamp signals tuning freshness, which tells the agent how to interpret staleness. This is meaningful behavioral disclosure.

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?

It is front-loaded with a clear Purpose and uses labeled sections (Triggers, When to call, Prerequisites, Next steps, Caveats) that make scanning easy. The bilingual trigger list is slightly verbose but serves a real matching function; overall it earns its space.

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

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

With an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies purpose, usage sequencing, prerequisites, and a freshness caveat, leaving nothing an agent needs 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 both optional filters (category, target_market) are fully documented in the schema, including the alias handling. The description adds no parameter-level detail beyond the schema, 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: it returns self-calibration evidence showing auto-tuned lag_hours and sensitivity per cell derived from real backtest outcomes. This distinguishes it from siblings like get_signal_calibration or get_structure_calibration, which are named separately in the ecosystem. An agent knows exactly what data this yields.

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 when-to-call ('after get_prediction_accuracy'), a prerequisite, and next steps ('get_monthly_accuracy_trend'). It even lists casual-question triggers in English and Korean, removing any ambiguity about when this tool applies 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 cover the safety profile (readOnly, idempotent, openWorld), so the bar is lower, and the description adds a genuinely useful caveat that correlation data may be empty until enough regime changes accumulate. It does not elaborate on pagination or response shaping, but the output schema exists to carry that.

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?

Clearly labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) with purpose and triggers front-loaded. The long list of multilingual trigger examples adds some bulk, but every section is functional rather than 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?

Given a read-only analytical tool with an output schema, full annotation coverage, and fully documented parameters, the description supplies the remaining context an agent needs: routing conditions, prerequisites, follow-on tool, and a data-availability caveat.

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 filters are documented in the schema including alias handling and case-insensitivity, so the description adds no parameter-level detail. Baseline 3 applies when the schema does the heavy lifting.

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 analytical resource (cross-market lead-lag relationships and decoupling events) with concrete examples of the signal ('BTC up while stocks down'). It explicitly distinguishes itself from the sibling get_macro_influence_map by scope (dynamic correlation vs. static causal hypotheses).

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 including multilingual casual phrasings, a 'when to call' condition (macro regime changes or divergent signals), stated prerequisites (none), and a named next step (get_macro_influence_map). Nothing is left to inference.

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 and purity profile is covered. The description adds genuine value with the caveat that the promoter cycle runs hourly, communicating data staleness. It does not describe pagination or exactly how transitions are computed, so it goes modestly beyond annotations rather than far.

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 front-loaded with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats), so an agent can scan it quickly. The dual-language trigger examples are useful for fuzzy matching but slightly inflate the length; every line still maps to a routing or behavioral decision.

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?

An output schema exists, so return values need no explanation, yet the description still names the status categories and the transition window. Combined with the explicit prerequisites, next-step routing, and freshness caveat, an agent has everything needed to call and interpret this zero-arg tool.

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

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

The tool takes zero parameters, so the baseline is 4 per the rubric. There are no parameter semantics to clarify and the description makes no misleading claims about 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?

States a specific verb+resource (feature governance snapshot) and enumerates the exact output taxonomy (OBSERVATION/CONDITIONAL/ACTIVE/DEPRECATED) plus the 7-day transition window. It also distinguishes itself from the sibling get_feature_governance_state, which is named as offering full per-feature lifecycle detail.

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 including casual/natural-language phrasings in two languages, a 'when to call' condition (trust evaluation, 'which features are live right now?'), a 'Prerequisites: none' note, and a 'Next steps' routing to the complementary state tool. Nothing about selection is left to inference.

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 only provide the read-only/idempotent safety profile; the description goes well beyond them by enumerating the content sections returned (headline claims, regime per interval, co-moving groups, members with signal bias, leads, gaps), noting that links carry evidence and sample sizes and hit rates, that empty sections are listed in gaps, and that it is not a quote/fundamentals/news source. This is rich behavioral disclosure that annotations cannot convey.

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

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

Four short sentences, front-loaded with the selection condition, then the payload, then the exclusions, then the quality caveats. The enumerations are dense but each clause adds distinct routing or expectation-setting information with no 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?

An output schema exists, yet the description still makes the shape of the answer predictable and covers negative scope (no real-time quotes, fundamentals, or full-text news) plus evidence-quality caveats. Nothing an agent needs in order to call or trust 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 description coverage is 100% and the schema already documents the group id format, the limit default/max, the market_id enum, and that question is analytics-only. The description adds no parameter-level meaning beyond that, so the baseline 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?

'Use when the question is about a sector, theme, ETF basket or index basket — its structure state and its members' states a specific resource and scope, and it explicitly names the sibling tools it is NOT for (get_symbol_context, get_market_context). An agent can route to it without opening any 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?

Gives an explicit trigger condition (sector/theme/ETF/index basket questions), names both excluded cases (single stock, whole market) and names the alternative tool for each. Nothing about when to select this tool is left to inference.

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/openWorldHint, and the description adds genuinely new context: it discloses the critical caveat that these are paper-trading decisions only with no real-money order routing, plus a recommended prerequisite resource for context. Return-format detail is omitted, but the output schema covers it.

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

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

Front-loads purpose and uses labeled sections (Purpose/Triggers/When to call/Prerequisites/Next steps/Caveats), which is easy to scan. The trigger list is long and somewhat repetitive, but each entry earns its place by mapping real user phrasing to this tool.

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

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

With a full input schema, an output schema, and annotations, the description completes the picture by adding track differentiation, prerequisites, next steps, and the paper-trading caveat. Only minor gaps (e.g., ordering/pagination behavior of the log) remain.

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

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

Schema description coverage is 100% and all four parameters (market_id, limit, hours_back, decision_filter) are already documented in the schema. The description references market_id only indirectly via the status URI and adds no format or syntax beyond the schema, so 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?

States a specific verb+resource (decision log) and scopes it precisely as 'Track-B (signal-driven)' while explicitly differentiating from the sibling get_llm_trading_decisions ('Track A = the LLM judgement path'). An agent can disambiguate the two tracking paths without opening a 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?

Provides concrete triggers (including casual/non-English phrasings), a 'When to call' statement, a prerequisite (market://{market_id}/status), and next-step tools (get_trade_history, get_signals). This is explicit when-to-use plus 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 cover read-only/idempotent/open-world, and the description adds genuinely non-obvious behavior on top: the chain inception date (2026-03-22), that hashes are computed once a day closes in UTC, and that entries are append-only at the serving-role level. It also explains the prev_chain_hash commitment model, which explains why re-anchoring matters — context no annotation conveys.

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?

Front-loaded with a labeled Purpose line and organized into Triggers/When/Prerequisites/Next steps/Caveats/Output sections, so an agent can scan quickly. It is somewhat over-stuffed — the duplicated multilingual trigger list and the Output block restate the output schema field-by-field — costing some economy.

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?

An output schema exists, so the description need not detail returns, yet it still supplies the edge cases an agent needs: chain start date, UTC daily closure, append-only semantics, and a verification hint. Nothing required to invoke or interpret this 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 coverage is 100% and the single parameter ('days', max 400) is fully documented in the schema itself. The prose never elaborates on the parameter's meaning or default behavior, so the description adds nothing beyond what the schema already provides — the baseline 3 for a fully-covered single-param tool.

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 ('tamper-evidence for the prediction ledger') and defines the mechanism precisely — a daily SHA-256 hash chain over created/resolved prediction rows with a published canonical recipe. It is clearly distinguishable from siblings like get_resolved_predictions, which is framed as the raw-data counterpart rather than the integrity check.

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 multilingual phrasings), names the condition for calling ('FIRST STEP of any serious credibility audit'), states prerequisites ('none'), and routes to next steps ('get_resolved_predictions'). This is textbook when/when-not/alternatives 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 readOnly/idempotent/openWorld, so safety is covered; the description adds genuinely non-obvious context — that the LLM output is applied only as a capped bias on top of engine signals, and that this is paper-trading only. It does not discuss volume, ordering, or rate limits, but the conceptual framing is a real addition.

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 (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) make it skimmable and the core purpose is front-loaded. The bilingual trigger list is slightly bulky but earns its place by improving intent 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?

An output schema exists so return values need not be described, and annotations cover the safety profile. Given prerequisites, next steps, caveats, and the Track A/B distinction are all present, nothing an agent needs to 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 coverage is 100%, including enum values and alias handling for market_id and optionality for symbol, so the schema already carries parameter meaning. The description adds nothing about parameter syntax or defaults; 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 resource and scope: the Track-A LLM-driven paper-trading judgement log, and explicitly defines Track A versus Track B. It names the sibling that covers the other track (get_latest_decisions), so an agent can distinguish the two without opening 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?

Provides explicit triggers (including casual phrasings in English and Korean), a 'When to call' line, 'Prerequisites: none', and a 'Next steps' pointer to get_latest_decisions for Track B comparison. Both when-to-use and the alternative are spelled out.

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, so the safety profile is covered. The description adds genuinely new behavior: the ROI<0 threshold definition, the 'paper-trading data only' caveat, and the wrapper relationship to get_positions. It stops short of describing result ordering or pagination.

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?

Clearly front-loaded with purpose first, then triggers, prerequisites, next steps, and caveats as scannable labeled sections. The multilingual trigger list is somewhat long but each entry maps to a real query pattern, so it earns its space.

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

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

With an output schema present, return values need no explanation, and the description covers purpose, scope, usage context, prerequisites, downstream tools, and the paper-trading data limitation. Nothing needed to 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 coverage is 100% and both parameters (market_id with enum and aliases, limit with default) are documented in the schema itself. The description adds a max_roi=-0.01 detail, but that parameter is not part of the exposed input schema, so it contributes little to invocation semantics. 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?

States a specific verb+resource and defines the exact scope ('Losing paper positions (ROI < 0)'), then anchors it against a sibling by naming get_positions(max_roi=-0.01) as the underlying call. An agent can distinguish it from get_losing_trades, get_profitable_positions, and get_positions without opening any 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?

Provides explicit triggers including casual and non-English phrasings, a when-to-call context (drawdown / risk review), prerequisites, and next steps. The one gap is that it never contrasts 'positions' against the similarly named get_losing_trades sibling, which is the most likely mis-selection.

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

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

Annotations already cover read-only/idempotent/open-world, so the description's job is to add behavior beyond that. It does: the 'paper-trading data only' caveat and the underlying max_pnl=-0.01 filter semantics are genuinely useful context not derivable from annotations. It stops short of describing pagination or result shape, hence not a 5.

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?

Front-loaded with Purpose and organized under clear labels (Triggers, When to call, Prerequisites, Next steps, Caveats), so the agent can scan efficiently. The multilingual trigger list is somewhat verbose but serves a routing purpose; overall tight.

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 read-only annotations, the description needn't explain return values, and it doesn't. It supplies everything needed for correct invocation: scope, prerequisites (none), the sibling to prefer for unfiltered history, and the data caveat.

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 only 2 parameters (limit, market_id), so the schema already fully documents them. The description adds no syntax or format detail beyond the schema, and the max_pnl value it mentions is an internal wrapper detail, not a callable parameter. 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?

States a specific verb (get/list), resource (losing trades), and precise scope (P&L < 0, paper only), and names the sibling it wraps (get_trade_history). An agent can distinguish it from get_winning_trades and get_trade_history without reading either 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?

Explicit 'When to call: failure-pattern review', a concrete wrapper alternative (get_trade_history(max_pnl=-0.01)), and a named next step (analyze_trades). Sample trigger phrases including casual/non-English questions further remove ambiguity about when it applies.

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 real behavioral context beyond that: Pearson-based methodology, a >=30-sample requirement, and a p<0.05 significance filter. It stops short of explaining behavior when sample counts are insufficient or what changing the thresholds does to 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?

Explicitly labeled sections (Purpose / Triggers / When to call / Prerequisites / Next steps / Caveats) make it front-loaded and scannable. The bilingual trigger list is slightly long but every entry aids routing, so little 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?

With an output schema present, return values need not be described, and the annotations carry the safety profile. Given that, the description covers purpose, invocation triggers, prerequisites, follow-up routing, and statistical caveats — nothing an agent needs to 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 both params carry inline descriptions with defaults, so baseline is 3. The description's mention of a 'p < 0.05 filter' loosely maps to max_p_value but adds no syntax, range, or interaction guidance beyond the schema.

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

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

States a specific verb+resource with scope: a 'lag-aware causal graph between macro categories', enumerates the categories, and pins down the output as 'statistically significant lead-lag pairs' with a concrete example (forex -> vix 7d rho=-0.41). This is clearly distinguishable from correlation siblings like get_cross_market_correlation and get_sector_correlations_tool by the lead-lag/directional framing.

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 including casual phrasings in two languages, a 'When to call' condition ('assess pre-emptive cross-category impact after a macro event'), 'Prerequisites: none', and a routing pointer to get_macro_influence_map as the next step. When, why, and where-to-go-next are all covered without inference.

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 only cover read-only/idempotent/open-world safety, so the description carries real behavioral load here and does: it warns that top-level values are static priors while the `effective` block reflects backtest_tuning when the tuning gate passes, and notes meta.effective_status reports lookup failures. That is genuine engine-behavior disclosure 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?

Front-loaded with 'Purpose:' then organized into Triggers / When to call / Prerequisites / Next steps / Caveats, so an agent can skim to the relevant block. Mildly verbose with the bilingual trigger list, but each section carries distinct information.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile; the description still supplies the interpretive key (priors vs effective block) that an agent needs to cite results correctly. Coverage of the sibling differentiation would make it complete.

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

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

Schema description coverage is 100% and the single market_id parameter is fully documented in the schema (including alias and case handling), so the baseline is 3. The description adds nothing about the optional market filter.

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 and its structure: 'pre-defined causal hypothesis map' with macro categories mapped to target markets via lag_hours + sensitivity, plus an `effective` block. Clear enough that an agent knows what it will get. However, it never distinguishes itself from the sibling get_macro_causality_graph_tool, which sounds like an adjacent causal-map resource.

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

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

Gives explicit triggers including multilingual casual phrasings ('how do rates affect crypto?', '금리가 코인에 어떻게 영향 줘?') and a 'When to call' clause (understanding WHY predictions are made), plus a next-step pointer to get_backtest_tuning_state. No exclusion guidance versus the causality-graph sibling, which is the one gap.

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=false, so the safety profile is covered. The description adds behavioral context beyond that: it reports sample sizes and measured hit rates, states that every link carries its evidence, and that every empty section appears in gaps. That is meaningful non-obvious behavior disclosure, though it does not discuss auth, limits, or freshness.

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?

It is front-loaded with a single usage sentence followed by a payload inventory, with essentially no filler. The payload enumeration is dense and long, but each clause adds information rather than repeating the name, so it remains efficient.

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

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

For a read-only market context tool with an output schema covering return structure, the description supplies the usage routing, payload overview, evidence/confidence disclosure, and gaps behavior that an agent needs to select it correctly. It does not cover pagination interaction with the limit parameter or freshness, minor gaps given a read-only, idempotent tool with an output schema.

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 all three parameters are documented in the schema itself, including the market word list and the limit default/max. The description adds the market group naming (KR, US, CRYPTO) but no syntax or format detail beyond the schema, so it sits at 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 specific verb-resource pair ('whole market ... structure regime and how its groups are positioned') and explicitly names the sibling alternatives it is not (get_group_context, get_symbol_context). It also enumerates the concrete return payload (headline claims, structure and macro regime, tuned lags, groups ordered by distance, news, gaps), leaving no ambiguity about what the tool produces.

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 specifies when to use it ('when the question is about a whole market (KR, US, CRYPTO)') and when not to ('Not for one sector or stock — use get_group_context or get_symbol_context'), and it further rules out real-time quotes, fundamentals, and full-text news as sources. Both sides of the routing decision are given explicitly with named 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 cover readOnlyHint/openWorldHint/idempotentHint, so the safety profile is handled. The description adds genuinely non-obvious behavior: it excludes the 'all' month aggregate and returns empty when backtest_results is unpopulated, both of which affect interpretation of 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?

Purpose is front-loaded and the block structure (Triggers/When/Prerequisites/Next/Caveats) makes it scannable. The bilingual trigger list is slightly long but each entry serves routing rather than padding.

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?

An output schema exists so return shape need not be described, and the prerequisites, next-steps, and caveats close the remaining gaps. An agent has everything needed to call this correctly and interpret an empty response.

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

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

Schema coverage is 100% and the schema itself documents both filters and the alias/case behavior. The description's mention of 'lag_bucket' describes output grain rather than a filterable parameter, so it adds only marginal meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific resource and grain: a monthly accuracy time series keyed by (category, target_market, lag_bucket), with the intent 'verify sustained performance and detect recent degradation.' This clearly separates it from the point-in-time get_prediction_accuracy sibling.

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

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

It gives explicit prerequisites ('after get_prediction_accuracy and get_backtest_tuning_state'), states it 'completes the trust chain,' and lists concrete trigger phrases including casual natural-language questions in two languages. Nothing about when to select this tool is left to inference.

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 cover read-only/idempotent/open-world safety, so the bar is lower; the description nonetheless adds substantive behavioral context: the labels are unvalidated pipeline heuristics, the methodology is under audit, and the window is limited to recent days. That is exactly the kind of caveat an agent cannot get from 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?

Front-loads the unverified disclaimer, then organizes content into Purpose/Triggers/When/Prerequisites/Next steps/Caveats. Sections earn their place, though the bilingual trigger list and repeated non-predictive warnings add slight 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?

An output schema exists so return values need no explanation, and the description covers scope, caveats, and the follow-up resource. Complete enough for an agent to call it correctly; only a sibling-level routing statement 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 both parameters are documented in the schema, including the enum and default. The description adds no parameter-level detail beyond that, 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?

States a specific verb+resource ('counts of news items per internal label the pipeline assigns') and defines the three labels, which is meaningfully more than a restatement of the title. It does not name a sibling tool to contrast against, relying instead on a resource URI for the follow-up.

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', sample triggers, 'Prerequisites: none', and a next step, plus an exclusion ('does NOT establish that the market did or did not see an event coming'). Lacks a direct contrast with a sibling tool, which would be needed for 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 readOnly/idempotent/openWorld, but the description adds substantial non-structured context: the metrics are deliberately withheld pending a methodology audit, the result is empty when no news events were processed in the recent window, and sample counts are coverage figures that confer no statistical validity. These are exactly the caveats an agent needs to avoid misreporting output.

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 labeled sections (Purpose/Triggers/When to call/Prerequisites/Next steps/Caveats) are easy to scan and the most important warning — UNVERIFIED, do not cite — is front-loaded. It is slightly verbose and repeats the 'no statistical validity' point in both the caveat and the schema, but nothing 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?

An output schema exists, so return values need no explanation, and the description still covers scope, triggers, exclusions, prerequisites, the sibling handoff, and the empty-result condition. An agent has everything needed to call this correctly and interpret the response honestly.

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 all three parameters (market_id, target_market alias, min_sample_count) are documented in the schema itself, including aliases and the 'coverage filter only' caveat. The description adds no parameter-level meaning beyond that, 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?

States a specific verb+resource: an inventory of the news pipeline's (event_type, news_type) groupings per market with sample counts. It also explicitly corrects a likely misconception from the tool name — the lead/score metrics are withheld — and points to get_news_causality_breakdown as the adjacent tool, so the agent can distinguish it from siblings 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?

Provides concrete triggers ('what news event groupings does OneQAZ track?', 'how many news samples per event type?'), an explicit when-to-call, an explicit when-NOT ('does NOT answer questions about predicting or anticipating news'), prerequisites, and a named next step. This is the full when/when-not/alternative pattern.

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 only declare read-only/idempotent/open-world, but the description adds substantial non-obvious behavior: a synthetic fixed-book capital model (400 slots, anchor 2026-06-16), the hard no-data error for account_type='live', and the rule that paper and live curves are never concatenated. The fixed-window determinism guarantee is also disclosed, which is genuinely useful context an agent cannot infer from 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?

Clearly front-loaded and labeled (Purpose / Triggers / When to call / Prerequisites / Next steps / Caveats), so the agent can scan quickly. It is somewhat long due to the multilingual trigger list, but every section carries actionable content, so it stays just short of ideal brevity.

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 not be explained; the description still covers prerequisites, caveats, the required-parameter failure mode, and routing to adjacent tools. Nothing material is missing for an agent to 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the fixed-window semantics that govern window_start/window_end and reinforces that account_type is REQUIRED with a hard-failure behavior for 'live'. These are semantic nuances not fully captured by the schema field descriptions.

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

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

States a specific verb+resource ('Portfolio-level performance metrics') and enumerates the exact metrics returned (MDD / Sharpe / Sortino / Calmar / monthly returns / equity curve) over a fixed window. It also positions itself as 'the single canonical computation path,' which distinguishes it from sibling breakdown tools like analyze_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?

Provides explicit 'When to call' contexts (track-record verification, blog cross-checks, risk review), a trigger list including casual/multilingual phrasings, prerequisites ('none'), and named next-step alternatives (get_trade_history, analyze_trades). The agent knows exactly when this tool is the right pick versus its siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered structurally. The description adds real behavioral context beyond them by stating it returns an error envelope when no position exists for the symbol, which tells the agent to expect a failure path rather than empty 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?

Labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) front-load the essential meaning and are easy to scan. The multilingual trigger examples add length but earn their place by improving intent 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 one-ticker read tool with an output schema and read-only annotations, the description supplies everything the agent still needs: what is returned, the pre-check step, follow-on tools, and the no-position error case.

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 coin/symbol/market_id and the enum aliases are already documented in the schema; the baseline of 3 applies. The description adds only an indirect hint that the tool is keyed to a single ticker, with no extra syntax or format guidance for market_id.

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 names a specific verb-scoped resource: a per-symbol position 'deep-dive' returning position, recent trades, and decisions. This distinguishes it cleanly from get_positions (list) and get_trade_history / get_latest_decisions, which return only one slice of that data.

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

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

Explicitly gives triggers including casual utterances ('why are you holding X?'), the selection condition ('full context for one ticker'), a prerequisite (confirm the position exists via get_positions), and follow-on tools (get_signal_detail, get_role_analysis). Nothing about when to use it versus alternatives is left 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 cover read-only, idempotent, open-world semantics, so the safety profile is known. The description adds genuinely useful non-schema context: the data is paper-trading only (stated twice), market status is recommended for context, and downstream tools are named. Pagination and stats_scope caveats live only in the schema, not the 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?

Labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats) keep it front-loaded and skimmable, with the core purpose in the first sentence. The six-item trigger list is slightly padded, but each item demonstrates a distinct query shape rather than restating the name.

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, and the description correctly focuses on scope, prerequisites, and follow-ups. The gaps that remain — pagination/truncation and the stats aggregation scope — are already handled in the schema, so little 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 description coverage is 100%, so the schema already documents limit, ROI bounds, sort fields, strategy, market_id aliases, and the important stats_scope caveat. The description only gestures at 'dynamic filters (ROI / strategy / sort)' without adding syntax or semantics beyond the schema, which is the baseline-3 case.

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 ('List current paper-trading positions') and enumerates the filter dimensions (ROI / strategy / sort). The paper-trading scope is repeated emphatically, which cleanly separates it from real-money tools. It does not, however, differentiate itself from close siblings like get_profitable_positions or get_losing_positions, which appear to be specializations of the min_roi/max_roi filters offered here.

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 conditions ('position dashboards, drawdown checks, exposure audits') plus a list of natural-language phrasings, including a Korean example, which is unusually concrete for routing. Prerequisites (market status) and next steps (get_position_detail, get_strategy_distribution) are named. It lacks an explicit 'use X instead when...' exclusion against the filtered sibling tools.

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

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

Beyond the readOnly/idempotent annotations, it discloses a critical behavioral caveat: raw accuracy overstates alpha because regimes are sticky, so skill_ci_95 and n_effective must be used. It also flags the 2026-07-08 methodology cutover and warns that monthly trends track stickiness rather than model improvement.

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?

Front-loaded with purpose, then cleanly sectioned into Triggers/When to call/Prerequisites/Next steps/Caveats. It is verbose, and some trigger examples overlap, but each block carries actionable routing or caveat information rather than 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?

With an output schema present the description needn't explain return values, yet it names the key fields and their interpretation. Combined with prerequisites, caveats, and sibling routing, an agent has everything needed 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%, so both parameters (category, target_market) are already fully documented in the schema, including aliases and enums. The description mentions only 'filter horizon_type=forecast' as a judgment rule, adding no filter syntax beyond what the schema 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 states a specific verb+resource (per-cell hit rates with baselines) and enumerates exactly which metrics it returns (persistence_accuracy, skill_score, n_effective, accuracy_v2_only). It clearly distinguishes itself from siblings like get_monthly_accuracy_trend and get_signal_calibration via the 'Next steps' routing.

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 an explicit 'When to call' directive ('should call this FIRST'), lists casual trigger questions in English and Korean, states 'Prerequisites: none', and names four specific alternative/next tools with their distinct roles. Nothing about tool selection is left to inference.

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 real context beyond that: the ROI > 0 threshold semantics, the wrapper relationship to get_positions, and the 'paper-trading data only' caveat. It stops short of describing return shape or pagination, which keeps it from a 5.

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?

It is labeled and front-loaded (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats), which makes it scannable. However, the bilingual casual-trigger list is longer than needed; a couple of examples would carry the same meaning with less bulk.

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 the safety/read profile, the description supplies everything else an agent needs: what counts as profitable, that it is paper-only, that it wraps get_positions, and where to go for detail. Nothing material 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 parameters (market_id enum, limit) are fully documented in the schema, so the baseline is 3. The description only gestures at parameterization through the min_roi=0.01 reference and adds no syntax beyond the schema.

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

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

The description states a specific verb+resource ('Profitable paper positions') and pins the scope precisely with 'ROI > 0'. It also distinguishes itself from the sibling get_positions by defining itself as a 'Convenience wrapper around get_positions(min_roi=0.01)', so an agent can tell the two apart without opening 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?

It gives explicit 'When to call' guidance ('quickly surface winning tickers'), samples of casual triggers, a 'Prerequisites: none' note, and a 'Next steps' pointer to get_position_detail. The alternative (get_positions with min_roi) is named, so both the when and the routing are covered.

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, so the safety profile is covered. The description adds genuinely useful behavior the annotations don't: id-ordered cursor pagination requiring next_cursor to bulk-read, and a disclaimer that these are paper-research forecasts, not advice. It does not cover rate limits or error behavior, so it stops short of a 5.

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?

Purpose is front-loaded and labeled sections (Triggers, When to call, Caveats) make it scannable. However, the 'Output' block restates the return shape that the output schema already defines, which is redundant length; the definition is slightly over-long.

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 this tool the description supplies prerequisites, pagination caveats, sibling relationships, and follow-up steps; given an output schema exists, return values needn't be explained, though they are. Nothing an agent needs to invoke 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 all six parameters including defaults and the enum. The description only indirectly touches parameters via the pagination caveat ('id-ordered, follow next_cursor'), adding little beyond structured data. 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 names a specific resource (row-level macro regime prediction ledger) and its full lifecycle, and explicitly differentiates it from the aggregate sibling get_prediction_accuracy. An agent can distinguish it from get_active_predictions and get_prediction_accuracy without opening any 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?

Provides an explicit 'When to call' list (credibility evaluation after get_prediction_accuracy, backtesting, archiving), states 'Prerequisites: none', and names next steps (get_ledger_integrity). It routes the agent to the correct alternative and the correct follow-up.

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/openWorldHint, so safety is covered. The description adds genuine behavioral context: results are based on hierarchy_context and can be empty under collector lag, and it points to a downstream resource and get_position_detail. This goes beyond what the annotations provide.

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

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

Front-loaded 'Purpose' followed by clearly labeled Triggers/When to call/Prerequisites/Next steps/Caveats sections make it scannable. The long list of multilingual trigger examples is slightly verbose but earns its place by aiding intent 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?

With an output schema present, return values need not be described, and the description still covers purpose, invocation triggers, prerequisites, follow-ups, and the key failure mode (empty hierarchy_context). Nothing an agent needs to call 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 symbol/coin/market_id (including the coin legacy alias and market alias handling) are already documented in the schema. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema carries the load.

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

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

States a specific operation (role-aware signal alignment per symbol) across named roles (timing/trend/swing/regime) plus hierarchy alignment, which is more than a restatement of the title. It is distinguishable from siblings like get_signal_detail or get_signals by its multi-timeframe/cross-role framing, though it never explicitly names those siblings as alternatives.

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' conditions, concrete trigger phrasings (including casual and multilingual questions), a prerequisite (get_signal_detail), and named next steps. An agent has clear routing signals to select this over adjacent tools.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered; the description adds genuinely useful non-structured context with data freshness ('refreshed every 6 hours') and scope ('60-day lookback'). These constrain how an agent should interpret the result, though response/pagination behavior is left to the output schema.

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

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

Well front-loaded with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats). Slightly padded by the bilingual trigger examples, but that length serves trigger matching rather than being waste.

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 two-parameter read tool with a rich output schema, the definition covers purpose, usage triggers, prerequisites, freshness caveats, and a next-step handoff. Nothing an agent needs to select or invoke it correctly is missing, and return values are legitimately delegated to the output schema.

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 parameters (top_k, market_id with enum + aliases) are fully documented in the schema. The description adds no syntax, defaults, or semantic nuance beyond the schema, so 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?

States a specific resource and scope: 'Intra-market ETF / group correlation matrix and auto-cluster output', explicitly quantifying structural co-movement with a concrete example (ARKK <-> QQQ). The 'intra-market' framing implicitly separates it from the sibling get_cross_market_correlation, so an agent can place it without opening either 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?

Gives an explicit 'When to call' (portfolio diversification or sector concentration audits), trigger phrasings, prerequisites ('none'), and a next step routing to get_symbol_peer_links_tool. It lacks an explicit negative case (e.g. 'for cross-market, use get_cross_market_correlation instead'), which keeps it just below 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 only cover readOnly/idempotent/openWorld; the description adds substantial behavior the agent could not otherwise know: daily per-market snapshot with stale flags, the observation-window field, a 30-minute judgment horizon, nominal n with correlated-trial caveat, and quality.status values (withheld/degenerate/non_monotone) that gate whether a cell may be cited.

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?

Front-loads purpose, then uses labeled sections (Triggers, When to call, Prerequisites, Next steps, Caveats) so an agent can scan to the relevant part. The Caveats block is a dense run-on, but each clause carries operational weight rather than 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?

An output schema exists, so return-value explanation is unnecessary; the description instead supplies the interpretive context the schema cannot (which field to cite, which quality statuses disqualify a cell). Nothing needed to call or correctly interpret the 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 description coverage is 100% and the variant/interval/market_id semantics (including v1 vs v2 and accumulation date) are already documented in the schema. The description adds no parameter-level syntax or default guidance beyond what structured fields provide, 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?

States a specific resource (reliability diagram data for Level-1 signal confidence), the exact output shape (realized hit rate per confidence bucket with ECE summary), and the agent-facing question it answers ('verify whether a 0.9-confidence signal actually hits ~90%'). This clearly separates it from siblings like get_signals (raw values) and get_structure_calibration (a different layer).

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

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

Explicit 'When to call: before trusting get_signals confidence values as probabilities,' plus 'Prerequisites: none' and 'Next steps: get_prediction_accuracy, get_signals.' Casual-language triggers are also enumerated, removing inference from the routing decision.

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 profile is covered. The description adds genuinely new context by disclosing that the tool queries both the per-symbol signal store and the paper-trading store, though it says nothing about result size or latency.

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?

Front-loaded with a one-line purpose, then labeled sections (Triggers, When to call, Prerequisites, Next steps, Caveats) that are easy to scan. The multilingual trigger examples are somewhat long but each maps to a real disambiguation case, so little 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?

With an output schema present, the description needn't explain return values; it instead covers intent, prerequisite sequencing, follow-up tools, and the dual data-store caveat. An agent has everything needed to call this 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 enums on interval and market_id, so the schema already documents symbol/coin/interval/market_id semantics including aliases. The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 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 — a per-symbol 'signal deep-dive' returning latest signal, history, and feedback. It clearly distinguishes itself from the sibling get_signals, which is the list/scan tool, so an agent can route correctly without opening 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?

Explicit 'When to call', prerequisites (confirm existence via get_signals first), and next steps (get_role_analysis, get_position_detail). Casual-question triggers in both English and Korean further pin down intent, leaving nothing to inference.

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 only declare read-only/open-world/idempotent, but the description adds substantial behavior an agent cannot get elsewhere: omitted-symbol semantics (whole-market scan, 2 newest rows per symbol), result capping with `truncated`/`truncated_note` to check, `common` hoisting with row-level precedence, `warnings` omission-when-empty, and `reason_uncalibrated` handling. It also warns the output is research, not advice/order, and to surface the disclaimer.

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?

Front-loaded with 'Purpose:' and clearly labeled Trigger/When/Prerequisites/Next steps/Caveats sections, so navigation is easy. The trigger list is dense and somewhat verbose, but the length is largely justified by 9 parameters, nested response behavior, and an output schema with non-obvious semantics.

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

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

Given an output schema exists, the description need not document return fields, yet it still explains the response's non-obvious envelope (`common`, `warnings`, `truncated`, `reason_uncalibrated`). Combined with prerequisites, next steps, and the advice disclaimer, nothing an agent needs to call or interpret this 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 coverage is 100%, so the baseline is 3. The description goes beyond by explaining the behavioral consequence of omitting `symbol`/`coin` (legacy alias) and the scan/cap semantics, which the per-parameter schema strings do not convey. Minor gap: no added guidance on `limit` beyond clamping, already stated in schema.

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

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

Opens with a specific verb+resource+filter set ('Query research signals with dynamic filters (symbol / interval / action / score / confidence)') and explicitly differentiates roles by naming get_latest_decisions, get_signal_detail, and get_role_analysis as follow-ons. An agent can tell this apart from the many signal/decision siblings without opening any 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?

Provides explicit triggers including natural-language examples, a dedicated 'When to call' section ('drilling into a specific signal slice; symbol-by-symbol scanning'), a prerequisite for the global view, and next-step tools. When-to-use and how-it-relates-to-alternatives are both covered.

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 safe/lookup profile is covered. The description adds a genuine behavioral caveat beyond the annotations: an empty distribution when no positions are open, plus dependency guidance. It stops short of describing pagination or aggregation window, hence a 4 rather than 5.

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?

Clearly labeled sections with Purpose front-loaded, so an agent can scan it quickly. The five-example trigger list (bilingual) is somewhat verbose, but each example plausibly improves trigger matching, so the length is largely earned.

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, no return-value explanation is needed, and the annotations cover safety. The description supplies the remaining gaps for a read-only aggregation tool: prerequisites, follow-up resources, and the empty-result edge case.

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 there is a single enumerated market_id parameter, so the schema already carries the semantics (including alias handling). The description adds nothing further about the parameter, which is the expected baseline-3 outcome when the schema does the work.

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 verb and resource ('per-strategy breakdown') with explicit scope ('across current paper positions') and names the three returned metrics (count, avg P&L, win rate). The 'current positions' qualifier cleanly separates it from structured siblings like get_strategy_leaderboard and get_performance_metrics.

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 (including casual question phrasing), a 'when to call' clause (diversification audit, per-strategy performance check), a prerequisite (get_positions for raw rows), and next steps (strategy-fitness resource, signals/feedback). Routing logic is fully spelled out rather than inferred.

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?

Goes well beyond the readOnly/openWorld/idempotent annotations by disclosing data-quality caveats: the GLOBAL pool may contain synthesized win_rate values, per_symbol_leaderboard is the primary measured-edge surface, min_trades enforces statistical validity, and results are paper-tested rather than real-money executed. This is exactly the kind of trust-relevant context annotations cannot carry.

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?

Front-loaded Purpose sentence, then labeled sections (Triggers, When to call, Prerequisites, Next steps, Caveats), which makes it scannable. The multi-lingual trigger list is somewhat verbose, but every line carries usable routing or caveat information.

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

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

For a read-only ranked-list tool with an output schema, the description supplies purpose, scope split, usage triggers, prerequisites, next-step routing, and trust caveats. Nothing an agent needs to call it correctly is missing, and return-value detail is appropriately delegated to the output schema.

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, but the description adds semantic weight by framing min_trades as a statistical-validity guard and include_per_symbol as selecting the primary measured-edge surface. It does not explain the alias pairs (limit/top_n, market_id/target_market) beyond what the schema already says.

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 ('Top RL-learned research strategies') and precisely delineates scope (GLOBAL pool vs per-symbol partition, Layer E evidence tier). An agent can tell what surface it returns. It does not, however, name or contrast itself with the closest sibling get_strategy_distribution, so sibling differentiation is implicit rather than 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?

Explicitly gives 'When to call' (final trust-validation step), 'Prerequisites' (none), and 'Next steps' routing to market://{market_id}/signals/summary. It even supplies natural-language triggers including Korean, which directly helps intent matching against siblings.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint), and the description usefully adds non-obvious behavior: results are empty until structure-learning cycles complete, rows are paginated so callers must read total_available rather than len(), and baseline/meta counts remain whole-set. It also discloses an interpretive caveat (measured skill is negative as of a stated date), which goes beyond annotations. It stops short of exactly how hit_rate_ema is computed, but the coverage is 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?

Front-loaded with "Purpose", then cleanly sectioned into Triggers / When to call / Prerequisites / Next steps / Caveats, so an agent can scan to the needed part. It is on the long side and some inline bolding/scaffolding is decorative rather than informative, but almost every sentence carries real guidance.

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?

An output schema exists so return structure need not be described, yet the description still supplies the interpretive frame an agent needs (baseline required to read hit rates, negative skill disclaimer, whole-set vs truncated fields). Given three optional params and a read-only tool, nothing required for a correct call 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 baseline is 3, but the description earns extra by clarifying the truncation semantics that govern `limit` — rows get truncated while `baseline`, `meta.total_entries` and `meta.total_samples` stay whole-set, and dimension keys are never hoisted out of rows. That is meaning beyond the per-field schema text.

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 verb+resource (prediction calibration) and pins down its granularity tier (Level 2 = ETF/basket/sector, versus Level 1 individual symbols), then names the exact metric returned (hit_rate_ema per market/group/interval/regime_bucket with sample counts and baseline). This is enough to separate it from siblings like get_signal_calibration or get_structure_validation_history without opening a 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?

Explicitly says when to call ("when an AI wants to see Layer D evidence"), supplies real example trigger phrasings in two languages, states prerequisites (none), and routes the agent forward to a specific sibling tool (get_structure_validation_history) for the daily trend. This is a complete when/how/when-not routing section.

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 and repeatability profile is covered. The description adds a scoping caveat (the window includes an overall_hit_rate summary) and the daily-row shape, but discloses nothing about auth needs, latency, or data-freshness behavior beyond that.

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 labeled sections (Purpose / Triggers / When to call / Prerequisites / Next steps / Caveats) are front-loaded and scannable. The trigger list is long, but it earns its place by enabling intent matching against casual queries; only slight verbosity keeps it from 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 an output schema present, the description need not explain return values, and it still covers prerequisites, next steps, caveats, and routing context. For a read-only history tool, an agent has everything needed to select and 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%, and both parameters (days, market_id) carry their own descriptions including the alias handling. The description implies a lookback window ('over the window') but adds no syntax or constraint detail beyond the schema, so the baseline 3 holds.

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 ('Daily validation history of Level 2 structure predictions') and even disambiguates the domain term ('Level 2 = ETF / basket / sector granularity'). It tells the agent what each row contains (hit_rate per day), making it clearly distinguishable from siblings like get_performance_metrics or get_prediction_accuracy.

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: after get_structure_calibration' and 'Next steps: get_monthly_accuracy_trend for the macro-level comparison', routing the agent to alternatives by condition. The Triggers block with casual and multilingual questions further pins down when it applies.

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, it discloses the response ordering (headline claims first), the section inventory including 'gaps' for untracked items, and that links carry sample sizes, measured hit rates and evidence. It also states negative capability boundaries — not a real-time quote, fundamentals, or full-text news source — which is behavioral context annotations cannot convey.

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?

It is front-loaded with the usage trigger, then the return shape, then the exclusions, which is the correct order. The single dense paragraph packs a lot, and a couple of clauses (the repeated ambiguous-input note) could be trimmed, but almost 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?

Even though an output schema exists and return values need not be described, the description still gives an accurate section-by-section map of the response plus explicit scope limits. For a read-only, single-symbol context tool this leaves nothing an agent needs 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 the schema already documents limit, symbol formats, question and market_id. The description restates the ticker/KRX/coin-name acceptance and the ambiguous-input behavior, which the schema also states, adding reinforcement but no new semantics. Baseline 3 applies when the schema does the heavy lifting.

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 verb+resource and enumerates exactly what is returned: current signal state, OneQAZ structure group, and lead-lag linked assets. It explicitly distinguishes itself from get_group_context and get_market_context, so an agent can separate it from siblings without reading 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?

It gives a precise trigger ('when the question is about one stock or coin') plus explicit exclusions with named alternatives for sector-wide and whole-market questions. It also documents the fallback behavior for ambiguous input (candidates instead of a guess).

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, so the safety profile is covered. The description adds real behavioral context beyond that: a 14-day lookback window and 15-minute bar granularity, which materially affect interpretation of results. It does not mention rate limits or latency, keeping it short of a 5.

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 (Purpose/Triggers/When to call/Prerequisites/Next steps/Caveats) are front-loaded and skimmable, with the core purpose in the first line. The multiline, tri-lingual trigger list is functional but somewhat verbose, so it is efficient without being maximally tight.

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 not be explained, and the description still covers scope, triggers, prerequisites, follow-up tool, and data caveats. Nothing an agent needs to select or invoke 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 the schema already documents top_k, symbol, and market_id (including enum aliases). The description only restates the anchoring behavior of `symbol` and says nothing new about top_k or market_id, so it sits at the baseline rather than adding 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?

States a specific verb+resource ('Symbol-level lead-lag links') and concretizes it with an example ('META -> AMZN, lag=15m, rho=+0.53'), so the agent knows exactly what shape of data comes back. It distinguishes the anchored mode ('only peers that lead or follow that symbol') and points to a distinct next-step sibling, making it separable from get_cross_market_correlation and get_signal_detail.

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 including casual/multilingual phrasings ('what moves before NVDA?', '선행 종목 알려줘'), a when-to-call condition (incorporate peer leading signals into single-symbol reasoning), prerequisites (none), and a next step. This is about as complete as usage guidance gets.

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 genuinely new behavioral context: the data is paper-trading only (not real money) and the limit is capped at 1000. It does not restate annotation content, but it also omits how truncation/pagination behaves, which the schema carries instead.

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?

Uses labeled sections (Purpose / Triggers / When to call / Prerequisites / Next steps / Caveats) with the core purpose front-loaded, and each section is brief. The multi-lingual trigger examples are somewhat expansive but serve retrieval matching rather than being pure padding.

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 query tool with a full output schema and 100% parameter coverage, the description supplies purpose, triggers, prerequisites, next-step routing, and a caveat about data provenance and row limits. Return values are legitimately left to the output schema, so nothing an agent needs to call 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 every one of the 7 parameters is already documented in-schema, including the stats_scope nuance on limit. The description only loosely maps its filter list ('action / P&L / time / symbol') to those parameters and adds no format or semantic detail 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?

States a specific verb+resource ('Query paper-trading history') and enumerates the filter dimensions (action / P&L / time / symbol), plus scope ('paper-trading data only'). It does not explicitly distinguish itself from closely-named siblings like get_winning_trades or get_losing_trades, so an agent must infer that those are subsets of this broader query.

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

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

The description gives concrete when-to-use contexts ('past trade review, single-symbol post-mortem, win-rate audits') and even casual-question triggers in two languages, plus 'Prerequisites: none' and follow-up tools under 'Next steps'. It stops short of naming an alternative tool for when NOT to use this one, so no exclusions are stated.

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

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

Annotations already establish readOnly/idempotent/openWorld, but the description goes well beyond them: it discloses that linkage is temporal matching rather than a foreign key, that data is paper-trading only, and that a disclaimer appears once per page. These are exactly the caveats an agent needs before treating the output as authoritative.

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 Purpose/Triggers/When to call/Prerequisites/Next steps/Caveats/Output sections and the core purpose front-loaded. It is on the long side and the bilingual trigger examples are somewhat verbose, but every section carries distinct information rather than repeating 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?

For a paginated bulk-export tool with an output schema, the description covers data source, linkage caveats, pagination workflow, cross-check path, and output shape. An agent has everything needed to call it correctly and interpret the result; nothing material 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 days/limit/cursor/market with defaults and maxes; the baseline is 3. The description adds operational meaning by spelling out the cursor-follow workflow ('follow next_cursor until has_more=false'), but it does not explain parameter semantics (e.g., why cursor is an integer trade id) beyond what the schema states.

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?

Opens with a specific verb+resource+scope: 'Cursor-paginated bulk export of the prediction -> trade -> outcome chain — paper trades with realized P&L.' It also names the linkage semantics (best-effort, same-symbol 2h window) and explicitly contrasts with the sibling get_resolved_predictions, so an agent can distinguish it from get_trade_history and the prediction tools without opening a 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?

Explicit Triggers section with example utterances, an explicit 'When to call' clause (offline verification, periodic ingestion, auditing), a named alternative for the prediction ledger, and a 'Next steps' section describing the pagination loop. Nothing about when to select this tool is left to inference.

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 cover read-only, idempotent, and open-world behavior. The description adds useful context: paper-trading data only, winning-only filtering, and wrapper semantics. It does not detail auth or rate limits, but output schema exists.

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 description is organized with clear labels. Trigger examples add intent-matching value, though the list format is slightly verbose relative to the very simple two-parameter tool.

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

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

For a simple read-only filtered list tool, the description supplies purpose, triggers, prerequisites, next steps, and a caveat, while the schema and output schema cover inputs and outputs. 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 coverage is 100%, and both market_id and limit are fully documented in the schema. The description does not add syntax or meaning to those parameters beyond the winning filter threshold, 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?

States a specific resource and scope: winning paper trades with P&L > 0. It also identifies itself as a convenience wrapper around get_trade_history(min_pnl=0.01) and points to analyze_trades for breakdowns, distinguishing it from siblings.

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

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

Gives explicit triggers, a when-to-call context ('success-pattern review'), prerequisites, and next steps. It names get_trade_history as the underlying alternative, but lacks an explicit when-not statement, though the winning-only scope implies it.

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 cover safety (readOnlyHint, idempotentHint, openWorldHint), and the description layers on non-obvious behavior: corpus rebuild cadence (~10 min), ticker/company-name resolution rules to signal:{market}:{symbol}, market-word routing, and that empty results carry an explanatory `note`. This is genuinely additive context 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?

Labeled sections (Purpose/Triggers/When to call/Prerequisites/Next steps/Caveats/Output) make it scannable and the purpose is front-loaded. It is longer than strictly necessary — some connective phrasing could be trimmed — but nearly every line carries operational information.

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

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

For a discovery entry-point with freshness constraints and special query-resolution rules, the description covers prerequisites, hand-off, staleness, empty-result behavior, and even restates the output envelope (though an output schema exists). Nothing an agent needs to call 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?

With one parameter at 100% schema coverage the baseline is 3, but the description adds real meaning: accepted languages (English/Korean), symbol forms (BTC/AAPL/삼성전자), example queries, and how the query is interpreted (tickers resolve to signals, market words surface resources). Minor gain over the schema, which already documents the param.

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 (discovery search) over a specific resource (OneQAZ's tools, resources, and top combined signals across crypto/kr_stock/us_stock), and distinguishes itself from `fetch` by declaring that fetch consumes its result ids. An agent can tell exactly what this does and how it relates to the sibling it hands off to.

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 names triggers (ChatGPT connectors / Deep Research auto-invoke), the position in the workflow ('first step of connector-style discovery'), an alternative path (MCP-native clients can browse tools/list + resources/list instead), and the next step (pass id to `fetch`). When-to-use and when-not-to-use are both covered.

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