Gogi

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

Annotations already flag destructive/non-idempotent/open-world, and the description adds substantial behavioral context beyond them: the two-step confirm handshake, the cumulative ≤ policy max_total_capital constraint, the capital > equity hard block, warning_level thresholds, and post-success fields to verify (engine_started, is_live, symbols).

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 but front-loaded: the action and the ID-provenance caveats come first, then the confirm workflow. A few clauses restate schema content (capital_allocation definition) and could be trimmed, but nearly every sentence carries operational weight.

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, multi-step activation tool with nested risk_advanced params and an output schema, this description covers the workflow, prerequisites, guardrails, and what to verify on return. Nothing an agent needs to invoke it safely 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 baseline is 3, but the description still adds real meaning: capital comes from broker buying power and accumulates into AI Trading Power, risk_preset enumerates the same values but frames it as an override, and confirm_allocation's alias is documented. It repeats the capital_allocation semantics already present in the schema, keeping it short of 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+scope: 'Link an algorithm to a trading instance with capital allocation and start live trading.' It even distinguishes the algo_id source (create_algo / list_my_algos) from the LinkedAlgo id, which is exactly the confusion an agent would have among the many sibling algo tools.

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

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

Gives explicit when-to-use and sequencing: ask user for capital, first call with confirm_allocation=false, surface allocation_requires_confirm data, then retry with true after explicit OK. It also names the alias acknowledge_capital_risk and the hard-block condition, 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, non-destructive, open-world behavior. The description adds value beyond that by listing what is returned (indicators, S/R pivots, Fibonacci levels, geometric patterns, an analysis_steps breakdown) and by specifying overlay defaults. It does not cover latency, rate limits, or failure modes, so it is strong but not exhaustive.

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 asset coverage are front-loaded, and the closing recommendation to summarize analysis steps is actionable for presentation. It is slightly instruction-heavy for a tool description, 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?

An output schema exists, so return values need not be explained in depth, and the description still sketches them. Combined with the annotations and full schema coverage, an agent has enough to call it correctly; only invocation-edge guidance (when not to use it, limits) is absent.

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

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

Schema description coverage is 100%, so the schema already documents symbol, feature, lookback, overlays, and timeframe. The description only restates the default overlay ("Default overlay is patterns"), adding negligible meaning beyond the schema. Baseline 3 is appropriate.

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

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

Specific verb ("Detect chart patterns and support/resistance") plus the resource and enumerated asset classes (stocks, crypto, FX, commodities, indices, futures). It also names the sibling it is not (get_market_data for quotes + indicators), so an agent can separate the two 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?

Names an explicit alternative and its use case ("Use get_market_data for quote + indicators"), and clarifies the default overlay, which guides invocation. It stops short of stating when this tool is the wrong choice or listing prerequisites, so it is clear context rather than full when/when-not coverage.

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, readOnlyHint=false, and idempotentHint=false. The description adds crucial context: the timing constraint (before in-app confirmation) and failure conditions for executed/expired/resolved trades. This goes beyond annotations, though it doesn't explain the exact impact of cancellation or whether it can be undone.

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

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

Two concise sentences, front-loaded with the core action and immediately followed by the key limitation. No wasted words.

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

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

Complete for a simple cancel operation: purpose, timing, and exclusions are clear. The presence of an output schema means return values needn't be explained. Minor gap: no guidance on error handling or whether the trade ID can be reused.

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 parameter is fully documented in the schema (pending_trade_id with its origin). The description adds no extra parameter details, which is acceptable given the high coverage.

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

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

Specific verb (cancel) and resource (pending trade) with an explicit precondition ('before in-app confirmation'). This distinguishes it from sibling tools dealing with executed trades or status queries.

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 states when the tool works (pending trades before confirmation) and excludes already executed, expired, or resolved trades. However, it does not name alternative tools (e.g., use get_pending_trade_status to check first) or describe when cancellation is appropriate versus other actions.

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 destructive=true and non-idempotent, but the description adds substantial context beyond them: the confirm_close_all requirement for multi-position closes, the pending_confirmation/Activity Confirm flow when mcp_require_confirm is true, and the important distinction that broker flatten does not close algo-tracked engine positions.

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 slightly long, but front-loaded with the core action and scope. Every sentence carries routing or gating information; little is wasted, though it packs a lot into one paragraph.

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, confirm-gated mutation tool with 5 params, an output schema, and rich annotations, the description covers the confirmation flow, cross-tool pitfalls, and the flatten-vs-partial distinction. 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%, so the baseline is 3. The description goes further by explaining the symbol-omission flatten behavior, the confirm_close_all gating condition, and the side requirement when multiple sides exist, adding usable semantics over the schema text.

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

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

States a specific verb+resource ('Close open broker positions on an enabled Connections account'), scopes it ('no trading instance required'), and enumerates supported asset classes. It distinguishes itself from siblings like execute_trade and delete_instance by naming them 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?

