Gambit

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

Annotations only say this is a non-read-only, non-idempotent, non-destructive write. The description adds what the annotations cannot: writes go only to the personal layer and never alter the shared view, facts are 'unconfirmed' until matched to an official/wire source, prompt-injection defense ('Gambit treats any instruction inside it as text and never follows it'), a daily limit with 429/retry_after, and full error taxonomy (409 gambit_building, 404 unknown_symbol, 422 ambiguous_symbol/check_by_in_past/invalid_url, 503 gambit_personal_disabled). Note it also explains a server-side web search for confirmation, which sits in mild tension with openWorldHint=false, but since the lookup is Gambit-internal and constrained to official/wire sources, this is not treated as a contradiction.

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

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

Front-loaded well with the core action and scoping sentence, and the numbered list aids navigation. But items (2)-(4) largely restate the behavior of sibling tools (get_gambit_pack, submit_gambit_view, what_if_gambit, plan_gambit) — including a full description of plan_gambit's outputs that is irrelevant to adding a fact — so a substantial fraction of the text is cross-tool bloat rather than information about this call.

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?

There is no output schema, so the description carries the return burden and does so: it names user_item, confirmation (with status and matched source or null), duplicate (same-fact dedup, nothing stored, limit not consumed), and your_view.status as either form_with_your_model or same_as_shared. Combined with the error codes, expiry rule, and the instruction to tell the user when the view rests on an unconfirmed fact, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% (baseline 3), yet the description still adds real meaning beyond it: claim is 1-2000 chars, is treated strictly as text and never enters the shared evidence; url confirms immediately if an official/wire source Gambit already holds states the fact; check_by defaults to 14 days and defines when an unconfirmed fact expires. It also explains the symbol disambiguation recovery path (call again with one candidate).

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+scope: 'Add a fact you know about one ticker to YOUR personal layer', and immediately contrasts it with the shared evidence layer ('the shared view never changes because of it'). It is clearly distinguishable from sibling write tools like submit_gambit_view, create_gambit, and update_gambit_monitoring 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 utterance ('I know this about NVDA; what does it do to the view?') and then separates this tool from the three adjacent steps (get_gambit_pack + submit_gambit_view, what_if_gambit, plan_gambit) in a numbered list. It also states sequencing (next: call get_gambit_pack, form the view, then submit_gambit_view) so the agent knows exactly where this call sits in the flow.

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 annotations: it flags REAL MONEY, explains that removing margin pushes the liquidation price toward the market, states position size is unchanged, and documents error semantics (404 for unheld symbol, 409 not_isolated, venue reason on error). The destructiveHint annotation is corroborated and enriched with concrete consequences.

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 the core action and sign convention, then layered with risk, approval, and error details. Dense but each sentence carries unique, actionable information; 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?

For a 2-param mutation with no output schema, the description covers scope requirements, safety implications, approval workflow, and error behavior, leaving nothing an agent needs missing in order 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?

With only 50% schema description coverage, the description compensates by explaining the positive/negative sign convention for margin_usd and adding meaning to symbol (must be an agent-wallet position, 404/409 failure modes). It adds value beyond the schema's bare type declaration for symbol.

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: add or remove isolated margin on the agent's own agent-wallet position. It scopes the operation to 'YOUR agent-wallet positions,' distinguishing it from any cross-margin or non-wallet context without the agent needing another tool's 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?

Clearly establishes context: requires api:trade scope, only applies to positions the agent wallet holds, and demands human approval before calling. It does not name an alternative tool, but there is no obvious sibling to route against, so the guidance is close to complete.

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

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

Annotations only declare the safety profile (readOnlyHint=false, openWorldHint=false, destructiveHint=false), and the description adds substantial behavior beyond them: the api:chat scope requirement with a 403 failure mode, per-turn token quota consumption, 1-2 minute latency, server-side conversation persistence across calls, and one-thread-per-Gambit semantics. These are exactly the operational facts an agent cannot infer from annotations or 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 correctly: purpose, then auth, then cost/latency warning, then threading rules, then the image workflow and siblings. Every sentence carries information, but the single semicolon-heavy block is dense and the image-upload clause could be split or deferred for easier scanning.

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

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

Complete for a mutation-adjacent, non-idempotent tool with no output schema: it covers auth prerequisites, cost, latency, state persistence, thread identity, and the prerequisite upload step for images. Nothing an agent needs in order to call it correctly or avoid misuse 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 75%, but the description still adds real meaning: case_id is sourced from list_gambits (the schema says only 'a Gambit id from list_gambits') and is shown to route to the same thread the user sees in the app, while being mutually exclusive with new_conversation. image_urls is explained as an upload-first workflow via POST /api/chat/images with accepted formats and a 24-image cap, which the schema does not convey.

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 (talk to your Gambit trading agent) plus the exact scope of what can be discussed: market takes, position analysis, recommendations, strategy. It is explicitly distinguishable from the sibling read tools it names (list_conversations, get_conversation, manage_conversation) and from execution tools, since it declares 'this channel cannot execute trades or move funds.'

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 and when-not-to-call guidance: 'don't call it speculatively' because each turn is a real run costing 1-2 minutes and AI tokens. It also gives the routing rule for case_id versus starting a new thread, states the mutual exclusion between case_id and new_conversation, and redirects history management to the three sibling conversation 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 destructiveHint=true and non-idempotency, but the description adds substantial context beyond them: the required api:trade scope, real-money warning, preview/confirm contract, live position re-read with 409 refusal, cancellation of TP/SL orders, REDUCE-ONLY market close that can never open or flip, and per-position success in data.closed including partial-failure reporting.

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 the core action and the money/scope warning, and every sentence carries operational weight for a destructive tool. It is a dense single block rather than bulleted steps, which slightly reduces scannability, but no sentence is wasted.

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

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

With no output schema, the description compensates by describing the return shape (data.closed per position, error listing which positions closed) and the preview payload (symbol, side, size, entry price, unrealized PnL). An agent has everything needed to execute the confirm flow 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% and already documents positions as 'confirm_echo.positions from the preview, unchanged', so baseline is 3. The description adds genuine meaning beyond the schema by explaining why the field must match exactly (server re-reads live positions and refuses with 409 if they changed) and by describing what the preview response contains.

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 with explicit scope: 'Close EVERY open perp position in YOUR agent wallet.' It distinguishes itself from sibling tools like get_positions or adjust_margin by naming the wallet boundary (agent wallet, never the main wallet) and the scope (every position).

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 two-step protocol: first call closes nothing and returns a preview list, second call only after explicit human approval. It states the prohibition directly ('NEVER make the second call autonomously or chain it after the first') and the failure condition that forces re-previewing (409 positions_changed).

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

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

Annotations already mark this destructive/open-world, and the description still adds the details that matter: real money at the user's brokerage, the auth scope required, the at-most-once placement guarantee with same-check_id retry semantics, the 409/410 error meanings, and the fact that a broker refusal is an error rather than a placed order. The retry guidance is in mild tension with idempotentHint=false, but the annotation is the conservative default for a write and the description explains the actual dedup behavior by check_id.

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 critical rule (human approval required, never autonomous) is front-loaded in the first three sentences, which is exactly right for a destructive tool. It is long and repeats the 'never call it automatically' idea in two forms, but almost every sentence carries distinct 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?

There is no output schema, and the description fully compensates: it enumerates the response fields (order_id, status, filled_units, avg_fill_price), interprets the status enum, and warns that pending/accepted/unknown are not fills and must be followed via get_stock_order. Nothing needed to invoke or interpret the result is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real value: the six confirm_echo fields must be echoed exactly, and limit_price is null/omitted for a Market order. It stops short of explaining any field beyond that echo contract.

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 ('Place a stock order that propose_stock_order checked'), names the sibling that must precede it, and makes the real-money stakes explicit. An agent can distinguish it from propose_stock_order and confirm_trade 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 explicit when-to-use rules (only after showing the full preview and obtaining human approval of that exact order), explicit prohibitions (never autonomously, never immediately after propose_stock_order), and routes the agent to alternatives (get_stock_order, re-propose with a new approval) for the ambiguity cases.

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 flag destructiveHint=true and non-idempotent, but the description adds far more: REAL MONEY, a market order from the user's agent wallet, the required api:trade scope, and the specific failure modes (409 naming a mismatched field, 410 for expired proposals, 409 with price_drift for a moved market). This is materially beyond what structured fields 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?

Front-loaded with the action, then the money/safety warning, then the parameter rules and error behavior. Dense but every clause carries operational information; no filler or restated title language.

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 destructive, non-idempotent real-money tool the description covers preconditions, scope, integrity checks and error codes thoroughly. The only gap is the success side — no hint about what comes back (order id, fill status), which matters somewhat since there is no output schema, though error handling is what an agent most needs here.

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

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

Schema coverage is only 60% and the schema only says 'REQUIRED for execute — echo confirm_echo.X'; the description explains the integrity-check mechanism, that the echo must match the proposal exactly, that mismatches 409 naming the field, and that cancel needs none of these fields. That is real semantic value over 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 pair (execute/cancel) applied to a specific resource ('a previously proposed trade'), which cleanly separates it from propose_trade and propose_stock_order/confirm_stock_order in the sibling list. An agent knows exactly what this tool does 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?

Gives explicit when-to-use ('after a human approves a proposal'), explicit when-not ('NEVER call confirm_trade autonomously, and NEVER chain it automatically after propose_trade'), and a hard precondition (present the full preview and obtain explicit approval). The decision=cancel branch is also distinguished ('needs no echo fields').

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 the safety/idempotency profile; the description goes far beyond by disclosing the auth requirement (api:account), the dedupe behavior (created=false, already_existed=true), the 10-per-hour rate limit, the initial neutral stance/conviction state, the 'no order placed' guarantee, and the full error taxonomy with codes and recovery actions. It is consistent with idempotentHint=true rather than contradicting 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?

Core action is front-loaded and every clause carries information, but the single dense paragraph stacks parentheticals and error codes, making it heavy to scan. It earns its length but could be structured into shorter sentences without losing content.

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

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