Gives explicit when-to-use ('Prefer this over inventing sell quantities'), when-not-to-use ('Omit symbol to flatten'), and routes the agent to execute_trade/delete_instance for algo-tracked positions. Condition for side and confirm_close_all is 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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds nothing about side effects, permissions, rate limits, or — crucially — whether the created algorithm is started or left inactive, which is exactly the ambiguity created by the presence of create_and_start_algo and activate_algo.

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 anti-invention rule is front-loaded and clear, but the same warning ('do NOT invent EMA 9/21' / 'never always the same MA pair' / schema's 'Never invent EMA 9/21') recurs across description and schema. The template-selection clause is useful but wordy, so structure is adequate rather than tight.

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

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

For a nested-schema mutation tool with an output schema, the essentials are covered (required params, indicator shape, the no-invention rule). What is missing is its position in the algorithm lifecycle relative to create_and_start_algo, activate_algo, and run_backtest, which is the main remaining ambiguity.

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

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

Schema description coverage is 100% and the nested strategy_params shape is fully documented, so the baseline is 3. The description's instructions about indicator choice are behavioral guidance rather than additional parameter semantics, and it says nothing about name, symbols, or timeframe.

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: 'Create a trading algorithm strategy with technical parameters.' An agent can tell it apart from update_algo or delete_algo. However, it never distinguishes itself from the close sibling create_and_start_algo, leaving the create-vs-create-and-start distinction to inference.

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?

Strong when/when-not guidance: 'Use the strategy the user (or this conversation) specified' and 'If indicators/entry conditions were not specified, ASK — do NOT invent.' It also scopes the one exception where the agent may pick freely. It does not, though, address when to use this tool rather than create_and_start_algo or activate_algo.

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/openWorldHint/non-idempotent; the description adds substantial behavior beyond that: a two-phase confirmation flow (first confirm_allocation=false, then retry with true after explicit OK), the allocation_requires_confirm response fields to surface, the policy max_total_capital ceiling on cumulative live allocation, and the risk-override semantics. This is exactly the context the annotations cannot convey for a live-money mutation.

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 constraint is front-loaded in sentence one, but the body is a dense wall of text that repeats the 'do not invent EMA 9/21' instruction already present in the schema, and stacks many workflow rules without visual grouping. Content mostly earns its place, yet the piece would be more usable if structured into labeled steps.

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

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

For a high-complexity, 12-parameter mutation with nested objects, an output schema already covers return values, and the description fills the remaining gaps: preconditions, confirmation choreography, policy limits, and risk precedence. Nothing an agent needs to invoke 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: confirm_allocation is tied to the two-step confirmation flow, broker_account_id must be the integer id from list_brokers (not the external account number), and capital_allocation must come from broker buying power. The risk-vs-risk_preset override relationship is explained, though a few optional params (instance_name, risk_advanced specifics) are 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?

The opening sentence 'Create algo + instance + start trading' states a specific composite action across three resources, which cleanly distinguishes it from the single-purpose siblings create_algo, create_instance, and start_instance. An agent can tell what this tool produces without opening the schema.

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

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

The description gives explicit when/when-not rules: call list_brokers first and get an explicit choice before passing broker_account_id, prefer paper/demo unless the user confirms live, ask rather than invent indicators, only pick a template when the user explicitly invites it, and prefer custom risk numbers over presets. It also names the alternative path (risk_preset) and the condition that selects it.

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

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

Annotations declare the write/non-idempotent/open-world profile. The description adds crucial behavioral context beyond them: default status is pending (not live), start_immediately is the only path to immediately live trading, and the paper-vs-live constraint ('each account is paper OR live, never both'). That is exactly the kind of state/side-effect guidance 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 imperative verb and workflow, and every clause carries routing or constraint information. Dense but earns its length; the label-format aside ('broker · paper|live · •••••last5') is slightly verbose but justified by the need to disambiguate accounts.

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 creation tool with a 4-param schema and abundant siblings, the description supplies the full workflow: prerequisite (list_brokers), selection rule, parameter origin, default state, and the alternative start path. Output schema exists, so return values need not be explained.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by clarifying that broker_account_id is the internal integer id from list_brokers, NOT the broker's external account number — a distinction the schema hints at but the description reinforces in operational context.

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

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

States a specific verb and resource ('create a trading instance') and immediately scopes it ('bound to a broker account the user selected'). This distinguishes it clearly from create_algo, create_and_start_algo, and list_instances, which are nearby siblings.

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

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

Explicitly prescribes the workflow ('ALWAYS call list_brokers first... then pass that row's integer id'), names the alternative start path (start_instance after activate_algo), and states the condition selecting start_immediately=true ('only when the user wants live trading started now'). Nothing is left to inference.

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

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

Annotations only declare the safety profile (destructiveHint false, idempotentHint false); the description adds behavior they cannot express: the saved algorithm is preserved, the action is reversible, and deactivation does not flatten broker exposure. That last point is a high-value operational caveat.

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 sentence with the core action front-loaded, followed by sequencing, reversibility, and risk in a logical order. 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 an output schema present, return values need not be described. Purpose, sibling routing, reversal path, and the exposure caveat are all present, leaving nothing an agent needs to call this correctly.

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

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

Schema description coverage is 100% and both params (algo_id, instance_id) are documented in the schema. The description adds no further meaning about the identifier semantics or constraints, so the baseline 3 applies.

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

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

States a specific verb pair (deactivate and unlink), names the resource (algorithm) and scope (from a trading instance), and clarifies the non-deletion semantics that distinguish it from delete_algo. An agent can differentiate it from siblings without opening a schema.

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

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

Explicitly sequences the tool relative to siblings ('Use this before delete_algo'), names the reversal path (activate_algo), and gives a precondition warning (inspect open positions first). Both when-to-use and the alternative are covered.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so safety is partly covered. The description adds genuinely new behavior: the confirm=true gate and the constraint that a linked algorithm must be deactivated first to avoid disrupting execution history. Return format is not described, but an output schema exists, so this 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?

Three tight sentences, front-loaded with the core action, then the confirm requirement, then the linking constraint. Every sentence earns its place with no 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?

With an output schema covering return values and annotations covering the safety profile, the description supplies the key operational prerequisites (confirm, linked-instance restriction) an agent needs to call it correctly. It stops short of naming alternatives, but nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so both parameters are already fully documented in the schema (algo_id sourcing, confirm meaning). The description restates 'requires confirm=true' but adds no syntax, format, or semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb (Archive) and resource (a saved algorithm owned by the user), which is precise and actionable. It does not name or contrast against siblings like update_algo or deactivate_algo, and it quietly reconciles the 'delete_algo' name by describing an archive operation. Clear purpose, but no explicit 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?

It gives clear context for use: an algorithm must not be linked to a trading instance (until deactivated) and confirm=true is required. This states a 'when-not' condition. However, it never names an alternative tool (e.g., update_algo or delete_instance), so the routing is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, but the description adds substantially more: slot freeing behavior, the stop-vs-delete distinction, the exact error_type returned, and the critical warning that deletion closes all open positions. This goes well beyond what annotations provide.

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

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

Front-loads the core action, then layers the conditions and error path efficiently. Dense but each sentence earns its place; slight density makes it less scannable than ideal 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?

Covers the mutation's destructive nature, the two guard flags, the exact error contract, and the required user-confirmation workflow. With an output schema present, return values needn't be explained, and no gaps remain for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning not in the schema by explaining WHEN each flag is needed (force for live, confirm_close_positions for open positions) and the ordering of the recovery flow, which the schema's terse descriptions don't 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?

Clear verb+resource: 'Permanently delete a trading instance and free a slot (max 10 per user).' It explicitly distinguishes from the sibling stop_instance with 'Stop ≠ delete,' so the agent can tell it apart without inspecting schemas.

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

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

Provides explicit conditions and alternatives: use force=true for live instances, and a full three-step recovery path (show open_positions, warn, retry with confirm_close_positions=true after explicit OK). This is about as prescriptive as usage guidance gets.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds genuine value by flagging that the action 'may be irreversible' and that policy and in-app confirmation still apply when enabled, which is not derivable 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?

Three tight sentences, front-loaded with the action and venue, followed by the prerequisite step and the irreversibility caveat. No filler; each sentence carries distinct information.

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

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

For a destructive, non-idempotent mutation tool, the description covers prerequisites, venue scope, and irreversibility, and an output schema exists so return values need not be explained. Only a clearer statement of what confirmation/policy entails is missing.

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

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

Schema description coverage is 100%, so side, ticker, platform, contracts, and price_cents are already documented with types, enums, and ranges. The description references verifying account, side, contracts, and price but adds no format or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (place) and resource (prediction-market order) with explicit venue scope (Kalshi or Polymarket). The 'prediction-market' qualifier cleanly separates it from the generic execute_trade sibling without needing to open 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?

Explicitly routes the agent to search_predictions first to identify the current contract, which is a concrete usage precondition. It also lists what to verify before executing. It stops short of naming when NOT to use this or contrasting directly with execute_trade, so not a full 5.

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

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

Adds substantial context beyond annotations: it discloses the confirm-flow (pending_confirmation, Gogi Activity, poll get_pending_trade_status), that mcp_require_confirm=false may place a REAL order immediately, and the LIVE vs direct execution semantics. This is exactly the behavioral detail 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-loads the core action and the mode branch clearly, but the description is fairly dense with multiple conditionals packed into long sentences. Every clause is useful, but structure could be slightly more 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?

Given a destructive, open-world, money-moving tool with a rich output schema and a confirm flow, the description covers prerequisites, execution modes, confirmation semantics, and the sibling alternative. Nothing an agent needs to call it safely 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% (baseline 3), and the description further clarifies the instance_id meaning (present=live algo-tracked, absent=direct on-demand) and the confirm flag behavior, adding meaning beyond the schema. It doesn't elaborate on linked_algo_id or broker_account_id beyond schema, so not 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 (execute/propose) and resource (money-moving trade on a connected broker), and distinguishes the two execution modes (live algo-tracked via instance_id vs. direct on-demand). It also distinguishes from close_positions by naming that tool explicitly for the flattening use case.

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

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

Explicitly prescribes calling get_policy, get_portfolio, and get_platform_disclosure first, prefers paper accounts, and routes to close_positions rather than inventing a sell quantity. The when-to-use-vs-alternative guidance is essentially complete.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorld, so the safety profile is covered. The description adds the ownership constraint (only the user's own algorithms are retrievable), which is real behavioral context beyond the annotations, though it does not discuss auth requirements or error behavior.

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 tight sentences with zero filler, and the core action is front-loaded before the routing hints. Every 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 an output schema present and complete annotations, the description need not explain return values. For a single-parameter read tool, the stated purpose, ownership scope, and sibling routing are sufficient to invoke it correctly.

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

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

Schema coverage is 100% and the single algo_id parameter is already documented as coming from list_my_algos. The description restates the same sourcing hint without adding format, type, or validation detail, so this is the baseline 3 when the schema carries the load.

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

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

States a specific verb (Retrieve) plus resource (one saved algorithm) with scope qualifiers (owned by the user, by ID). It explicitly contrasts itself with the sibling get_linked_algo, so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit prerequisite route ("Use list_my_algos first when the ID is unknown") and names the alternative tool for a different scenario ("use get_linked_algo for an instance-specific runtime copy"). This is textbook when/when-not/alternatives guidance.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds a meaningful access-scope constraint that annotations do not cover: the run must belong to this user's agent, which tells the agent an ownership check can fail.

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, front-loaded with the action and keyed on the required parameter, with no filler. It is appropriately sized for a trivial single-parameter lookup, though 'details' stays slightly vague.

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

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

The tool is simple, has an output schema so return shape needn't be described, and the description states the one non-obvious constraint (ownership). Little else is required for an agent to invoke it correctly.

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

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

Schema description coverage is 100% and the schema already explains run_id comes from run_backtest or list_backtest_runs, so the baseline is 3. The description only reinforces the ownership condition on the id rather than adding format or validation detail beyond the schema.

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

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

States a specific verb and resource ('Get details for a backtest run') and scopes it by run_id, which cleanly distinguishes it from the sibling list_backtest_runs. It does not name the alternative tool explicitly, but the singular/plural contrast is obvious.

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

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

Usage is implied - fetch a single run once you have its run_id - and the ownership constraint hints at a precondition, but there is no explicit when-to-use versus list_backtest_runs or run_backtest guidance in the description itself.

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 safety profile is covered. The description adds real behavioral context beyond that: output varies by feed type (FMP-backed financials/insider/congress data vs. a text preview for uploaded files), which helps the agent anticipate 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?

Two sentences, front-loaded with the core action and scope, then the query requirement and return behavior. No filler sentences.

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

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

With an output schema present, the description needn't detail return fields, and it correctly summarizes the divergent return behavior across feed types. It is essentially complete for a two-parameter read tool, with only discovery/prerequisite guidance absent.

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 a concrete format example ('e.g. AAPL') for the query ticker and clarifies that query values map to feed types (marketplace vs. uploaded file id). That is modest but genuine added meaning.

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 ('Query') and resource ('subscribed marketplace data feed') scoped by feed_id, which cleanly distinguishes it from the sibling list_data_feeds. An agent can tell it retrieves data for one feed rather than enumerating feeds.

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 conveys the mechanics of usage (pass a ticker in query for marketplace feeds) and implies different behavior for uploaded file ids, but never states prerequisites or names the alternative (e.g. list_data_feeds) for discovering feed_ids. Usage context is implied rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real context beyond that: the instance must be 'live' and 'owned by this agent', and it discloses inheritance semantics ('mcp_require_confirm (null=inherit)') plus an 'effective_confirm' resolution field, which is genuine behavioral detail about how the value is computed.

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 that front-loads the verb and resource before the field list; nothing is filler. Slightly list-heavy but every clause maps to a real returned element.

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

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

With an output schema present, return values need not be spelled out, and annotations cover safety. Parameters are fully documented in the schema and the scoping/auth context is given, so an agent has what it needs; only the when-to-use framing against update_linked_algo is missing.

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

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

Schema coverage is 100% and both parameters (instance_id, linked_algo_id) carry their own descriptions naming list_instances as the source. The description adds the 'live instance owned by this agent' scoping constraint on instance_id but nothing on the ID format, so the schema still does the heavy lifting – baseline 3.

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

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

States a specific verb ('Read') plus the exact resource ('a LinkedAlgo on a live instance owned by this agent') and even enumerates the contents returned (parameters, capital, symbols, confirm flags). An agent can immediately distinguish it from the write sibling update_linked_algo.

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 resource ('read a linked algorithm') but the description never states when to reach for this versus update_linked_algo or how it fits relative to get_portfolio/list_my_algos. No exclusions or prerequisites are given, so guidance is only inferable from the name.

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 behavioral context beyond the annotations: 'No broker account required' (auth/prerequisite), the fact that technicals default to a 1day timeframe, and the exact contents returned. Slightly weakened by the tension with readOnlyHint=false, which declares a non-read-only operation for what the description presents as a pure data retrieval.

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 but well front-loaded — the snapshot purpose and asset coverage come first, then ticker syntax, then routing exclusions. Every sentence carries information; it is on the long side but not padded.

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

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

With an output schema present, the description need not explain return values in detail, yet it still summarizes them; annotations cover safety and the schema covers both parameters. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value on top: the timeframe default ('default 1day') is not in the schema, and it clarifies that slash ticker forms are accepted while also listing concrete symbols per asset class.

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 ('FMP market snapshot') and enumerates the covered asset classes plus the return payload. It explicitly differentiates itself from siblings by naming get_data_feed and analyze_chart_structure, so an agent can route correctly 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-not guidance with named alternatives: 'Not Marketplace SKUs — use get_data_feed for insider/congress/financials-pro' and 'For chart patterns / S/R geometry use analyze_chart_structure.' This is the full when/when-not/alternatives 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, so the safety profile is fully covered by structured data. The description adds the status vocabulary (pending, executed, cancelled, expired, failed), which tells the agent what outcomes to expect, but says nothing about polling cadence, expiry timing, or what happens if the ID is unknown. Modest added value above 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?

A single front-loaded sentence with the action and resource leading and the status enumeration trailing as a parenthetical. Every clause earns its place, though the dense parenthetical list makes the sentence slightly harder to parse than a clean two-sentence split 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?

With an output schema present, the description needn't explain return values, and annotations cover the safety profile. For a one-parameter, idempotent status-check tool the definition is nearly sufficient; only the lack of guidance on repeated polling or handling an unknown/stale ID keeps it from being fully 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?

There is a single parameter at 100% schema description coverage, and the schema already explains it is the 'ID from execute_trade pending_confirmation'. The description adds no additional syntax, format, or provenance detail beyond that, so the baseline of 3 for schema-carried semantics applies.

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

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

States a specific verb and resource ('Check status of a pending MCP trade') and scopes it to the in-app Confirm lifecycle, which is far more informative than the bare title. It doesn't explicitly name the sibling it complements (list_pending_trades) or contrast polling a single trade vs listing all pending trades, so it stops short of the sibling-differentiation bar.

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 'awaiting in-app Confirm' implies the usage context (a trade handed off for approval that may not yet be settled), which is useful implied guidance. However there is no explicit when-to-use, no when-not-to-use, and no routing to list_pending_trades or execute_trade, so the agent must infer the trigger condition.

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 real content context beyond the annotations: the disclosure is mandatory, it concerns agent-action liability, and it explicitly disclaims investment advice. That tells an agent what it is retrieving and why it matters. It does not explain the unusual readOnlyHint=false on a getter, leaving 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 verb and resource, followed by the trigger condition. The trailing liability clauses are dense and read more like document content than invocation guidance, but they are short and earn their place as disclosure substance.

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

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

An output schema exists, so return values need not be described, and the description covers purpose, timing, and nature of the content. It could say whether the agent must surface the text to the user, which is the one operational detail left implicit.

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 nothing for the description to clarify. No parameter-related omissions exist.

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 ('Return') and a precisely named resource ('Gogi's mandatory trading / MCP risk disclosure'). No sibling tool in the list does anything similar, so an agent can distinguish it immediately.

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

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

'Call this when connecting or before trading' gives explicit triggering conditions, which is more than most siblings provide. It stops short of stating when not to call or naming an alternative, but no plausible alternative exists for a disclosure endpoint.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context beyond annotations: it explains that the policy has a default mcp_require_confirm setting and that LinkedAlgo overrides are scoped to a single live binding, which is important for interpreting results correctly.

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 zero waste, front-loading the primary fetch purpose before explaining override semantics. The second sentence is somewhat cryptic for readers unfamiliar with 'mcp_require_confirm', but every clause carries functional information.

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

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

Given the tool has no parameters, rich annotations, and an output schema, the description need not explain return values. It adequately covers what is fetched and the key override scoping rule, though it stops short of describing what a policy broadly contains or when an agent should call 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 accepts zero parameters, so per the rubric the baseline is 4. There is no parameter information to add, and the description does not need to compensate for schema gaps.

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 ('Fetch') and resource ('global policy constraints plus per-live-instance HITL/AITL overrides'), clearly distinguishing this tool from siblings like get_linked_algo or get_platform_disclosure. However, it leans on domain jargon (HITL/AITL, mcp_require_confirm, LinkedAlgo) that an agent may not fully parse, and it does not explicitly contrast itself with the closest sibling.

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

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

Usage is only implied: one would call this to learn the agent's policy constraints, but the description never states when to use it (e.g., before executing a trade) or when not to. It hints at scope via 'LinkedAlgo overrides apply only to that live binding' but offers no actionable guidance or named alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful scope fact that it aggregates across multiple connected brokers and wallets, but says nothing about auth/permission requirements or pagination/limits. This is adequate but modest value beyond the annotations.

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

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

Two sentences, zero waste, with the resource scope front-loaded and the routing hint immediately after. Every 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?

An output schema exists, so return values need not be explained in prose. With read-only annotations covering safety, a clear scope statement, and explicit sibling routing, an agent has everything needed to select and invoke 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 semantics to document; the baseline for a 0-param tool applies. Nothing in the description misleads about inputs.

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

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

States a specific verb (Get) and resource (portfolio), then enumerates exactly what it returns: account-level balances, equity, buying power, positions, and Web3 wallet holdings across brokers and wallets. It also differentiates from the sibling get_positions, so an agent can distinguish it without opening any schema.

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

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

Explicitly names the alternative (get_positions) and the condition that selects it ('when you only need normalized open exposure'). This tells the agent both when to use this tool and when to route elsewhere.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and side-effect profile is fully covered. The description adds the scoping context (brokers, normalization) which is useful, but doesn't disclose return format, pagination, or broker connection requirements. With annotations carrying the safety burden, a 3 is appropriate.

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

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

Two sentences with zero waste. The first sentence states the core capability, and the second immediately clarifies scope relative to the sibling. Front-loaded and efficient.

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

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

For a zero-parameter read tool with an output schema, the description is nearly complete: it states what is returned and clarifies the scope boundary against get_portfolio. With annotations covering safety and an output schema covering return values, little else is needed. The main gap is not stating whether this aggregates across all brokers by default or requires broker 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?

With zero parameters, the baseline is 4. There is no parameter information needed or provided, and the description correctly focuses on what the tool returns rather than inputs. No schema compensation is 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 ('Get') and resource ('normalized current open positions and exposure across connected brokers'), and explicitly distinguishes itself from the sibling get_portfolio by scoping what it does not cover. An agent can tell it apart from get_portfolio without inspecting 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?

Names the sibling alternative (get_portfolio) and clarifies the boundary by stating it 'does not replace account balances or wallet holdings.' This gives clear context for when this tool is the right choice. However, it doesn't specify the positive condition that selects this tool over get_portfolio (e.g., 'use this when you only need position exposure').

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, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results are limited to non-terminal states (completed or running) and span four distinct channels (MCP, chat, voice, API), which the agent could not 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?

Two sentences, zero filler, front-loading what the tool returns before the routing guidance. Every 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?

An output schema exists so return values need no explanation, annotations cover the safety profile, and the single parameter is fully documented. The description supplies the remaining scope and routing context, leaving nothing an agent needs to call it correctly.

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

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

Only one parameter (limit) and schema description coverage is 100%, so the schema already documents default (20) and max (100). The description adds no parameter-level detail, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (list) and resource (backtest runs) with clear scope: recent runs in completed or running state, across MCP, chat, voice, and API. An agent can distinguish this listing tool from get_backtest_run and run_backtest 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 to alternatives: get_backtest_run for a single run's details and run_backtest to start a new run. This names both the read-alternative and the write-alternative with the conditions that select them.

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/destructiveHint=false, so safety is covered. The description adds real behavioral context beyond them: empty-state handling ('If none connected, send them to https://gogi.ai/voice-agent'), a guard against fabrication ('Do not invent account IDs'), and the display contract for results. A minor gap is that it doesn't address caching or refresh behavior, but this is well above the annotation baseline.

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 scope before the sequencing instruction, and every clause carries a distinct directive (ordering, display, follow-up question, preference, fallback, anti-hallucination). It is dense and long for a zero-parameter read, with some instructional overlap, but nothing is pure 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?

No parameters, full schema coverage, annotations present, and an output schema exists — so return values need not be explained. Within that context the description is more than sufficient, covering scope, ordering, presentation, and the empty case.

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

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

The tool takes zero parameters, so the baseline is 4. The description does explain a related machine field (the integer `id` used as broker_account_id elsewhere) and warns against verbalizing it as a 'Gogi ID', which is useful cross-tool semantics even though it isn't a parameter of this call.

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

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

States a specific verb and resource ('List ALL connected broker accounts and wallets') and immediately narrows scope with '(Alpaca, TradeLocker, Kalshi, Coinbase, etc. — never Alpaca-only)', which distinguishes it from any broker-specific sibling. An agent can tell 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?

Explicitly names the prerequisite sequence: 'Call BEFORE create_instance / create_and_start_algo / execute_trade / close_positions.' It also states the downstream step (ask the user which account, then pass that account's id as broker_account_id), so both when-to-call and what-to-do-next are covered. Exclusions are implicit in the ordering constraint but the guidance is unusually complete.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered and the description does not need to restate it. The description adds the useful detail that results span plan/marketplace/user-upload sources, but says nothing about auth requirements, rate limits, or result size.

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 sentence with zero waste, front-loading the action and then the result scope. Nothing could be removed without losing information.

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

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

For a zero-parameter read-only list tool with an output schema and full annotation coverage, the description is nearly sufficient. The only minor gap is that it does not contrast with the singular get_data_feed sibling, leaving list-vs-get routing to be inferred.

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; there is no parameter semantics for the description to clarify. The description appropriately focuses on what is returned rather than inventing input options.

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 ('List') and resource ('data feeds') and clarifies the scope with the parenthetical breakdown (plan, marketplace subs, user uploads). It does not explicitly name the singular sibling get_data_feeds/get_data_feed, but 'List all' implicitly distinguishes it from a single-feed retrieval.

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

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

The description implies the usage context by enumerating the feed categories returned, but it never states when to call this versus get_data_feed or other catalog tools. No exclusions, prerequisites, or alternatives are given.

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, and non-destructive semantics, so the safety profile is free. The description goes further with real operational context: pending/stopped means not live yet, and stopped/pending instances still count toward the max-10 limit until delete_instance — a quota behavior no annotation could convey.

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

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

Four short sentences, each carrying a distinct payload: what is returned, when to call it, the id-type trap, and the quota rule. Nothing is filler and the constraining facts are front-loaded.

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

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

An output schema exists, yet the description still supplies the id-disambiguation and max-10 quota rules an agent needs before mutating instances. Combined with the annotation-covered safety profile, nothing material is missing for a zero-argument 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?

The tool takes zero parameters, so the baseline is 4. The description's enumeration of returned fields is output information rather than parameter meaning, so there is nothing additional for it to convey here.

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

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

States a specific verb and resource (list the user's trading instances) and enumerates the returned fields id, name, status, is_live, broker. This cleanly separates it from siblings like list_my_algos, list_brokers, and list_backtest_runs.

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

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

Explicitly instructs the agent to call this before start_instance / stop_instance / activate_algo / delete_instance in order to confirm instance_id (not algo_id). That is a named when-to-use condition plus a named pitfall, which is the strongest form of routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint. The description adds value beyond them by disclosing what is returned (stable algo_id values, strategy summaries, symbols, timeframe, archived flag), which the agent needs to know it can resolve a name to an ID. It omits permission/rate-limit context, 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?

Three tight sentences, front-loaded with purpose, then return shape, then when-to-call. No redundant restatement of the name or title; every sentence carries distinct information.

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

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

For a simple read-only list tool with an output schema and full annotation coverage, the definition covers purpose, routing, and return content adequately. Minor gaps (e.g. any pagination or empty-result behavior) are mostly handled by the output schema, but not entirely addressed.

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

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

With 100% schema coverage on a single parameter, the schema already documents include_inactive and its default. The description's reference to a returned 'archived' flag is tangentially related but does not clarify the filter parameter itself, so baseline 3 applies.

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

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

States a specific verb ('List') and a scoped resource ('saved algorithms owned by the user'), which distinguishes it from the many other algo-related siblings. The ownership qualifier makes the scope unambiguous.

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

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

Explicitly routes the agent: 'Call this before update_algo, delete_algo, or activate_algo when the user names an algorithm rather than supplying its ID.' This names the alternatives and the exact condition that selects this tool over them.

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 read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description's contribution is the 'awaiting in-app Confirm' state qualifier, which usefully signals that returned items are blocked on human action, but it adds nothing about freshness, scope limits, or whether the list can be empty.

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 short sentence, front-loaded with the verb and resource and with no filler. Every word 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?

For a zero-parameter, read-only list with an output schema describing the return shape, the description is nearly sufficient. The only gap is the absence of a pointer to the sibling that returns the status of an individual pending 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?

The tool takes no parameters, so the baseline is 4; there is nothing for the description to disambiguate. No parameter meaning is missing because none exist.

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 (List) and resource (pending trades) and narrows scope with 'for this agent awaiting in-app Confirm', which helps separate it from the generic read siblings. It does not explicitly distinguish itself from get_pending_trade_status, which an agent could easily confuse with it.

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 'awaiting in-app Confirm' implies the scenario (trades needing the user's confirmation before execution), but the description never says when to call this versus get_pending_trade_status or execute_trade, nor does it state any prerequisite. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, but the description adds important context: records are permanent, retained indefinitely, visible in the UI activity feed, and repeated calls create duplicate timeline records. It also warns that redundant logging creates database spam, which is valuable behavioral guidance beyond the annotations.

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

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

The description is front-loaded with the core write behavior and then cleanly separated into WHEN TO USE and WHEN NOT TO USE. Every sentence earns its place by clarifying permanence, duplication, or correct usage.

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

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

With an output schema present, return values need not be explained. Annotations cover the safety profile, while the description fully covers when to use the tool, when not to, and the consequences of misuse.

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

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

Schema description coverage is 100%, so the input schema already documents event_type, payload, and description. The description adds usage context for event_type via examples like inner thoughts, reasoning steps, and milestones, but does not add syntax or format details beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: logging and persisting a custom activity event to the backend database and UI timeline. It also distinguishes itself from siblings by naming execute_trade, close_positions, and execute_prediction as tools that already emit their own events.

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?

Contains explicit WHEN TO USE and WHEN NOT TO USE sections. It names the alternative behavior directly, explaining that standard action tools automatically emit timeline events and should not be duplicated.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it returns metadata plus a capped UTF-8 text preview, and binary files yield metadata only, which tells the agent what to expect from the call. It does not cover error behavior for non-owned or missing files.

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 tight sentences with the primary action and ownership constraint front-loaded, followed by the return-shape caveat. Every clause earns its place with no 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?

With rich annotations and an output schema present, the description need not explain return values, yet it helpfully summarizes them anyway and states the ownership requirement. Only a note on failure modes (missing file, foreign ownership) is absent, which is minor for a simple 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 100% with a single parameter, so the schema already documents file_id, its origin (list_data_feeds), and the ownership constraint. The description only restates 'owned by this agent', adding no format, casing, or sourcing detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (read) and resource (a user-uploaded file owned by this agent), which clearly separates it from siblings like get_data_feed, get_market_data, and list_data_feeds. The description also previews the return shape, so an agent can distinguish it from list/read tools 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?

Usage is implied rather than stated: the schema notes file_id is 'returned by list_data_feeds', which hints at a discovery-then-read flow, but the description itself offers no explicit when-to-use guidance or alternatives. No exclusion criteria (e.g., when to use list_data_feeds or get_data_feed instead) are given.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, so the agent knows this is a non-idempotent external write. The description adds genuinely useful context the annotations lack: results location (Backtesting tab and Activity feed) and a Pro plan requirement. It still omits whether a run is asynchronous, whether it consumes quota, or how long results take, which matters for a backtest.

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 sentences, front-loaded with the action, then the outcome location, then the gating requirement. Every sentence earns its place with no filler.

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

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

With an output schema present, return-value explanation is not needed, and annotations cover the mutation profile. What's missing is async/sync behavior and typical duration for a 13-parameter, possibly long-running backtest, plus routing to the get_backtest_run/list_backtest_runs siblings.

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

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

Schema description coverage is 100%, so every one of the 13 parameters is documented in the schema, making a 3 the baseline. The description adds no parameter detail at all, and notable nuances (respect_policy defaults false/opt-in, symbol cap of 10, timeframe units) are all already 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 (run) and resource (policy-aware historical backtest), scoped to 'this agent', which distinguishes it from sibling read tools like get_backtest_run and list_backtest_runs. However, it doesn't reference those siblings or explain what 'policy-aware' means beyond the name.

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

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

Gives an implied gating condition ('Requires Backtesting Pro') which tells when it will succeed, but provides no guidance on when to use this vs the get_backtest_run/list_backtest_runs siblings or prerequisites like needing a saved algo.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful non-annotation context: the markets are public and no broker account/authentication is required, which is the key operational trait an agent needs before invoking 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?

Three short sentences with zero filler. The core action and venue scope are front-loaded, followed by the auth precondition and the sibling routing, which is the right priority order.

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

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

An output schema exists, so return values need not be explained. For a two-parameter search tool, the description covers scope, authentication requirements, and the alternative for write actions — nothing 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?

Schema description coverage is 100%, and the schema already documents both 'query' (text or ticker) and 'platform' (venue filter with enum, omit to search both). The description adds no additional parameter semantics, so the baseline 3 applies.

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

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

States a specific verb ('Search') and resource ('public prediction markets'), names the two venues covered (Kalshi, Polymarket), and explicitly routes betting to the sibling execute_prediction. An agent can distinguish this read/search tool from execute_prediction without opening either schema.

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

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

Gives a clear precondition ('No connected Kalshi/Polymarket broker account required') and names the alternative for the written action ('To place a bet, use execute_prediction with a connected account'). It stops short of stating explicit when-not conditions, such as cases where a private/account-scoped search would be needed, but 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 destructiveHint=true, openWorldHint=true, and non-idempotency. The description adds the critical consequence that this 'can enable live trading', which conveys real-world stakes beyond the annotation flags. It doesn't explain the non-idempotency implication (e.g., double-start behavior), so it falls short of a 5.

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

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

Three tight sentences: action, prerequisite, and scope boundary. Front-loaded with the verb and resource, no filler.

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

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

An output schema exists so return values need not be described. Description covers the action, prerequisite verification, sibling disambiguation, and the live-trading consequence, which is everything an agent needs to invoke correctly.

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

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

Schema coverage is 100% and the single instance_id parameter is documented in the schema. The description adds the meaningful instruction to verify instance_id and its linkage via list_instances first, but offers no format or constraint detail beyond that. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Start automated execution for an existing stopped or pending trading instance') and explicitly bounds scope by naming what it does not replace (activate_algo, create_instance). An agent can distinguish it from activate_algo and create_instance 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 an explicit prerequisite workflow ('Call list_instances first to verify instance_id, linked algorithm, broker environment, and status') and names the alternatives it supersedes. When-to-use and routing 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?

Adds substantive behavior beyond annotations: reversibility with start_instance, that existing broker positions are not necessarily closed, and the destination for exposure flattening. Annotations already cover safety hints (destructiveHint=false, idempotentHint=false), so the description appropriately focuses on the operational side effects and reversibility.

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 sentences, each with clear purpose: purpose statement, prerequisite/alternative, and routing to close_positions. Front-loaded and no wasted words.

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

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

Covers the action, prerequisite, reversibility, side effects on positions, and the alternative for exposure flattening. An output schema exists, so return values need not be explained; the description is complete for a 1-parameter tool.

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

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

The single parameter is fully documented in the schema, so baseline is 3. The description does not add format or constraint details for instance_id beyond implying it must be confirmed via list_instances.

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 (stop) and resource (running trading instance) and clarifies that it stops automated execution, distinguishing it from close_positions and delete_instance. An agent can select it correctly without further inference.

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

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

Explicitly names alternatives (start_instance for reversal, close_positions for flattening exposure) and the conditions that select them. It also prescribes a prerequisite ('Call list_instances first and confirm the target'), which is strong usage guidance.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false. The description adds genuinely useful context beyond them: 'Only supplied fields change' documents partial-update semantics, and it clarifies that the edit does not propagate to linked live instances. A 4 rather than 5 because no auth/permission or error behavior is mentioned.

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 sentences, zero waste, with the core purpose and partial-update behavior front-loaded before the sibling disambiguation. Every sentence earns its place.

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

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

With an output schema present, annotations covering the safety profile, and 100% schema coverage, the description's remaining job is scope and sibling disambiguation, both of which it handles cleanly. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema. The description adds the PATCH-style semantics ('only supplied fields change'), which explains why only algo_id is required, but provides no field-specific meaning beyond that. Baseline 3 is appropriate.

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

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

States a specific verb (update) and resource (saved algorithm) and scopes ownership ('owned by the user'). It explicitly distinguishes itself from the sibling update_linked_algo, so an agent can route correctly 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?

Names the alternative (update_linked_algo) and the condition that selects it ('instance-specific runtime change'), and clarifies that this tool does not touch live instances. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare destructive=true, idempotent=false and openWorld=true. The description adds meaningful context beyond that: toggling is_live=true can launch live trading and needs explicit user intent. It does not explain whether omitted fields are preserved or how name conflicts are handled, so it is good but not 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?

Two sentences, front-loaded with the core action, then the caveats. Every clause earns its place with no filler.

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

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

With an output schema present and annotations covering the safety profile, the description supplies the remaining high-value information (sibling exclusions and the live-execution side effect). Nothing critical to calling it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by flagging that is_live=true may start live execution, adding risk meaning the boolean type alone 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 (update), resource (an owned trading instance), and scope (name or runtime settings), which lets an agent separate it from adjacent tools at a glance. It also names the siblings it does not replace (activate_algo, update_linked_algo), removing ambiguity.

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

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

The description gives explicit exclusions ('does not replace activate_algo or update_linked_algo') and a usage condition ('setting is_live=true... requires explicit user intent'). It stops short of saying when to prefer this over start_instance/stop_instance, so it is strong but not fully 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?

Adds substantial context beyond the annotations: the override scope is per-instance-only, the first call returns a 'loop_mode_requires_confirm' disclosure, and the agent must retry with confirm_loop_mode=true. This is exactly the kind of behavioral disclosure the agent needs for a multi-step mutation flow. The annotation set (non-readonly, openWorld, non-idempotent) is already sensible and not contradicted.

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 the core purpose, then the confirm-loop mechanics. Dense but justified. Slightly cumbersome phrasing ('for THAT live instance only') but no wasted filler.

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

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

Given an output schema exists and the schema describes all parameters, the description supplies the crucial missing piece: the two-step confirmation contract and the scope of overrides. That is the non-obvious operational knowledge an agent needs to invoke this 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 description mostly restates what is already in the schema. It does explain the semantic difference of mcp_require_confirm values and the two-step confirm mechanism, but parameter-level details for parameters/name/description are not added.

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 specific verb+resource ('Update this agent's LinkedAlgo on an instance') and names the two updateable fields (parameters, mcp_require_confirm). Distinguishes from sibling update_algo by the 'LinkedAlgo on an instance' scope, though the distinction is somewhat implicit rather than contrasted 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?

Describes the retry flow and how new instances behave, giving clear context for the confirm_loop_mode path. However, it does not explicitly contrast with sibling tools like update_algo or get_linked_algo, 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.