Despite no output schema, the description enumerates the return fields (case_id, created, already_existed, monitoring_status, case, app_url) and explains the call's lifecycle, error states, and follow-up reads. Nothing an agent needs to invoke and interpret 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 already 100%, yet the description still adds meaning the schema cannot: symbol resolution rules for bare tickers, exact Hyperliquid ids (xyz:GOOGL), and the ambiguity policy when a ticker lists on several HIP-3 markets, plus sentence's 280-char limit and its role as the monitoring question with a documented default when omitted.

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 ('Open one of YOUR Gambits on a symbol') with the scope ('on a symbol') and even maps real user utterances ('start tracking GOOGL') to the call. It distinguishes itself from siblings by naming get_gambit, update_gambit_monitoring, search_symbols and get_tracking_updates and explaining how each relates.

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-use with example phrasings, when to reach for search_symbols (finding the symbol), and what to do when a Gambit already exists (returns it rather than creating a second; if paused, prompt the user before calling update_gambit_monitoring with active=true). It also tells the agent what to do on gambit_choice_required (ask the user) and on retryable errors.

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 flag destructiveHint=true and idempotentHint=false; the description goes well beyond that by stating that open positions are never closed by deletion, that the deletion is irreversible, that a foreign mandate returns 404, that api:account scope is required, and that the response includes app_url. This is exactly the extra context the 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 with the action and its scope, and every sentence carries distinct information (irreversibility, the pause alternative, confirmation, 404 behavior, return value). It is dense and slightly long for a one-parameter tool, but there is 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?

With no output schema, the description compensates by describing the return value and the app_url field. Combined with auth scope, error behavior, and side-effect semantics, an agent has everything needed to call this destructive tool correctly.

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

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

Schema coverage is 100% and the single parameter is already documented as a UUID, so the baseline is 3. The description adds provenance ('from list_mandates') and error semantics for an id that isn't yours (404), which is meaningfully more than the schema alone.

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

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

Names a specific verb and resource ('Delete one of YOUR saved Gambits') and scopes it with the id source ('mandate_id from list_mandates'), which cleanly separates it from get_mandate, list_mandates, and save_mandate. The ownership qualifier ('YOUR') further distinguishes it from any admin-level deletion.

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 alternative for the reversible case: 'to stop it for a while, use save_mandate action=update with status paused instead.' It also states a prerequisite workflow ('Confirm with the user first') and where the argument comes from, so 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.

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

Annotations only give the safety profile (readOnlyHint=false, non-idempotent), but the description adds the full operational picture: ~45s latency, shared monthly quota with generate_recommendation, a 5/min shared cap yielding 429 with Retry-After, 403 scope/tier errors, that no order is placed (capital_authority none), and that a recommendation is recorded but is advisory and refused by execute_recommendation (409). readOnlyHint=false is consistent because a ledger recommendation is written, so no contradiction.

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

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

Purpose is front-loaded, but the body is a single dense wall of prose spanning quota, rate limits, Gambit-view internals, and execution handoff. Almost every sentence carries needed information given the tool's complexity, but the lack of segmentation makes it hard to parse and some detail (app_url, view block fields) is overload for the selection 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?

With no output schema, the description fully carries the return contract: outcome states (actionable/watch/pass/insufficient), execution.state, decision_analysis and decisive_evidence, and the Gambit-view block. Combined with the auth, quota and execution-handoff details, an agent has everything needed to call and interpret it.

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

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

Schema coverage is already 100%, but the description goes beyond it by explaining the two disjoint naming modes (opportunity_id vs security_id+session_date), the mo_+32hex format, that scenario_id picks a plan scenario, and the added constraint that a Daily Move 'must be a Big Move'. It adds real meaning over the schema's per-field hints, though the mutual-exclusion/requirement structure is implied rather than stated.

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 ('Evaluate one setup for YOUR account') and anchors it to a known action ('the same action as Evaluate in the Gambit app'). An agent can distinguish this from generate_recommendation, review_opportunity_trade, and the get_* 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?

Explicitly says 'Do not call it speculatively', defines the two valid ways to name a setup and where each id comes from, and routes the agent to review_opportunity_trade for refreshing a ticket and to a separate api:trade step for execution. When-to-use and when-not-to-use are both present.

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 the generic safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false); the description adds what those annotations cannot: it stages rather than places an order, targets the agent deposit wallet and never the main wallet, requires the api:trade scope, caps leverage at the API ceiling, and enumerates the returned fields including confirm_echo. The staged-proposal behavior is fully consistent with a non-readOnly, non-destructive, non-idempotent annotation set.

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 critical facts are front-loaded (preview, no order placed, human approval required) before the error taxonomy, and each sentence carries distinct operational content. It is dense and long, but almost none of it is filler, so it stays readable despite the volume.

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 no output schema, the description still enumerates the return payload (proposal_id, expiry, plan, notes, confirm_echo), and it covers scope requirements, wallet targeting, leverage capping, and the full 404/409 error taxonomy. An agent has everything needed to invoke it correctly and to route the result into confirm_trade.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It documents recommendation_id's provenance and leverage's default (1x) and ceiling, but slippage_bps is never mentioned anywhere, and leverage's interaction with the recommendation's own leverage is only implied. Partial compensation for a total schema-coverage gap.

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 (preview-execute a pending recommendation from the agent wallet) and immediately disambiguates against the sibling that actually executes (confirm_trade). The name's 'execute' is reconciled with the title's 'preview' by the explicit 'This does NOT place anything', so an agent can tell it apart from confirm_trade/propose_trade/respond_to_recommendation 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 when-to-use condition (recommendation_id is a list_recommendations(status=pending) id from YOUR agent wallet), an explicit when-not plus alternatives (advisory rows -> respond_to_recommendation or propose_trade), and a hard sequencing rule (only call confirm_trade after explicit human approval, never autonomously). It also maps 404 (not yours) and 409 (stale/invalidated) failure paths to distinct meanings.

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?

Though annotations declare non-read-only and non-idempotent, the description explains WHY and adds far more: the api:recommend scope (403 otherwise), manual-recommendation quota burn, LLM token spend, ~2 minute duration, refusal semantics for other instruments, and the ledger statuses (pending/recorded/not_persisted) that determine whether the returned id is respondable. This is exactly the behavioral 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 with the core action and quota warning, which is good, but it then becomes a single enormous block of dense, jargon-heavy prose covering Gambit-view decision paths, ledger id variants, wallet rails, and diagnostics without sectioning. Most sentences earn their place individually, yet the length and run-on structure make it hard for an agent to parse quickly.

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 no output schema, the description fully specifies the return shape: user_facing_recommendation with state recommend|watch, expression_kind single_instrument|pair_trade, ledger.status variants, snapshot_id, and watch_status/pin_status values. For a high-complexity mutation tool with no structured output contract, this is complete.

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

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

Schema coverage is 67%, and the description compensates far beyond the schema: watch_instrument 'PINS the run to that one instrument, so the answer is about YOUR instrument or it says why it could not be, never a different asset', all_universe semantics, and include_diagnostics default false with the specific extra payload it returns. It also documents the 422 failure modes per parameter 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?

Opens with a specific verb+resource: 'Trigger YOUR Gambit agent to run a fresh trade recommendation', and immediately distinguishes itself from siblings by noting it is a real agent run that consumes quota, unlike list_recommendations or respond_to_recommendation. An agent can tell it apart from ask_gambit_agent, get_gambit, and evaluate_opportunity 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?

Explicit exclusions and alternatives: 'do not call it speculatively', 'If the call times out ... check list_recommendations before retrying', 'Set all_universe to scan the full tradeable universe instead', and retry-vs-different-instrument guidance for blocked states. It also names the sibling to use for the follow-up (respond_to_recommendation, propose_trade -> confirm_trade).

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 genuine behavioral traits: absence returns null, an alias marker with no balances avoids double-counting, unified accounts can hold funds in spot so zero native_perp is not empty, DEX margin accounts must not be summed with native_perp, and failed DEX reads surface via failed_dexes with meta.quality='partial'. These are non-obvious data-integrity semantics the agent would otherwise get wrong.

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 core scope is front-loaded in the first clause, but the remainder is a dense run-on of nested parentheticals mixing wallet taxonomy, field definitions, and error states. Since there is no output schema the content largely earns its place, but the structure makes it hard to scan.

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

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

With no output schema, the description carries the full burden of explaining return shape and it does so thoroughly: wallet entities, per-wallet native_perp/spot/hip3_perp fields, collateral_token, and partial-failure indicators. An agent can correctly interpret and act on the response from this text alone.

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?

Zero parameters yields a baseline of 4, and the description reinforces that identity is derived from the API key rather than supplied, which is meaningful for a parameterless tool. No further param detail is needed or possible.

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 (account balances) and immediately pins the scope to the API key's own account, explicitly excluding an address input. That clause distinguishes it from address-oriented siblings such as get_wallets without needing to name them.

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 'YOUR ... no address input, identity comes from the key' phrasing implicitly tells the agent when this tool applies rather than an address-based one, and '(Requires api:read.)' flags a prerequisite. But there is no explicit routing against get_wallets, get_holdings, or get_portfolio_performance, so the when-to-use rule must be 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/idempotent/non-destructive, and the description adds real context beyond them: the api:read auth requirement, server-side caps on returned points, and the meta envelope. It doesn't detail what happens when a range exceeds caps (truncation vs error), but the added auth and cap disclosure is meaningful.

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 core statement, then packs symbol format, intervals, defaults, and return shape into dense but readable prose. No filler sentences; slightly information-dense but each clause earns its place.

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

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

With no output schema, the description carries the return-value burden and does so ('[timestamp, {o,h,l,c,v}] series with a meta envelope'). Auth requirement and defaults round out the picture; only edge-case behavior for oversized ranges is unstated.

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 only 40%, but the description compensates well—it documents the instrument_id format (bare Hyperliquid symbols vs dex-prefixed HIP-3 like xyz:TSLA), enumerates intervals, and explains start/end defaults. Only max_points behavior (beyond the cap note) is left to 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 ('OHLCV price bars for an instrument over a time range') and clarifies scope via defaults and interval set. It does not differentiate itself from the closely related sibling get_prices, which an agent might reasonably confuse it with.

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 useful context: symbol values come from scan_markets and start/end default to the last 24h. However, it never states when to choose this over get_prices or get_live_snapshot, leaving the main selection decision 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?

Beyond the read-only, idempotent, open-world annotations, the description discloses important behavior: New York calendar dates, per-day caps, earnings completeness semantics via completeThrough, truncated flags, what null completeThrough means, and the api:read requirement. These are substantive operational caveats not captured by annotations.

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

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

The description is front-loaded and information-dense, with nearly every clause contributing necessary behavior. However, it is a single long paragraph with many semicolon-separated rules, making it harder to scan than a lightly structured version would be.

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 12-parameter tool with no output schema, the description is unusually complete: it covers all kinds, date-window rules, response caveats such as completeThrough and truncated, the app_url field, and the required permission. An agent has enough context to call this correctly without external documentation.

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?

Although schema description coverage is already high at 92%, the description adds meaningful semantics beyond the schema: forward windows of 1-90 days, back windows of 0-14 days, explicit from/to requiring both or neither and max 90 days, scope=all lifting the earnings size filter, symbols always included, and exact identifier fields required for macro_take.

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 (macro and earnings calendars) and explicitly enumerates the four supported modes via kind. It gives concrete use cases such as 'the call for earnings this week' and distinguishes macro vs earnings vs macro_take vs earnings_priority clearly enough that an agent can select the right invocation.

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 selection guidance for each kind: macro for scheduled macro events, earnings for upcoming reports, macro_take for a stored shared take on one event, and earnings_priority for tickers followed by the user's open and saved Gambits. It also explains when scope=all applies and what date-window controls are available.

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 readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: 'No forward filling, trading or collection on read,' 'Missing history/rights is explicit,' 'forecasts not observed prices,' 'history returns capped genuine observations,' and 'Returns are fractions.' These are useful operational caveats an agent couldn't get from 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?

It is a single hundred-plus-word run-on paragraph stuffed with parentheticals, so the core purpose is not front-loaded and the three views are harder to extract than they should be. The content is mostly informative, but the structure actively impedes scanning.

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

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

Against 8 params, 0% schema coverage, no output schema, and open-world behaviour, the description does a lot to explain data sources and result semantics, but it leaves half the parameters (start/end/interval/symbol/max_points) undefined for an agent that must construct calls.

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

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

Schema coverage is 0% across 8 parameters, so the description must compensate. It explains the view enum thoroughly and implies series_id (catalog discovery) and lag behaviour ('calendar-day lag' ties loosely to lag_days), but start, end, interval, symbol, and max_points are never addressed, leaving most of the surface undocumented.

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 (read) and a well-scoped resource: stored compute/GPU pricing plus forecasts and a correlation view against equities. It is distinguishable from get_prices/get_bars by the GPU-rental and forecast framing, though the dense parenthetical enumerations of vendors (OpenRouter, Pricify, ORNN, Databento) crowd out the one-line purpose.

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

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

The implicit workflow is inferable: use view=catalog to discover series_id before history/correlation, so an agent can figure out sequencing. But there is no explicit when-to-use/when-not, no mention of when to prefer get_prices or get_symbol_research instead, and the view semantics are buried mid-sentence.

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

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

The description adds significant behavioral context beyond the annotations: it details the returned message structure, ordering (oldest first), limit range and default, the 404 ownership restriction, and the required api:chat permission. Annotations already cover safety (readOnly, idempotent), so this is good supplementary detail.

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

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

The description is a single paragraph that front-loads the key information: what the tool does, the source of conversation_id, ordering, and limit. It is dense with useful details and has no filler, though it could be slightly better structured with separate sentences for readability.

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

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

Given the tool's simplicity (read-only, two parameters), rich annotations, and absence of an output schema, the description covers all necessary aspects: return format, ownership constraint, authentication requirement, and parameter details. Nothing critical 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?

With 0% schema description coverage, the description compensates well: it explains that conversation_id comes from list_conversations and specifies the limit range (1-200) and default (100). It does not describe the format of conversation_id beyond that, but it adds meaningful semantics beyond the bare 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 and resource: retrieving one of the user's conversations with its newest messages. It distinguishes from the sibling list_conversations by indicating the conversation_id comes from that tool, though it does not explicitly contrast with other conversation-related tools like manage_conversation.

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 implies usage: you need a conversation_id from list_conversations, and it explicitly states that accessing someone else's conversation returns 404. However, it does not offer explicit when-not guidelines or mention alternatives for different use cases.

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. The description adds genuinely new context beyond them: the data is pre-stored, no model is executed on call, the caller needs api:read, and the response includes an app_url pointing at the Daily Moves screen.

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, front-loaded sentences with no filler; the permission note is tucked into a parenthetical at the end where it belongs. Slightly dense use of parentheticals, but nothing wasteful.

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

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

For a one-parameter read with rich annotations and no output schema, the description covers what is returned, that it is stored rather than computed, and the auth requirement. It omits what happens when no captured context exists for a mover, which would be the last missing piece.

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

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

Schema coverage is 0% — the pattern is present but undocumented. The description compensates by naming the parameter's meaning (US-equity ticker) and giving a concrete example (CXMT), which is more than the schema provides, though it does not explain the pattern's bounds or edge cases.

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: it retrieves the stored research context (news, catalysts, evidence) behind a symbol's big move. The symbol-scoped phrasing and the ticker example distinguish it from the list-style sibling get_daily_moves and from the plan-oriented get_daily_move_plan, though no sibling is named explicitly.

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

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

Usage is implied by the question it answers ('Why a Daily Move moved'), and 'Stored only — it never runs a model' implicitly steers agents away from asking for fresh analysis. But there is no explicit when-to-use/when-not guidance and no named alternative for live or unrestricted research.

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/non-destructive, so the description's added value is the display-only semantics, the auth requirement (api:read), and the fact that the response includes app_url for the Daily Moves screen. That goes beyond what the structured fields 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?

One dense paragraph, front-loaded with the resource and usage, with no repeated filler. Slightly long but every clause (source tool, format, display-only caveat, auth) carries 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?

With no output schema, the description helpfully notes the response carries app_url, and it covers inputs, auth, and the non-actionable nature of the output. Enough for an agent to call it correctly and interpret the result.

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 only 50% (session_date has a pattern but no description), and the description compensates by spelling out the YYYY-MM-DD format and tying both parameters to their source in get_daily_moves.

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 ('example trade plan for one Daily Move') and explicitly scopes it as the per-item companion to get_daily_moves, so the agent can distinguish it from the sibling list tool 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?

Tells the agent exactly how to source inputs ('pass its security_id and session_date ... from get_daily_moves') and sets a clear exclusion ('never an order or a recommendation to trade'). It doesn't name the tool to use for actual trade proposals, but the usage context is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value on top: the product-level default filters and how to bypass them (pass 0), the compact-vs-all filtering behavior, rejection-reason payload on non-qualifying rows, the meta.caps_applied.available uncut-size signal, and the required api:read scope. It stops short of describing snapshot freshness/staleness beyond the word 'materialized'.

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 what the tool returns, then defaults, then view semantics — every clause carries information. It is a dense single paragraph, slightly overpacked, but there is 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?

With no output schema, the description shoulders return-value explanation and does so well (field list plus meta.caps_applied.available). The remaining gap is the three undocumented parameters, which leaves the agent guessing on min_abs_z and session selection.

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 only 33%, and the description restates the two filter defaults already documented in the schema while leaving min_abs_z, limit, and market_session completely unexplained in both places. It compensates partially, not fully, for the coverage gap.

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 (US-equity session movers from the Daily Moves snapshot) and enumerates the returned fields (session return, z-score vs annual distribution, dollar volume, market cap, qualifies_big_move). An agent can tell this apart from get_daily_move_context or get_market_brief 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?

Gives clear when-to-use guidance for the two modes: view=compact for qualifying movers, view=all 'useful for why is X not listed'. It does not, however, route the agent away from the adjacent daily-move/context/plan siblings, so the alternative-selection guidance is incomplete.

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/non-destructive, and the description adds useful context beyond them: the hard ticker allowlist and the api:read scope requirement. It does not disclose rate limits, payload size, or whether darkpool results are paginated.

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?

A single dense sentence front-loads the resource, then the kinds, then the auth requirement — no filler. It is slightly run-on, but every clause (tickers, kind semantics, scope) earns its place.

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

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

The tool has no output schema, so the description should hint at what each kind returns structurally (fields, shape, time window conventions). It names the analytics but not the response form, and never mentions the darkpool date-window requirement that the schema only partially signals.

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 only 40% schema coverage, the description carries real weight: it maps each kind enum value to a concrete data product and constrains ticker to a fixed list. It leaves start/end (darkpool-required per schema) and limit entirely to the schema, so it does not fully compensate for the coverage gap.

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 (US equity options positioning) and enumerates exactly what each kind returns, plus the ticker universe. An agent can distinguish this from get_exposures or get_orderbook 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?

It gives clear in-tool routing guidance: gex for gamma/charm/vanna, iv for IV rank/percentile/term structure, darkpool for dark-pool prints. It does not contrast this tool with adjacent siblings such as get_exposures or get_live_snapshot, but the kind-level disambiguation is strong.

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 non-destructive, so the safety profile is covered. The description adds real value beyond that: it discloses the taxonomy-only scope ('never reads your account') and the meaning of the status values (same_exposure vs separate) plus the returned fields, compensating for the absent 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?

It is front-loaded (purpose, then parameters, then return shape, then worked example) and every sentence carries information, but the return-field enumeration plus the workflow example make it dense for a single-argument 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 no output schema, the description supplies the return-field list and status semantics, the input format, and a concrete end-to-end usage pattern, so an agent has everything needed to call and interpret the result.

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

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

Schema coverage is 0%, so the description carries the burden and does: it states the batch limit ('up to 50') and shows accepted symbol syntax for both venues ('Hyperliquid symbols (BTC, xyz:TSLA) and brokerage tickers alike'). That explains the pattern and prefix conventions the schema only encodes opaquely.

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 ('Group instruments into the exposures Gambit treats as one') and immediately scopes it against the account-reading siblings by asserting it never reads the user's account. An agent can distinguish this taxonomy-lookup tool from get_positions/get_holdings 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?

It gives an explicit conditional workflow: for 'my exposure to MU across accounts', first call get_positions and get_holdings, then pass the held symbols here and sum rows sharing MU's group_id. That names the alternative tools and the exact sequence, 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 already cover the read-only/idempotent safety profile, and the description adds genuinely useful context beyond them: a null value means no data rather than an error, and an api:read scope is required. It does not mention rate limits, pagination, or limits on timeseries length, so it is not fully complete.

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?

A single front-loaded paragraph that opens with what is returned, then modes, symbol format, null semantics, and auth — the highest-value information comes first. It is dense but nearly every clause carries operational meaning; the only soft spot is the parenthetical feature-family list.

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 7-parameter tool with no output schema, the description covers the essential call-shaping facts: mode semantics, identifier format with a cross-tool source of truth, null-vs-error behavior, and required scope. An agent could invoke it correctly without further clarification.

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 only 43% schema coverage the description does real work: it explains all three mode values, defines instrument_id format (bare Hyperliquid symbols or dex-prefixed HIP-3 symbols, matching scan_markets output), and ties universe_id to outlier universes like hl_top50. It leaves start/end as only implicitly timeseries-scoped, without restating the ISO 8601 format or range inclusivity.

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 — pre-computed quantitative features — and enumerates the families it covers (returns, realized vol, z-scores, funding, OI deltas), and explicitly delegates the full enumeration to the schema. This clearly distinguishes it from raw-data siblings like get_bars, get_prices, and get_market_regime.

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 per-mode routing guidance: snapshot for the latest value, timeseries for history, outliers for top-N extreme instruments in a universe. It also tells the agent to source instrument ids from scan_markets. It stops short of stating when to prefer a sibling over this tool (e.g. versus get_bars for raw series).

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/idempotent annotations: it explains wallet resolution (main_wallet, agent_wallet, alias), truncation semantics (2000-fill page, hip3_truncated_dexes), partial-failure flags (hip3_complete, hip3_failed_dexes), the 90-day window cap, and a 30-calls/minute rate limit.

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 the core identity before drilling into wallet/return-detail mechanics, and every clause carries real information. It is dense as one block paragraph, so slightly harder to scan than it could be.

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 no output schema, the description shoulder the burden and does so fully—it documents the return structure (address, fills, hip3_fills, per-fill fields like coin, px, sz, side, closedPnl, fee, oid, hash) and failure signaling. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds constraints the schema does not state: a 90-day maximum window and that end_time cannot be in the future. It also restates the 24h default, which is redundant with 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 and resource ('YOUR Hyperliquid fills (executed trades)') and disambiguates from sibling tools like get_open_orders and get_positions by scoping to executed fills. The 'my fills today' framing makes the intent unmistakable.

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

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

Provides clear usage context via the phrase 'the call for "my fills today"' and directs narrowing the window on truncation. However, it never names alternatives (e.g., get_open_orders for open orders vs. get_positions) so the agent must infer that this is the executed-trades tool.

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?

Adds substantial context beyond the readOnly/idempotent annotations: newest-first ordering, a default limit of 20 with a 1-50 range, a total field counting all waiting items, and the required api:read scope. These are exactly the details an agent needs before calling and before interpreting how much it received.

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 scope and ordering, then the field enumeration. The field list is long but earns its place since there is no output schema; a slightly tighter grouping of returned fields would make it easier to scan.

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

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

With no output schema, the description supplies the return shape (execution_id, cron_id, cron_name, description, instrument_id, triggered_at, query, result, predicate result), the total counter semantics, and the app_url pointer. Authorization requirements are also covered, leaving nothing an agent needs for correct invocation.

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

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

Schema coverage is 0% and there is one parameter, so the description must carry it — and it does, supplying the default of 20 and the 1-50 bounds that the schema declares only as min/max without any default value. That default is genuinely new information over 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 and narrows scope precisely: 'YOUR signals that fired and still wait for your answer', explicitly disambiguating from the sibling list_signals by restricting to unanswered fired signals. It also self-identifies as 'the call for "my fired signals"', so an agent can match user intent 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?

Usage is clearly implied by the state filter (fired and awaiting answer) and it routes the follow-up action by naming respond_to_signal and telling the agent to pass execution_id. It never explicitly contrasts with list_signals or save_signal, so the when-not guidance is inferred rather than 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 cover read-only/idempotent safety, and the description adds substantial context beyond them: api:read authorization, the default-on mark_seen read-receipt side effect with an opt-out, asynchronous build queueing on first unseen symbol, freshness statuses, the fact that case_id reads neither record seen nor run freshness checks, 404 for non-owned Gambits, and specific error codes.

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 two-mode selection is front-loaded, and much of the length is justified because there is no output schema and the return shape must be explained. However, it is a single dense paragraph enumerating many view fields; bullets or headings would make it scannable and would trim some 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?

There is no output schema, so the description carries the full burden of explaining returns: the view contents, since_you_last_looked, reasoning ledger, new_since_view, freshness, what_would_change_our_view, judgments, and case-seed fields. Combined with error states and side effects, 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 the baseline is 3; the description adds the symbol resolution workflow the schema cannot express—Hyperliquid-vs-US-stock precedence, the ref:eq:TICKER escape hatch, and resubmitting an ambiguous_symbol candidate as the symbol—plus case_id provenance. Some of this duplicates schema text, so it is strong but not entirely additive.

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 sentence states the exact two resources and modes: Gambit's shared per-ticker view (symbol) or one of the user's Gambits in full (case_id). It distinguishes itself from siblings by explicitly routing hypothetical scoring to what_if_gambit, case enumeration to list_gambits, and data-quality complaints to leave_feedback.

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-use rules for both modes, the one-of-two constraint, when to call what_if_gambit, how to handle user pushback against levers, when to use leave_feedback, mark_seen=false for silent reads, and not to poll while a view is building. Recovery from 422 ambiguous_symbol is spelled out with the exact retry 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 already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds substantial context: shared versioned view semantics, ambiguity handling via 422 ambiguous_symbol and ref:eq:TICKER, error codes, api:read requirement, app_url behavior, and pagination mechanics. No annotation contradiction.

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

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

The definition is front-loaded with the core purpose and organized with BY SYMBOL / BY CASE_ID / Errors sections. However, it is very long and dense, with several run-on parentheticals, so it is not maximally concise.

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

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

There is no output schema, but the description exhaustively covers return fields for each view, pagination, error behavior, permissions, and app_url differences. For a complex tool with two modes and eight parameters, this is complete.

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

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

Schema coverage is 100%, but schema descriptions are terse; the prose adds meaningful detail: accepted symbol formats, ref:eq fallback for US stocks, case_id source, view enum meanings, limit defaults, before_version/next_cursor usage, and required ids for entry/observation views. This goes well 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 opening sentence states a specific verb/resource and two mutually exclusive modes: Gambit's shared view of a ticker by symbol, or a dated history of one of the user's Gambits by case_id. It also names list_gambits as the source for case_id, making the tool's purpose distinct and actionable.

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

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

It explicitly says 'Pass exactly one of the two' and gives detailed conditions for symbol reads (any covered ticker, even without a Gambit) versus case_id reads (from list_gambits). It also covers ambiguity resolution and reporting bad views via leave_feedback, but does not explicitly say when to choose this over sibling get_gambit.

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 and idempotent annotations, the description discloses authentication requirements (api:read), that Gambit runs no model for this call, that personal-layer data never changes the shared view, and exact error codes for building, unknown symbol, ambiguity, and disabled reads.

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

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

The description is front-loaded with the core purpose and uses numbered sections for workflow, error handling, and next steps. It is somewhat verbose and repeats the no-model point, but the length is largely justified by the multi-step workflow it must explain.

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 without an output schema, the description fully explains the return structure: based_on_version, pack contents, rules, output_schema, and submit_with. It also covers error recovery and how this call fits into the broader personal-view workflow.

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 symbol's format and examples are already documented. The description adds meaningful parameter behavior by explaining the 422 ambiguous_symbol error and instructing the caller to retry with one candidate as the symbol.

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: retrieving the evidence pack for one ticker so the caller's own model can form a view. It distinguishes the tool from siblings by naming get_gambit for queueing and submit_gambit_view as the required next step.

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 workflow: call get_gambit_pack, form the take with the pack's rules and output_schema, then call submit_gambit_view. It also routes related tasks to add_gambit_evidence, what_if_gambit, and plan_gambit, with clear when-to-use conditions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description extends far beyond them: option arithmetic (contracts vs per-share pricing, contractMultiplier null handling), currency caveats (null vs USD, totalValueCaveat values), holdingsDegraded reduced-feed semantics, meta.data_freshness staleness, meta.degraded_reason, and caps_applied truncation. This is exactly the additional behavioral context the annotations cannot carry, and it is consistent with them.

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

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

The description is very long and dense, but for a tool with this many edge cases (option multipliers, currency aggregation, degraded feeds, per-cap truncation) most sentences carry load-bearing semantics rather than repetition. It is front-loaded with purpose and never buries the core statement, though the heavy capitalization and sheer volume slightly hurt scannability.

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

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

There is no output schema, so the description bears the full burden of describing return shape — and it does: totalValue/currency/totalValueCaveat, accountId, topHoldings limits, activeSymbolPosition legs and null aggregation rules, holdingsDegraded, and meta flags. For a tool this complex, an agent has everything needed to interpret results 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 real meaning beyond the schema: it explains that 'full' yields the raw snapshot (holdings/totalCash, no topHoldings/spotlight) and that symbol is compact-only, driving activeSymbolPosition with cross-leg nulling rules. That is more than a restatement of the enum/pattern.

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 opening sentence names the exact resource and scope — 'YOUR connected brokerage holdings (the API key's user — no address input, identity comes from the key)' — plus the providers (Robinhood and any SnapTrade-linked brokerage). It explicitly distinguishes itself from get_positions/get_account_balances (Hyperliquid) and states what is excluded (bonds, CFDs, futures). An agent can tell it apart from every sibling 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?

It routes the agent to alternatives for a specific case ('see get_positions / get_account_balances for Hyperliquid') and gives condition-based selection for view:'compact' vs 'full' and the symbol spotlight. It also states the read-only constraint. It stops short of a full when-to-use map across the many siblings (e.g., when to prefer get_account_balances for cash), so it is clear but not exhaustive.

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

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

Beyond readOnly/idempotent annotations, the description discloses cache-only behavior, exact content-keying, the missing/unavailable status semantics, return shape, and the api:read requirement. These details materially affect how an agent interprets results and avoids assuming fresh generation.

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 paragraph is dense but well front-loaded: purpose first, cache behavior next, packet input shape, then return semantics. Every sentence contributes useful information for correct invocation.

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?

There is no output schema, but the description explains return values including cached compression fields and missing/unavailable outcomes. Combined with annotations and full parameter guidance, it is complete for an agent to call and interpret the tool.

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

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

Schema description coverage is 0%, but the description compensates by documenting the observations packet shape, field meanings, kind enum options, fact_fragments and significance_facts limits, optional observed_at, and return statuses. This adds substantial semantic clarity beyond the raw 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: cached short wording for Home observations in Gambit. The cache-only constraint and exact-match behavior clearly distinguish it from tools that generate fresh model output, such as ask_gambit_agent. An agent can understand the tool's unique role 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?

It gives clear context: cache only, never runs a model, never reads the account, and missing means 'no summary yet' with a fallback to use the facts you sent. It does not explicitly name sibling alternatives, but the operational boundaries are well defined.

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

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

The description discloses non-obvious behavior beyond the annotations: reading the daily view claims today's card, one card per UTC day, that reading ahead claims nothing, and that the tool requires api:read. This is unusually rich, though there is mild tension with readOnlyHint=true since claiming the card changes read state; it is non-destructive and idempotent enough that it reads as bookkeeping rather than a contradiction.

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

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

The purpose and default are front-loaded and every clause carries information (response fields, claiming behavior, read path). It is a dense single paragraph rather than a structured breakdown, which slightly reduces scannability.

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

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

There is no output schema, so the description responsibly enumerates the returned fields (card, completed, progress, spine, app_url) and the read-tracking flow. Nothing an agent needs to call this correctly appears 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 only 50% schema coverage and an undescribed enum, the description compensates fully: it defines what 'slug' is (a concept slug or an asset lesson's symbol) and explains all three view values, including that slug is required for view=lesson.

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 concrete verb+resource (a daily Gambit lesson) and enumerates exactly what each of the three views returns (daily card, archive, single lesson by slug). It clearly distinguishes itself from the nearby mark_lesson_read sibling by naming it and its role.

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

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

It explicitly says view=daily is the default and what each mode is for, covers the when-to-use condition for view=lesson ('reading ahead claims nothing'), and routes read-marking to mark_lesson_read. The alternatives and their selection conditions are spelled out, not implied.

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/non-destructive/openWorld, so the safety profile is covered. The description adds real context beyond that: the data source (Hydromancer position snapshots), the 'stale' indicator, and that ADL mode omits per-trader rows.

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 details each view. The field enumerations are dense but earn their place given there is no output schema. Some range values duplicate the schema, and the parenthetical flow is slightly crammed but still scannable.

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

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

With no output schema, the description carries the burden of documenting returns and does so thoroughly for both views, including defaults and the ADL omission. Minor gap: 'stale' is named but never explained, and refresh/freshness expectations for the snapshots are unstated.

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 only 60%, but the description compensates by documenting defaults (view, queue_side), explicit ranges (bucket_pct 0.05-5, max_distance_pct 1-100), and which view each parameter applies to. It adds meaning beyond the terse 'levels only'/'adl only' schema notes.

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 (liquidation levels and the ADL queue for one perp), and explicitly maps the natural-language intent 'liquidation map for BTC' to this call. No sibling tool covers liquidation maps, so it is clearly distinguishable from get_positions/get_exposures/get_live_snapshot.

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 clear routing context ('the call for "liquidation map for BTC"') and distinguishes the two modes with defaults (view=levels default, view=adl, queue_side default short). It does not, however, state when NOT to use it or contrast against a specific alternative.

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 readOnly/idempotent/non-destructive/openWorld, so the bar is lower, and the description still adds real value: the data comes from a hot cache and is therefore fresher but not authoritative history, plus an explicit auth requirement ('Requires api:read'). It does not describe the shape of the returned 'features'.

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?

One tight paragraph: purpose first, then alternatives, then parameter formats, then auth. Every clause carries information an agent needs; there is 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?

For a read-only tool with no output schema, the description covers source, freshness, id format, batching, and auth. The remaining gap is that 'market features' is never enumerated, so an agent cannot anticipate what fields come back or whether it should combine this with get_feature for full coverage.

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 50% and the description compensates well: it explains the single-vs-comma-separated batch semantics and pins down the exact id format (bare Hyperliquid symbols like BTC/HYPE, dex-prefixed HIP-3 like xyz:TSLA) plus a cross-reference to scan_markets' `symbol` values. It leaves open the edge case of passing both parameters or neither, which matters since 0 parameters are required.

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 ('Real-time market features') with explicit scope (one or more instruments, hot cache) and names the sibling it is fresher than ('get_feature'). An agent can distinguish this from get_feature, get_feature/get_bars, and get_prices 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?

Explicitly routes the agent: use this over get_feature when current conditions are needed, and it explains single-vs-batch invocation. It stops short of a full when-not statement (e.g., historical ranges → get_bars, and what happens if both id params are supplied or neither).

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

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

The annotations provide comprehensive behavioral signals (readOnlyHint, destructiveHint, idempotentHint). The description adds minor helpful context regarding the `app_url` being present in the response, but doesn't add much beyond the structural metadata already provided.

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?

While a little verbose, the structure is logical, starting with the core purpose and ending with the technical context (UI link and access rights). The information density is appropriate for a high-level description.

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

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

The description is complete for its intended purpose. It confirms the resource scope (only the user's saved items), the required identifier, and the necessary UI context (`app_url`) for the agent to follow up.

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?

Since schema coverage is 100%, the baseline is 3. The description adds value by explaining the multiple possible sources for the required `mandate_id` (i.e., from `list_mandates`, a Gambit row, or an activity row).

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

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

The description clearly states the intent is to retrieve a specific 'Gambit' (mandate). By requiring a `mandate_id`, it distinguishes this retrieval operation from listing or creating mandates.

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

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

It provides crucial usage guidance by specifying that if the ID belongs to another user, it will return a 404 error. This defines the scope and limitations of the tool for the agent.

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 safety, and the description adds substantial context beyond them: newest-first ordering, the api:read auth requirement, status lifecycle (pending/processing/ignored/failed with last_error), and what evidence and recommendation fields represent. This is well past what structured fields 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?

Purpose and parameters are front-loaded, and every clause about row fields earns its place given there is no output schema. It is one very dense run-on sentence, though, which slightly hurts scanability.

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 no output schema, the description must document the return shape — and it enumerates nearly every row field (mandate_id/version, symbol/security_id/subject_id, observed_at, relevance_reason, activity_reasons, evidence, status, recommendation, case_id, timestamps). Nothing an agent needs to call or interpret it 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 0% for the single limit param, and the description fully compensates with 'limit 1-20, default 10', which matches the schema bounds and adds the default the schema omits.

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 ('What Gambit found for YOUR saved Gambits') with scope ('saved Gambits', newest first) that separates it from get_gambit, list_gambits, and get_gambit_history. The parenthetical 'what did my saved Gambits find today' pins the intent unambiguously.

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 framing 'the call for "what did my saved Gambits find today"' gives clear usage context, and it routes to get_gambit when a case_id is present. It doesn't explicitly exclude or contrast with siblings like get_gambit_history or list_gambits, so a small inference remains.

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 the safe, idempotent, read-only profile, but the description adds real context: the brief is shared and cached with status 503 while regenerating, symbol caps (60 for quotes), downsampling to ~90 points, the 1m period default, limit range 1-30, and the api:read requirement. It stops short of describing failure behavior for the other views or the response shape beyond app_url.

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?

Content is dense and largely earns its place, but it arrives as a single wall of parenthetical prose covering ten views. A per-view list structure would make it far easier to scan; as written it is informative but poorly front-loaded beyond the opening clause.

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 no output schema, the description carries the burden of explaining what each of the ten views returns, and it does so. It also notes app_url in the response. What is missing is minimal — pagination/limits on other views and how views behave when data is unavailable.

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 88%, so the baseline is 3, but the description earns more by mapping parameters to views — kind only for asset_description, limit only for news, market only for breadth, period only for series — and by clarifying that crypto means Hyperliquid perps and symbols means US equities, 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 resource — the Home Market Brief plus 'the reads behind it' — and enumerates each view, so an agent knows exactly what data is returned. It does not explicitly route against overlapping siblings like get_sentiment, get_news_headlines or get_bars, so the differentiation is implicit rather than stated.

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

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

Usage is only implied through the per-view content descriptions; there is no explicit when-to-use/when-not guidance and no mention of which alternative tool to pick when the agent only needs one view. The one real guideline given — 'never mix' equity and crypto for returns/series — is a parameter constraint rather than tool selection 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, and non-destructive, so the bar is lower. The description adds the api:read scope requirement and clarifies what the numeric return values mean, which is genuine context beyond structured fields. It doesn't mention refresh cadence or staleness, so 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?

One sentence that front-loads the resource, then the returned fields, then the usage trigger and auth note. Dense but every clause carries information; the stacked parentheses and em-dashes make it slightly harder to parse than an ideal split.

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 no output schema, the description carries the burden of explaining return values and does so with field names and value mappings, plus the auth requirement. Missing only operational details such as data freshness or caching, which matter for a regime signal used before sizing.

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 and there is no parameter behavior to explain. The description correctly adds nothing here and focuses on return semantics instead.

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 ("Current global market regime classification") and enumerates the exact fields returned, including the encoding of regime_label and the +1/0/-1 mapping of regime_state. That level of specificity distinguishes it cleanly from siblings like get_sentiment or get_market_brief.

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?

"Use to adapt strategy to conditions before sizing or proposing anything" gives a concrete decision point in the workflow. It stops short of naming alternative tools (get_sentiment, get_market_brief, get_liquidation_map) or stating when this is not needed, so no explicit alternatives or exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real behavioral content: a 1–100 batch limit, per-item return fields with the exact shape of a null vote, and the api:read auth requirement. It doesn't say what happens to malformed or unknown ids, which is the only remaining gap.

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 the core statement and the id source, then the return shape, then the exclusion, then auth — a sensible order. The nested parenthetical in the second sentence is dense and slightly strains readability, but no sentence is 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 no output schema, the description supplies the return fields inline; with a single required parameter it explains the id source and limit; and it names a sibling for the adjacent question plus the auth scope. 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 already 100%, so the baseline is 3; the description still adds meaning by saying where the ids come from (get_opportunities) and what each returned item maps to. It clarifies the pairing between the single input array and the per-id output rather than repeating the pattern constraint.

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

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

The description opens with a specific verb+resource statement — the caller's own votes and saves on Today's Market opportunity cards — and names the exact id source (get_opportunities, mo_ + 32 hex). It is clearly separable from get_opportunities (card feed) and get_opportunity_detail (card content), so an agent can pick it 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?

It states the intended use (tell the user which cards in a feed they already voted on or saved) and explicitly carves out a neighbouring case it does NOT answer — Gambit tracking, routing to list_gambits. That is an explicit when-to-use plus a named alternative, leaving little 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 readOnly/idempotent/openWorld, and the description goes well beyond them: it discloses the required api:read scope and that results reflect only the caller's own source choices (an important authorization/scope nuance). It also documents the polling vs paging semantics of the cursors, which no annotation covers.

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?

A single dense paragraph with the identity front-loaded and each view labeled in call order, so scanning is fast. It is longer than typical but nearly every clause carries new information; the framing phrases ('the call for ...') are slight 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?

With 7 optional parameters, no output schema, and an openWorld hint, the description supplies return-value concepts for each view (newest posts newest-first, source list with include flag, related Today's Market cards) plus auth and pagination behavior. It stops short of describing the actual response envelope, which matters somewhat given no output schema exists.

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 already 86%, but the description adds genuine meaning: each view's behavior is explained, item_id is framed as the item's numeric id for related_opportunities, and critically it states that before + before_id (or since + since_id) must be passed as 'both halves of the last row's cursor' — a pairing rule the schema does not express.

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 identity ('YOUR curated news feed') and enumerates three distinct views with their exact contents, immediately separating it from get_news_headlines (raw headlines) and manage_news_sources (mutation). An agent knows what resource this is and what modes it exposes 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?

Maps natural-language intents ('news on my holdings', 'what's in my feed') to the correct view and explicitly excludes writes with 'changing them stays in the app'. What's missing is naming the sibling that performs that change (manage_news_sources), so routing for the write case is inferred rather than stated.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower, yet the description still adds real context: the data source (X/Twitter firehose), that results are priority-ranked, and the api:read scope requirement. It stops short of explaining what 'priority-ranked' means operationally or whether results are truncated.

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

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

Three short clauses with the resource and source front-loaded; no filler. Slightly clipped to the point that 'priority-ranked' and the parenthetical auth note read as unexplained fragments.

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 no output schema, the description should hint at the return shape (headline objects? source attribution?) and it does not. Combined with 0% parameter coverage and no sibling differentiation, it is adequate but leaves meaningful gaps for a 4-parameter read tool.

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

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

Schema description coverage is 0%, so the description must carry semantic weight; it explains symbol filtering and lookback hours but says nothing about the `limit` cap or the `priority` parameter's 1-2 range. Two of four parameters remain semantically opaque.

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 ('Recent market news headlines') and adds source/ranking context (X/Twitter firehose, priority-ranked). However, it never distinguishes itself from the nearby siblings get_news_feed and get_opportunity_news, so an agent cannot tell which news tool to pick 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?

'Filter by symbol or lookback hours' implies the two main usage modes, so an agent can infer how to narrow results. But there is no when-to-use versus get_news_feed / get_opportunity_news, and no statement of defaults or exclusions, leaving routing 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?

Goes well beyond the annotations (which already declare readOnly/idempotent/non-destructive) by disclosing the upstream source ('trigger-aware upstream, so stop orders never masquerade as plain limits'), a ~2s shared-cache staleness bound on HIP-3 rows, partial-failure signaling via hip3.failed_dexes and meta.quality='partial', and the api:read auth requirement. That is exactly the kind of failure-mode and freshness context structured fields 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 with the core statement, then layered with progressively finer detail (ordering, HIP-3, failure flags, staleness, auth). It is dense and sentence-long but nearly every clause carries operational meaning; a small deduction because the return-shape details are packed into a single run-on block rather than separated from the call rationale.

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 no output schema and no parameters, the description must carry return-shape and failure semantics, and it does: field names (is_trigger, trigger_price, trigger_condition, dex, hip3.failed_dexes, meta.quality), ordering, partial-result conditions, and the empty-list interpretation. An agent can both decide to call it and correctly interpret a degraded 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?

The tool takes zero parameters, so the baseline is 4; nothing in the schema needs disambiguation and the description does not waste space restating emptiness. It correctly implies the implicit scope (the API key's user) rather than a caller-supplied wallet 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 verb+resource with precision: 'YOUR open (resting) Hyperliquid orders (the API key's user)', scoped to both the main wallet and the agent deposit wallet. It also enumerates what counts as an order (limit, trigger/TP-SL, perp, spot, HIP-3 builder-DEX), which separates it cleanly from sibling reads like get_positions, get_fills, and get_orderbook.

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

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

Usage is implied rather than stated — the reader infers 'call this to see your resting orders'. The only guidance-like statements are about interpreting results ('empty list genuinely means no resting orders') and the api:read prerequisite. No sibling alternative is named (e.g., get_fills for history, get_positions for exposures), leaving the agent to infer routing.

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/idempotency, and the description adds substantial behavioral context beyond them: ~10-minute refresh with explicit 'do not poll faster', backfill described as by-design with section/display_reason signals, and coverage distinguishing 'empty' from 'unavailable'. This is exactly the kind of operational nuance annotations cannot express.

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 the core purpose and views before diving into field semantics. It is dense and long, but with no output schema the return-field explanations (published_at, first_seen_ts, baseline_basis) earn their 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?

For a complex read tool with 8 params, no output schema, and multiple enum modes, the description covers views, refresh cadence, fallback semantics, the null-published_at case, and the key return fields. An agent can call and interpret it without further help.

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 63% and notably the `view` param has no schema description at all, which the description compensates for thoroughly. Other params (limit, min_market_cap_usd) go undocumented in both places, keeping it below a 5.

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 (ranked, evidence-backed market observations) and enumerates the observation types. The three view modes are each explained so the agent knows exactly what 'get_opportunities' returns per mode.

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?

Clearly distinguishes view=market vs view=for_you vs view=saved and the backfill behavior, and names get_opportunity_detail as the follow-up using opportunity_id. It states a polling constraint but doesn't contrast with siblings like scan_markets or get_fired_signals, so the when-to-use-vs-alternative is incomplete.

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, non-destructive, so safety is covered. The description adds non-obvious behavior: cards missing from the live feed are served from the archive with expired=true, a semantic the agent would otherwise misread as a live signal, plus the api:read auth requirement.

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

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

Three tight sentences, front-loaded with what the card contains, followed by the archive caveat and id provenance. The payload list is dense but each item is informative, with little 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?

With no output schema, the description carries the burden of describing return contents, and it does so richly (evidence trail, invalidation conditions, optional model read, mentions, price history, market stats). An agent knows what it will get and how to interpret the expired flag.

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 already documents the pattern and an example for opportunity_id. The description only restates the provenance (from get_opportunities) and format (mo_ + 32 hex), adding marginal value over the structured field.

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 and then enumerates exactly what the card contains (evidence trail with source/observed_at, invalidation conditions, model read, mentions, price history, market stats). This is clearly distinguishable from the sibling get_opportunities, which supplies the ids, and from get_opportunity_news.

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 routes the caller to get_opportunities for the opportunity_id and warns to treat archived (expired=true) cards as historical rather than a current signal. It gives context but does not explicitly compare against alternatives like get_opportunity_news or evaluate_opportunity for related needs.

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 destructiveHint=false, so the safety profile is covered. The description adds beyond that: the api:read scope requirement, the response payload (headlines, posts, sources, times, app_url). With no output schema, disclosing the return shape is genuinely extra value.

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

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

Two sentences, front-loaded with what the tool returns and immediately followed by input provenance and format. The auth requirement is relegated to a parenthetical at the end but is short enough not to be wasteful.

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

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

For a one-parameter read-only tool with no output schema, the description covers resource scope, input format/provenance, return contents, and auth scope. Only minor gaps remain, such as ordering or volume of returned news and behavior for an invalid ID.

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

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

Schema coverage is 0%, so the description must carry the parameter meaning, and it does: it states the ID comes from get_opportunities and repeats the 'mo_' + 32 hex format. That fully compensates for the missing schema description, though it adds no further semantics such as what happens on an unknown or malformed 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 description states a specific verb+resource: news matched to one Today's Market opportunity card. Scoping to a single opportunity_id implicitly separates it from get_news_feed and get_news_headlines, though it never names those siblings explicitly, so the differentiation is inferred rather than declared.

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 helpfully says the opportunity_id comes from get_opportunities, which is real usage guidance for obtaining the input. It gives no guidance on when to prefer this over get_news_feed, get_news_headlines, or get_opportunity_detail, leaving the choice 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/no-destructive, and the description adds the non-structured requirement 'Requires api:read' plus an enumeration of the graded outcome states (played_out, invalidated, expired, active). It still omits scale/volume and pagination characteristics, but since no output schema exists the field-level disclosure is valuable.

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 every clause maps to a real output section, but it is delivered as one very long, jargon-dense sentence with nested parentheticals. 'Case auto-resolution counts' is unexplained, forcing the agent to guess at what a 'Case' is.

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 no output schema, the description does real work by enumerating the four report sections and the classification taxonomy (momentum continuation detectors like options_unusual vs. mean-reversion fades like funding_extreme/basis_dislocation/liquidation_cluster). Gaps remain around output shape and undefined 'Cases', but an agent knows what it will get and that it needs api:read.

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

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

Schema coverage is 100% with all three filters (category, detector, window_hours) described including examples and the 1-720 range, so the schema does the heavy lifting. The description adds no filter semantics or interaction notes (e.g., how the window applies to already-closed opportunities), keeping this 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 names a specific resource (an empirical scoreboard over Today's Market opportunities and tracked Gambits) and enumerates its four output areas: barrier grading, calibrated detector edge, lead-lag latency, and Case resolution counts. It is clearly a read-only analytics aggregate rather than a per-opportunity lookup like get_opportunities or get_opportunity_detail, though it never names those siblings explicitly.

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

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

Usage is only implied: the 'closed-loop empirical' framing signals this is for evaluating historical detector performance rather than fetching a live opportunity list. There is no explicit when-to-use, when-not-to-use, or pointer to the alternative tools (evaluate_opportunity, get_opportunities) an agent would otherwise weigh.

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, and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: the data is 'live', the response is ordered best-first, each level carries price/size/order-count, and '(api:read)' signals the required scope.

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

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

Two dense sentences with the purpose and return shape front-loaded; almost every clause carries information. It is slightly packed with parenthetical format detail, 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?

For a single-parameter read tool with no output schema, the description covers purpose, return structure, ordering, and the full range of valid symbol inputs. 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 description coverage is 0%, so the description carries the full burden and does so thoroughly: it explains the three accepted symbol forms (perp like BTC/HYPE, HIP-3 like xyz:TSLA, spot pair-id like @107), gives examples, and ties valid values to scan_markets. This meaningfully exceeds the raw regex pattern in the schema.

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

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

States a specific verb and resource ('The live Hyperliquid order book for one market') and immediately defines scope plus return contents (bids and asks, each level {px, sz, n}, best first). This is clearly distinguishable from siblings like get_prices, get_bars, and get_live_snapshot.

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

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

Usage is implied rather than stated: an agent can infer this is the tool for depth/liquidity inspection, and the description usefully points at scan_markets as the source of valid symbols. But it never states when to prefer this over get_prices, get_bars, or get_live_snapshot, nor any exclusions.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower; the description still adds the auth requirement ('Requires api:read') and notes the response includes app_url as a deep link. It does not discuss pagination or failure modes, but for a static read that is a minor gap.

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 the value proposition, then segmented by 'view=' markers that scan cleanly. It is dense and long for a one-parameter tool, with some nested parenthetical detail, but almost every clause conveys 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?

With no output schema, the description takes on the return-value burden and does it well, naming the specific fields (tier, display_name, per-feature caps, expires_at, meters, pending_tier_effective_at, prices). An agent can decide and call correctly without further information.

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

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

Schema coverage is 0% and the only parameter is an unlabeled enum, so the description carries the full burden — and it does, explaining what each of plan/usage/tiers returns and which is the default. This is meaningfully richer than the bare enum values.

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

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

States a specific verb and resource ('your Gambit plan, usage and limits') and then enumerates the three distinct data sets the tool returns. No sibling in the list covers billing/plan/limits, so it is unambiguous.

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

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

Directly answers the agent's likely query phrasing ('the call for "what's my plan usage"') and maps each view to an intent: plan for current tier/limits, usage for consumed meters, tiers for comparison shopping. It also excludes the mutation case ('changing the plan is done in the app'), though it does not name a sibling alternative explicitly.

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/non-destructive, and the description still adds meaningful behavior: the address is resolved from the token rather than passed in, ledger data is restricted to non-funding updates, start_time defaults to 30 days ago, each answer names the wallet and address read, and the response carries app_url. That is rich 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?

Front-loaded with the resource and then walks the views in order; nearly every clause carries information, though the long em-dash sentence listing view=portfolio ranges is dense and could be broken up. Size is justified by a five-view discriminating 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 zero-required-param, five-mode tool with no output schema, the description covers mode selection, defaults, wallet resolution, and return provenance. An agent has everything needed to pick a view 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 only 50% (only the two timestamps are documented), but the description compensates fully: it explains all five view enum values, the meaning of wallet=main vs wallet=agent, the epoch-ms format and 30-day default for start_time/end_time. An agent can invoke this correctly without opening 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 (Hyperliquid account performance/facts) and enumerates the five views with distinct semantics, so an agent knows exactly which sub-answer each view returns. It explicitly distinguishes itself from siblings by pointing to get_positions / get_account_balances for positions and balances.

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-use guidance per view (e.g. view=portfolio is 'the call for "how is my portfolio doing"'), states the default view, and routes the agent to alternatives for open positions/balances. The wallet parameter's trade-off (main vs agent deposit wallet) is also 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, non-destructive and closed-world, so the safety bar is mostly covered. The description still adds real value beyond them: a privacy/data-minimization guarantee (only symbols and coarse PnL direction sent, no sizes or values), an auth requirement (api:read), and the coverage.uncoveredInstrumentIds signal for empty results.

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

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

Front-loaded with the answer to 'what does this return,' followed by how to call it and privacy details. Dense but every sentence carries information; the parenthetical auth note and coverage field could be trimmed slightly.

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 no output schema, the description steps up by describing the three feed item types and the coverage.uncoveredInstrumentIds escape hatch, which is exactly what an agent needs to interpret empty results. It stops short of explaining what the limit parameter caps or how items are ordered.

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?

Adds genuine meaning beyond the schema: the omit-both-to-derive behavior is spelled out, holdings/watchlist semantics are contrasted ('hold' vs 'watch but do not hold'), and ticker format is specified with an example (NVDA). limit and window are left entirely to the schema, which covers window's default but not limit's intent.

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 ('what changed' feed) and enumerates exactly what composes it: symbol-tagged news with model-written digests, notable price moves, upcoming earnings. The scoping to instruments the API-key user holds or watches separates it from get_news_feed and get_watchlist.

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 describes two calling modes: no arguments derives holdings from open Hyperliquid positions, while passing holdings/watchlist controls coverage. It does not name the sibling alternatives (get_news_feed, get_tracking_updates, get_holdings) it should be preferred over, so the agent must infer the boundary.

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/idempotent annotations: it discloses the main-vs-agent wallet shape, null agent wallet semantics, the alias_of_main_wallet marker, HIP-3 cache staleness of ~2s, partial-quality failure via hip3.failed_dexes, and the api:read auth requirement. This is exactly the extra 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?

The core statement is front-loaded, but the body is a dense run of nested parentheticals covering wallet shape, ordering, HIP-3 failure modes, and cache freshness. Most details are useful, yet the packaging makes it harder to scan than it needs to be.

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?

There is no output schema, so the description carries the full burden of explaining returns, and it does: per-position fields, native-then-HIP-3 ordering, dex-prefixed symbols, and how to interpret empty versus partial results. An agent can call this correctly and interpret the response from the description alone.

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?

Zero parameters, so baseline is 4. The description still adds genuine value by explaining there is deliberately no address argument and that identity is derived from the key, which prevents an agent from hunting for a nonexistent 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 verb and resource (open Hyperliquid perp positions) and immediately scopes it to the API key's own user with no address input, which separates it from holdings/balances style siblings. It also enumerates the fields returned, so an agent knows exactly what it gets without opening anything else.

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?

Clear context is given: identity comes from the key, no address parameter, and a note that an empty list genuinely means no positions. It does not explicitly route the agent away from get_holdings or get_open_orders, so the boundary with those siblings is implied rather than 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses that trading_profile returns 404 when no profile exists, that the response carries app_url pointing at the editing Settings tab, and that the call requires the api:read scope. These are exactly the operational facts an agent needs and none are derivable 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?

It is front-loaded with the core purpose and every clause carries real information, but the body is one dense run-on with heavy parenthetical nesting that is harder to scan than a per-kind breakdown would be. Slightly trimmed formatting would make the same content easier to use.

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?

There is no output schema, yet the description fully characterizes the return payload for each kind plus the app_url field and the 404 case, and it flags the auth requirement. An agent can call this correctly and interpret the result with no further information.

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

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

Schema coverage is 0% and the single parameter is an enum, so the description carries the full burden — and it does, defining each enum value's meaning and payload in depth (raw_answers q1-q6, dna_code/archetype, derived_params such as gross exposure and max position %, hidden_rows per category, default_destination and symbol_overrides). This adds substantial meaning well beyond the bare enum list.

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

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

The description opens with a specific verb and resource ('One of YOUR preference sets, by kind') and then enumerates the three distinct kinds with the concrete fields each returns, so an agent can tell exactly what it is fetching. It is clearly separated from the sibling update_preferences, which is named for the write path.

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 the read-only boundary ('These are read-only here: the quiz, the caps, agent mode and chat execution are changed only in the app') and names update_preferences as the alternative for two of the three kinds. It also pre-empts a likely misuse of trade_routing by clarifying 'it preselects the ticket only, it never routes or places an order.'

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/non-destructive, but the description adds substantial context beyond them: the api:read auth requirement, the ~850-entry default payload size, and nuanced failure semantics — failed_dexes versus unavailable_symbols vs missing_symbols. That distinction prevents an agent from misinterpreting a transient read failure as a nonexistent symbol.

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?

Dense and front-loaded — the scope comes first, then symbol formats, then the guidance to use scan_markets. Every clause carries information, though the single unbroken paragraph packs a lot (pair-id mapping, HIP-3 keys, failure taxonomy) and could be easier to scan.

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

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

No output schema exists, so the description compensates by naming the relevant return fields (data.spot_pairs, data.hip3.failed_dexes, unavailable_symbols, missing_symbols). For a one-parameter read tool, 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 coverage is 100% and already documents the string-or-array form, so the description is not carrying the burden alone. It still adds meaning the schema lacks: which symbol notations are accepted per market type and how spot pairs map back to native HL pair ids via data.spot_pairs.

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 ('Current mid prices') and enumerates the exact asset classes covered: Hyperliquid native perps, spot assets, and HIP-3 builder-DEX perps. It is clearly distinguishable from siblings like scan_markets and search_symbols, which it names explicitly.

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 routes the agent: 'WITHOUT symbols this returns ~850 entries — prefer scan_markets for discovery and pass symbols here for targeted lookups.' It also spells out the acceptable symbol formats (BTC, HYPE/USDC, xyz:TSLA), so the agent knows both when to call it and how.

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 carry readOnly/idempotent/non-destructive/openWorld, so 'this read does not trade' is largely redundant. The description does add genuinely new behavioral context: the payload is a composite (live 24/7 metrics, cross-DEX sibling spreads, your open Gambits on those symbols, OCPI/OTPI snapshot) and Tesseract clearing is conditionally omitted unless TESSERACT_REFERENCE_FEED_ENABLED is on — a real data-availability caveat not expressible in annotations.

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

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

Front-loaded with purpose and invocation mode before the long return-value enumeration, and the enumeration is justified because there is no output schema. It is dense to the point of being a run-on, and 'This read does not trade' repeats what readOnlyHint already says.

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 no output schema, the description fully covers what comes back (quote/perp fields, cross-DEX spreads, open Gambits, OCPI/OTPI) and flags the feature-flagged omission, so an agent knows both how to call it and what to expect. The only residual gap is the preset-vs-symbols routing ambiguity noted above.

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

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

Schema coverage is 100%, so baseline is 3, and the description does enrich mandate_id (reads YOUR saved Gambit's name, interval, whitelist). However it muddies the schema by writing 'preset=ai_memory_compute (or a comma-separated symbols list such as xyz:SKHX,...)', which implies the symbol list is passed through preset when the schema has a distinct symbols parameter (maxLength 512) — an ambiguity an agent must resolve from 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 concrete resource (a 'shareable radar' over a mandate or symbol list) plus the (api:read) scope, which is specific enough to distinguish it from plain quote tools like get_live_snapshot or get_prices. It does not explicitly name a sibling it is not, so differentiation is inferred from the dual-mode framing rather than stated.

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 clear routing: use mandate_id to read your saved Gambit, or preset=ai_memory_compute for the memory/optical/AI-compute watch. It states the positive conditions for each mode but never says when to prefer this over get_mandate, get_live_snapshot, or get_sector-style siblings, nor any exclusions.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior, so the description does not need to restate safety traits. It adds useful context beyond annotations by stating the required scope '(Requires api:read.)' and indicating that readings are 'latest'.

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

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

The description is compact, front-loaded with the core data sources, and every phrase contributes either purpose, usage context, or authorization requirement. There is no wasted wording.

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 parameterless read tool with rich safety annotations, the description is nearly complete: it identifies the indexes, gives a usage context, and states the required API scope. It does not describe the return shape, which is a minor gap given there is no 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?

This tool takes zero parameters, so there are no parameter semantics to document. Per the baseline rule for parameterless tools, a 4 is appropriate.

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

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

The description clearly states the resource and even names the two sentiment indexes returned, so the tool's purpose is easy to identify. It does not explicitly contrast itself with sibling market-context tools such as get_market_regime or get_market_brief, so it stops short of full sibling differentiation.

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 phrase 'Good opening move for a market-context check' gives a clear usage context for when to call this tool. It does not name alternatives or describe when not to use it, but the intended use case is explicit enough.

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/non-destructive, yet the description adds meaningful context beyond them: the required api:account scope, the REST response shape ({ success, data }), the specific data fields to read, and the crucial constraint that the user — not the agent — must sign the Hyperliquid agent approval. That last point is a real behavioral limit an agent must know before calling.

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 and the 'call/poll after' instruction are front-loaded, and the later sentences carry load: because there is no output schema, enumerating the data.* fields and the special open_agent_setup.url semantics is necessary rather than padding. It is dense but nearly every sentence earns its place.

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

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

With no output schema, the description takes on the return-value burden and does so by listing the key data fields (next, onboarding_completed, wallet_linked, trading_profile, agent_approved, brokerage_connected) plus the special-case open_agent_setup.url. For a zero-parameter status-read tool, an agent has everything needed to call and interpret it.

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

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

The tool takes zero parameters, so there is no parameter syntax to document and the baseline is 4. The description correctly spends its words elsewhere rather than inventing parameter guidance.

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 check — what remains unfinished on the account setup — and the title 'Get account setup status' pins the resource precisely. It distinguishes itself from siblings like submit_onboarding or start_brokerage_connect by framing the tool as a read of onboarding progress. The opening phrasing is stylistic ('What is still unfinished on YOUR account') but the intent is unambiguous.

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

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

Gives concrete timing guidance: 'Call this after connecting, and poll it after the user finishes a browser step.' It also marks connect_brokerage as optional and states that Stripe billing is not on this surface, which is a useful scope exclusion. It stops short of naming a specific alternative tool for the excluded billing flow, so it is not a full when/when-not/alternatives treatment.

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 carry readOnly/idempotent/destructive hints, but the description adds genuinely new behavioral context: the required api:stock_trade scope and confirmation that it never mutates the order. The enumerated status values also set expectations for return semantics.

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 inputs, returns, and safety in four tight sentences with no wasted preamble. The final 'Read only' clause mildly restates the readOnlyHint annotation, slightly preferring redundancy for reader safety.

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 no output schema, the description explicitly names the returned fields (order_id, status, filled_units, avg_fill_price) and the status enum, and adds the auth scope. For a two-param read-only status lookup, 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 coverage is 0%, so the description must compensate. It explains the provenance of order_id (from confirm_stock_order) which is useful, but leaves account_id's meaning under-specified ('your own linked brokerage' only implies it). Partial compensation for the coverage gap.

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

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

States a specific verb and resource (get the current status of ONE order) plus scope ('at YOUR own linked brokerage'), which cleanly separates it from the plural sibling get_open_orders. An agent can identify exactly what 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?

Gives a concrete operational link: 'Pass the account_id and the order_id that confirm_stock_order returned', which tells the agent the upstream tool that produces its inputs. It lacks an explicit exclusion against alternatives like get_open_orders, but the workflow context is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, but the description adds substantive context: the HTTP 202 'pending' retry semantics for bars, the api:read auth requirement, 'same for every reader', and that the response carries app_url. These add genuine value beyond the structured flags.

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 content is dense and earns much of its space, but it's delivered as one long run-on paragraph with no structural breaks between views, and phrases like 'The same for every reader' are opaque. Front-loading the overview is good, but per-view formatting would improve scanability.

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?

No output schema exists, and the description compensates by describing the return payload per view and mentioning the app_url field. For a complex multi-view dispatch tool it's mostly complete, though the 'same for every reader' phrasing and lack of any response-shape detail leave minor gaps.

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

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

With 75% schema coverage, the description still goes well beyond it: it enumerates the interval options, explains that start/end are ISO timestamps with start < end <= now, clarifies venue reference (US equities) vs hyperliquid (perps, bare or dex-prefixed), and notes observed_at as timezone-aware. This meaningfully disambiguates the enum-driven dispatch.

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 it returns the Research page's reads for one symbol, then enumerates each view (snapshot, bars, return, trade_baseline, context, relationship_profile) with a concrete description of what each returns. This is specific verb+resource, though it doesn't name siblings like get_bars or get_live_snapshot that an agent might otherwise confuse it with.

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 per-view descriptions give clear context for which view to select (e.g., bars for chart OHLCV, snapshot as the default, trade_baseline for the last trade at or before observed_at), and the required param conditions are noted. It lacks explicit 'use X instead' routing to sibling tools, keeping it 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 establish read-only/idempotent/non-destructive behavior, and the description adds substantial context beyond them: pagination, response shapes, first_look repetition until marked seen, null gambit_changes with an error field, and api:read authorization.

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 most details are useful because there is no output schema, but the description is a single dense paragraph with long semicolon-heavy clauses. It is hard to scan and could be organized into clearer sections.

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 complex tool with no output schema, the description covers item kinds, field meanings, pagination, optional gambit_changes behavior, failure handling, and auth requirements. Little an agent needs in order 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?

The schema documents cursor and include_gambit_changes, but the description adds the missing default for limit (20), restates the 1-100 range, and thoroughly explains the semantics of include_gambit_changes, first_look, and has_more.

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, and scope: what changed across all of the user's Gambits, newest first. The phrase 'the call for what changed on my Gambits' makes the tool's role immediately distinguishable from get_gambit and get_gambit_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?

Gives a clear primary use case and explains when include_gambit_changes should be used, including what counts as a followed ticker. It does not explicitly name an alternative sibling or state when not to use this tool, so it falls short of full when/when-not 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/non-destructive, and the description adds genuinely new behavior: nulls mean the wallet isn't set up, a 404 means no agent wallet yet (setup is in the app), view=agent_wallet re-checks approval against Hyperliquid at call time, and the tool never returns keys. That is exactly the error/null/auth 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?

Front-loaded with the core purpose, then scannable per-view sentences; nearly every clause carries information. Minor deductions for a long run-on opening sentence and the fragmentary trailing 'The response carries app_url, Settings → Addresses.'

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