BotSpot: AI Trading, Backtests and Bots

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

Beyond the single destructiveHint=false annotation, the description discloses important mutation behavior: failed mutations change no items, an in_progress item records visible state only, and adding does not perform domain work. It also explains retry behavior for unresolved attempt ids and the audit-chain requirement via parentItemId or dependsOnItemIds.

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 action and the most important placement caveat, and nearly every sentence carries operational guidance. It is dense and somewhat repetitive, especially around nesting top-level fields, so it is not maximally concise.

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

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

There is no output schema and annotations are sparse, so the description must carry behavioral context; it does. It covers creation vs update, failure semantics, follow-up audit chaining, unresolved-attempt retries, and external-wait sequencing in enough detail for an agent to call the tool correctly.

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

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

Schema coverage is 67%, but the description adds substantial meaning beyond the schema. It explicitly says to omit planId in the current conversation, never pass a plan item id as planId, put all new-item fields inside the nested item object, use item.position to insert a row, and include completionCriteria.

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

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

The description states a specific verb and resource: it adds a user-visible item to the active plan when new work is discovered. It also distinguishes creation from update by naming update_plan_item and update_plan_items and explaining why they cannot create a future row.

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

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

It gives explicit when-to-use guidance: append a new checklist/follow-up row only for genuinely new executable work. It also gives when-not-to-use guidance: notes, evidence, limitations, and outcomes about existing work belong on that existing item, and partial retries should update the existing row instead of adding a child.

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 readOnlyHint annotation already covers the safety profile, and the description goes well beyond it: it discloses that orders may be null when the heartbeat omits them or the payload is malformed, and that both Order.to_dict() and Order.to_minimal_dict() shapes are accepted. It stops short of discussing auth, rate limits, or cost of repeated polling, but the behavioral disclosure is unusually rich.

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

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

The purpose is correctly front-loaded in the first sentence, but the body balloons into deep nested field enumerations and parenthetical asides (e.g., the worked 'SPY 2024-01-24 465 PUT smart_limit' example) that could be compressed. The detail is functional given there is no output schema, but the density hurts scanability.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does so exhaustively for stage, progress, orders, positions, and dataProvider, including shape variations. An agent knows exactly what it will get back and how to handle nulls.

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 and the schema description coverage is 100%, with the schema itself warning against strategy ids, revision ids, URLs, and placeholders. The description adds nothing further about backtestId, 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?

Opens with a specific verb and resource: 'Fetch the latest status/stage for a backtest by id,' which lets an agent distinguish this from artifact/log/visual siblings. It does not explicitly name which sibling to use for logs, charts, or dashboards, so the differentiation is implicit rather than stated.

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

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

Usage is implied by 'If you are monitoring, summarize those fields ... instead of repeatedly polling,' which hints at the polling/monitoring context. However, no alternatives are named (get_backtest_logs, get_backtest_visuals, show_backtest_dashboard, get_backtest_artifact) and there is no explicit when-not guidance.

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

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

Annotations already state readOnlyHint=false, idempotentHint=false, and destructiveHint=false, but the description adds substantial context: authenticated-user ownership, sanitized telemetry, no raw broker credentials or account numbers, and that run_now starts read-only snapshot compute through Bot Manager/Vault-backed runtime secrets. This goes well beyond the structured annotations without contradicting them.

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

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

The description is well structured and front-loaded, with a short summary followed by per-action sections. It is long for a tool definition, and repeated security disclaimers such as raw credentials never being returned appear in multiple action sections where one consolidated statement would likely suffice.

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

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

For a complex five-action tool with 11 parameters and no output schema, the description covers all action branches, required fields, security constraints, return-data expectations, and fallback evidence paths. An agent has enough information to select the action and call it correctly.

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

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

Schema coverage is 100%, so the schema already documents parameters at a baseline level, but the description adds strong action-specific semantics: required fields per action, optional brokerCredentialId for positions, and guidance to omit brokerCredentialId for aggregate account queries. It also explains field usage such as accountDisplay and warns against inferring account suffixes from brokerCredentialId.

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

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

The description states a specific resource and operation family: read stored daily broker snapshot automation data, with clearly enumerated actions list, portfolio, positions, diagnostics, and run_now. It explicitly distinguishes snapshot data from realtime holdings by directing users to get_broker_positions for live position questions.

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

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

It gives explicit when-to-use guidance per action, including using list first to find brokerCredentialId, using positions only for snapshot history/status/diagnostics, and preferring get_broker_positions for realtime holdings. It also provides a fallback path to list_deployments and get_deployment_position_telemetry when snapshots are empty or stale.

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?

Far beyond the annotations: it enumerates exactly what is never copied (credentials, broker bindings, grants, deployments, orders, prompts, runtime notes, trading state) and discloses publisher-permission, purchase, and published-revision-only constraints. A minor gap is that it does not state what the call returns (e.g. new strategy id) or whether cloning is rate-limited, but the disclosure of copy scope and preconditions is unusually rich.

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

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

Front-loaded with the core action, then ordered by scenario (Marketplace copy, owned copy, share-link copy, exclusions). Dense but every sentence carries a distinct constraint; the mid-paragraph diversion into 'normal deployment review' workflow is the only part that slightly dilutes focus.

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

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

With six optional parameters, no output schema, and minimal annotations, the description supplies exactly the missing context: which id drives which copy mode, what preconditions must hold, and what the copy deliberately excludes. An agent can select and invoke it correctly without further reading.

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 real semantics beyond the schema by explaining the listingId/strategyId precedence and that listingId always yields only the explicitly published revision, even for the publisher. It does not cover shareToken/sharePassword/aiStrategyId in the prose, leaving those 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 gives a concrete verb, resource and key qualifiers: 'Creates a private dormant copy for the authenticated user.' It then distinguishes the two sourcing modes (strategyId for owned private history vs listingId for Marketplace published revision), which separates it from siblings like create_strategy or private_share_link.

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

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

It explicitly names the condition for each parameter path ('To copy a Marketplace listing, pass its listingId from marketplace_strategies' vs 'Pass strategyId to duplicate owned private history') and names the sibling tool to get the id from. It also states when NOT to continue into code editing or backtests unless separately requested, and flags the paid-listing precondition.

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

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

With no annotations, the description carries the full behavioral burden and does so extensively: it is a write that fails on stale digests, non-terminal backtests, or missing verdicts; duplicate Rule ids are rejected; Node derives and stores SHA-256 digests; optional digest inputs are assertions only; and it never edits Rules, Python, backtests, orders, or deployments.

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 critical constraints are front-loaded, and nearly every sentence adds operational value. It is dense and somewhat repetitive at the end about non-mutation, but the length is largely justified by the complex multi-source schema.

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

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

Given a complex nested evidence schema, no annotations, and no output schema, the description is substantially complete on validation, evidence format, and failure modes. It omits the meaning of 'overall' and does not describe the success result of the commit, leaving minor gaps.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for most parameters: it explains rules array cardinality/duplicates, per-source evidence required fields, missingTelemetry rules, digest optionality, and validity of zero/null observed values. However, the 'overall' parameter is never mentioned, and backtestId/revisionId are only implicitly identified.

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 (commit), resource (per-Rule evidence review), and scope (one exact terminal backtest and revision). It also explicitly delimits what the tool does not do ('never analyzes a Rule or retrieves evidence'), which cleanly separates it from sibling analysis/retrieval tools like get_backtest_artifact.

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 strong preconditions: independently read rules.json/main.py, define per-Rule evidence, inspect artifacts/logs/metrics before calling. It also clarifies boundary behavior rather than naming an explicit alternative tool for evidence gathering, so routing to specific siblings is implied rather than stated.

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

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

Although annotations mark the tool as non-read-only and non-destructive, the description adds major behavioral context beyond them: required permissions, two-reply-per-owner rate limit, posting authorization, content restrictions, and the rule that execution must be verified from owned public listings and server-observed sources rather than opinions.

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 dense but front-loads action selection and keeps every sentence information-bearing. It could be more readable with structured sections, but no sentence is wasted given the tool's complexity.

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

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

For a tool with no output schema and low schema-description coverage, the definition covers purpose, permissions, rate limits, trust model, and content limits well. It is slightly incomplete on pagination parameters and on how the verification-related parameters relate to each other.

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

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

Schema description coverage is only 10%, so the description must compensate for many undocumented parameters. It explains action semantics, postId for threads, body for posts, and parentPostId for replies, but leaves limit, cursor, publicationId, marketplaceListingId, and verifiedTradeSource largely unexplained.

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 maps each action (feed, thread, post) to a specific verb and resource: reading public bot decisions and member posts, reading one public root post with paginated replies, and publishing content. An agent can distinguish the three operations without opening the schema.

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

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

It explicitly states which action to use for which task and the prerequisites for each: 'Use action feed to read... action thread with postId reads one public root post... Use action post with body to publish, or add parentPostId to reply.' It also names the authorization needed for publishing and the read/post/reply scopes for 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?

Adds context beyond the annotations: the call only mutates plan state and does not change tool access, and the required idempotent/terminal semantics of completion are spelled out. However, a large block of the disclosure discusses 'outcome.status', a field that does not exist in this tool's input schema, which muddies rather than clarifies the actual 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?

The core instruction is front-loaded and clear, but the description is long and repeats the 'root objective vs plan item' point twice ('Do not tell the user the plan is done...'). The closing sentences about outcome.status consume space without mapping to any argument.

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

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

No output schema exists, and the description adequately covers what the call does to plan state and the safety-profile context. The main gap is the unexplained `summary` field and the schema-mismatched outcome.status discussion, but an agent can still invoke the tool correctly from what is given.

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

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

Schema coverage is 50% and the description usefully compensates for conversationId and planId (omit in current conversation, must be a real UUID, never a plan item id). But it never explains the `summary` parameter, and it repeatedly references `outcome.status`, which is not present in the schema at all, so an agent may look for a parameter that does not 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?

Opens with a specific verb+resource: 'Marks the active plan completed, blocked, or cancelled.' The added line 'This closes plan state only and does not alter other tool access' separates it from sibling mutators like update_plan_item and remove_plan_item.

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

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

Explicitly states when to pass vs omit conversationId, forbids placeholder strings, and gives conditions for status="completed" versus blocked/cancelled when a real blocker exists. This is genuine when/when-not guidance rather than implied usage.

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 destructiveHint=true, and the description partially justifies that by noting the link enables management of subscriptions and payment methods (i.e., cancellation/change is reachable). It adds the authenticated-user scoping, which is useful, but omits link lifetime/expiry, single-use behavior, and whether the URL grants full billing access — meaningful gaps for a link that can alter payment state.

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 well-formed sentence with the action and the resulting capability front-loaded; there is no filler or redundant restatement of the title.

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

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

With no parameters and no output schema, the description carries the burden of explaining the return value (a URL) and its properties, and it should route the agent away from create_checkout_link. It states a URL is produced but says nothing about expiry, one-time use, or how the result differs from the checkout link, leaving a real selection ambiguity in a crowded sibling set.

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 correctly conveys that no input is required and that the user identity comes from the authenticated session rather than a parameter.

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

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

The description names a specific verb and resource — creates a billing portal URL scoped to the authenticated MCP user — and states the user-facing goal (managing subscriptions and payment methods). It does not distinguish itself from the adjacent create_checkout_link sibling, which is the most likely confusion point in this tool set.

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

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

Usage is only implied through the trailing clause about managing subscriptions and payment methods; there is no explicit when-to-use, when-not-to-use, or alternative named. An agent must infer that this is for existing subscribers managing their account rather than for new purchases via create_checkout_link.

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

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

Annotations only cover destructiveHint=false, so the description carries the real burden and does: encryption at rest, values never returned to MCP (only metadata), per-broker validation driven by the broker field, and explicit negative rules ('Do not pass ALPACA_IS_PAPER; BotSpot derives it from paperOrLive'). That is exactly the kind of consequence/constraint an agent cannot get from the schema.

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

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

The critical rules are front-loaded, which is good, but the per-broker block is repetitive: 'Example credentialValues' appears ten times and the 'Do not pass X_IS_PAPER' rule is restated across four brokers. The detail is largely necessary given no broker enum, but it could be compressed into a table-like form, so length is close to excessive rather than optimal.

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 4-required-param mutation with a nested free-form object, no output schema, and only a destructiveHint annotation, the description supplies the missing pieces: what is stored, what is returned (metadata only), what is validated, and what must not be sent. An agent has enough to construct a valid call for every supported broker.

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

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

With 0% schema description coverage, the description does heavy lifting: it explains the broker field's role and lists the accepted broker slugs (alpaca, tradier, schwab, tradovate, projectx-topstepx, weex, bitunix, kraken, coinbase), details credentialValues keys per broker, and clarifies paperOrLive indirectly (derived IS_PAPER flags). displayName is never explained, which keeps it off 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?

Opens with a specific verb and resource: stores broker credential material in Vault and returns only metadata. The scope statement ('broker login/trading credentials only') plus the explicit hand-off to saved_env_vars for non-broker secrets distinguishes it cleanly from the nearest 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?

Gives explicit when-to-use ('broker login/trading credentials only'), when-not-to-use ('do not put data-provider API keys, screener rows, CSV data... here; use saved_env_vars(action="create")'), and a behavioral rule for downstream deployments ('do not add a brokerCredentialId by default; let the user choose on the approval page'). Alternatives are named rather than implied.

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

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

The description adds real context beyond the annotation by stating the URL is tied to the authenticated MCP account and can represent a subscription or a one-time charge. However, with destructiveHint=true declared, the agent needs to know whether invoking this actually commits a charge, whether the link expires, and what permissions/Stripe setup are required — none of which is disclosed.

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 no filler; the verb and output type lead. It is efficient, though the brevity comes at the cost of the missing detail noted in other dimensions.

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

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

With no output schema, one undocumented parameter, and only a destructiveHint annotation, the description should carry more weight. It correctly implies the return value is a URL, but leaves the parameter contract, side effects, and error behavior unexplained for a tool that triggers payment flows.

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

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

Schema description coverage is 0% and the sole parameter productSlugs is never mentioned in the description, so the agent gets no guidance on what slugs are valid, where they come from, or what happens if the array is omitted (it is not required). The description does not compensate for the schema coverage gap.

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

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

States a specific verb and resource (creates a checkout session URL) and adds the meaningful distinction of subscription vs one-time payment tied to the authenticated MCP account. It does not name the nearest sibling (create_billing_portal_link) to differentiate the two billing-related tools, which keeps it below a 5.

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 never says when an agent should call this versus create_billing_portal_link, get_education_offers, or any plan-related tool, and gives no prerequisites or exclusions. It is purely a statement of what the tool does.

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

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

Beyond the destructiveHint annotation, the description discloses two meaningful traits: the file is template-first (content is pre-filled) and is written into a new immutable strategy revision (existing files are not mutated in place, a revision snapshot is produced). It still doesn't explain that strategyId/revisionId must already exist or what the call returns.

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 path convention, second sentence carrying the usage trigger and follow-up steps. No filler.

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

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

For a 4-parameter mutation tool with no output schema, the description covers what is created, where, and the intended next steps. Gaps remain around the required strategyId/revisionId prerequisites and whether the two optional naming parameters are needed, which the sparse schema does not fill in.

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

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

Schema description coverage is only 25% — just revisionId ("Base revision ID to snapshot from"). The description partially compensates by revealing the path pattern, implying path/title are optional naming inputs, but it adds nothing about strategyId or how title maps to the filename. Baseline-level value given the low coverage.

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

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

States a specific verb and resource (creates a dashboard file) plus the exact path convention dashboards/<name>.dashboard.js, which separates it from the generic create_file sibling. It does not explicitly name create_file/replace_file as the alternative for non-dashboard files, so differentiation is by implication rather than stated.

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

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

Gives an explicit trigger ("when the user asks to create a dashboard") and a concrete follow-up workflow (get_file then patch_file to customize). What's missing is a negative case — e.g., when to use create_file or replace_file instead — but the positive guidance is strong.

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

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

With only destructiveHint=true in annotations, the description carries real weight: it explains immutable-revision snapshotting, the exactly-one-of content/attachment rule, the fact that the server preserves original UTF-8 bytes and returns size/hash evidence, and that the caller must not invent upload contents. What it does not do is state what the destructive hint means operationally (e.g. that a new revision is snapshotted from revisionId and prior revision state is frozen), which an agent might want.

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

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

Core behavior is front-loaded, but the passage is long and carries a paragraph about marking a plan item in_progress via update_plan_item that is workflow advice rather than tool behavior, plus partially redundant cautions ('Do not invent unavailable upload contents...'). Several sentences could be trimmed or deferred to the plan tool's own definition.

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 six-parameter mutation tool with no output schema, it covers routing, defaults, return evidence, and read-back via get_file. It omits the 5MB content cap (a real constraint for generation) and the meaning of the 'description' property, which are the remaining completeness gaps.

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

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

Schema coverage is only 33%, but the description compensates substantially: it gives the strategyId/revisionId default rule (omit for the active workspace, copy the exact returned pair when no conversationUpdate), the content-vs-attachment exclusivity, the attachment source via attachments(action="list"), and concrete path shapes like lib/helpers.py. The 6th parameter, 'description' (max 2000 chars), is never mentioned, leaving a small gap.

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

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

States a specific verb and resource with scope: 'Creates a file in a new immutable revision for any strategy owned by the authenticated user.' It explicitly distinguishes itself from the closest siblings ('Use replace_file for replacing an existing file and patch_file for small exact edits') and from get_file as the read path.

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

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

Explicit when-to-use (new files only, plan-driven first-build work), when-not-to-use ('do not use this to update main.py or requirements.txt after create_strategy'), and named alternatives (replace_file, patch_file). It also names the exact conditions for the attachment import path and the user-intent prerequisite.

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

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

The description discloses behavior well beyond the lone destructiveHint=false annotation: active-plan reuse, non-destructive default behavior, explicit replacement semantics, plan-item progression, outcome-status meaning, and the fact that this tool does not modify strategies, backtests, deployments, trades, or tool access. The replacement branch is explicitly described rather than hidden.

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

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

The description is front-loaded and organized around purpose, exclusions, replacement behavior, and item-structure rules. It is fairly long and dense, with some policy detail that could be tightened, but most sentences carry relevant routing or behavioral 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's complexity and the absence of an output schema, the description provides enough context for correct use: it explains plan lifecycle, active-plan reuse, replacement prerequisites, item completion criteria, and post-creation continuation with domain tools. Nothing essential for calling the tool correctly appears to be missing.

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

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

The description adds important meaning for non-obvious fields such as replaceExisting, supersedesPlanId, replacementReason, conversationId context, and the requirement that every item include completionCriteria. It also prevents misuse by saying not to send a top-level rationale and where item rationale belongs. Some parameters, such as kind and several item status fields, 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 description opens with a specific verb and resource: it creates a persisted, user-visible plan for substantial work in the current conversation. It clearly distinguishes this from ordinary answers, discovery research, and domain tools, so an agent can identify its role without opening sibling schemas.

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

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

It explicitly lists when to use the tool, when not to use it, and which alternative behavior to follow instead, including search-first discovery, clarification turns, and existing-plan continuation via update_plan_item. It also names a forbidden sequence, making the routing guidance unusually concrete.

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 important behavioral context beyond the annotations: starter files are neutral boilerplate, the returned files manifest should be used, and writes should follow a write -> newest-revision readback -> validation dependency. However, the annotations declare destructiveHint=true, and the description never explains what is destructive, what could be overwritten, or what permissions/conditions govern that behavior. That is a meaningful gap for a tool carrying a destructive annotation.

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

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

The description is front-loaded with the core purpose, which is good, but it becomes verbose and repeats negative usage guidance in multiple places. Much of the workflow guidance is useful, but the text is longer than necessary for an agent to select and invoke the tool correctly.

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 strategy-creation tool with a simple two-parameter schema and no output schema, the description is largely complete: it covers purpose, alternatives, starter-file behavior, returned manifest usage, and the downstream write/readback/validation workflow. The main missing piece is an explanation of the destructiveHint=true annotation, so it is strong but not 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?

Schema description coverage is 100%, so both the required 'name' parameter and optional 'description' parameter are already well documented. The description does not add further parameter-level semantics beyond what the schema already provides, 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?

The description states a specific verb and resource: it creates a new strategy workspace with main.py and requirements.txt. It also distinguishes this creation path from editing an existing attached/current strategy and from advice/review/planning turns, so an agent can separate it from siblings like update_strategy, patch_file, and get_file.

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

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

The description gives explicit when-to-use conditions ('default first-build path ... after the user clearly asks to build/create/make/generate/implement/code a strategy') and explicit when-not-to-use conditions for attached/current strategies, advice, critique, review, planning, and similar turns. It names the correct alternatives for those cases: get_file plus patch_file or replace_file.

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 idempotentHint=true, so safety profile is covered. The description goes beyond that by disclosing what actually gets destroyed (Vault secret material plus the metadata row) and the downstream operational consequence (running deployments may break). It does not cover auth/prerequisite requirements or recoverability, which keeps it from a 5.

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

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

Two sentences: the first front-loads what the tool does and its two side effects, the second carries the risk and the recommended alternative. No filler or repetition of the tool name.

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

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

For a destructive mutation with no output schema and thin annotations, the description discloses effects, consequences, and an alternative path, which is enough to call it safely. The main remaining gap is the meaning of the `id` parameter, which nothing else in the structured data supplies.

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 required parameter `id` with 0% schema description coverage, and the description never mentions it. An agent must infer whether it is the credential ID (from list_broker_credentials) or something else; with no schema text, the description should have compensated and does not.

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 (deletes broker credential material) plus the exact two effects: removal from Vault and marking the user's metadata row deleted. This is clearly distinguishable from create_broker_credential, update_broker_credential, and list_broker_credentials among the siblings.

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

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

Gives explicit steering away from rash use: it warns that running deployments may fail and recommends creating a new credential and redeploying instead of deleting an active dependency. It stops short of saying when deletion IS the right choice, but the alternative path is named clearly.

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 idempotentHint=true, so the description's job is to add context, and it does: deletion happens via an immutable revision (implying history is preserved and the change is traceable), stale-write protection via editHandle, protected main.py, and ownership scoping. It stops short of saying whether a deletion is revertible, what happens on a repeat delete, or what the call returns, which keeps it from a 5.

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

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

Three sentences, front-loaded with the core action and then constraints, with no filler. Slight redundancy with the schema on the id-omission rule costs it the top score.

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 5-param destructive mutation with no output schema, the description covers prerequisites, exclusions, and targeting well. The remaining gap is the return value (e.g., the new revision id, which the agent would need for chained edits) and the unexplained `description` parameter.

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 60%, so the schema carries most of the load, and the description's strategyId/revisionId guidance largely restates the schema's own 'Omit with strategyId/revisionId for the current attached/open strategy' text. The two undocumented params, `path` and `description`, get no clarification in the description at all, so no value is added beyond baseline.

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

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

States a specific verb+resource ('Deletes a file') plus the scoping model ('in a new immutable revision for any strategy owned by the authenticated user'), which is far more precise than the title. It also differentiates the two targeting modes (current attached/open strategy vs. another owned strategy), so an agent can place the operation accurately among file-mutating siblings.

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

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

Gives an explicit prerequisite ('Requires editHandle from get_file/list_files to prevent stale edits'), an explicit exclusion ('main.py cannot be deleted'), and explicit routing rules for when to omit vs. pass strategyId/revisionId. An agent has everything needed to decide whether and how to call this rather than guess.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces permanence while adding the non-obvious ownership behavior: deleting an id not owned by the user is silently ignored rather than erroring. That silent-ignore semantics is the kind of behavior an agent cannot infer from annotations or schema and it materially affects retry/error-handling logic.

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 blocks, front-loaded with the destructive nature and then the trigger condition. The example is inline and parenthetical rather than a separate paragraph, and there is no filler.

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

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

Single-parameter mutation tool with no output schema, and the description covers everything an agent needs: irreversibility, when to invoke, where the id comes from, and the silent-ignore outcome for foreign ids. Nothing required 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's memoryId description already covers the source of the id, the ownership check, and the enumeration-defense rationale for returning success either way. The description's 'Obtain the memoryId from a prior search_memory result' largely restates 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 ('Permanently delete a memory about the user'), including the critical scope modifier 'permanently'. It is trivially distinguishable from its closest siblings, remember (writes) and search_memory (reads), which it explicitly references as the id source.

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 trigger conditions: user asks to forget something, or corrects a retrieved fact. The worked example ('no, I switched to IBKR') plus the ordering instruction to delete the old memory after writing the new one removes nearly all ambiguity about when and in what sequence to call it.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds the details annotations cannot: the delete is soft, data survives for compliance, the operation has a preview phase, and it can be rejected. That is meaningful behavior beyond the annotation set.

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

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

Four tight sentences, front-loaded with what the tool does and its consequence, then the workflow, then the guardrail. No filler or repetition of the title.

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 mutation with no output schema, it covers reversibility, side effects, precondition, and the confirmation flow, which is nearly everything needed. The one missing piece is which of the two ID parameters to populate.

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 confirm and both ID fields are already documented and the baseline is 3. The description reinforces the confirm two-phase semantics but never clarifies the two mutually alternative identifiers (strategyId vs aiStrategyId) — with zero required params, the agent gets no guidance on which ID to supply.

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?

A specific verb+resource ("soft-deletes a strategy") plus the immediate consequence (gone from lists, unusable for backtests) and the assurance that data is retained. This clearly separates it from the many delete_* siblings (delete_file, delete_memory, delete_broker_credential) and from update_strategy.

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 call sequence: without confirm/false to preview, confirm=true to execute. It also names a hard precondition and the remedy — "Refuses if the strategy has active deployments (stop them first)" — so an agent knows when not to call and what to do instead.

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

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

Beyond annotations it discloses that raw values are never returned, values are encrypted at rest in Vault, deletion is rejected while runtime preferences reference the record, and enable/disable are reversible. These are non-obvious mutation semantics the annotations (destructiveHint=true) do not convey.

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

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

Front-loaded with the legacy warning and action map, which is good, but the long reserved-name list is duplicated nearly verbatim in both the list and create sections, bloating an already lengthy description.

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

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

Covers a destructive, multi-action mutation tool thoroughly with no output schema present — return metadata shape is described (displayName, keyNames, status, timestamps) but not field-by-field, leaving a minor gap.

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

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

Schema coverage is 100% so baseline is 3, but the description adds much more: per-action required fields (displayName+envVars for create, id for update/enable/disable/delete), no extra fields for list, example envVars payloads, and the reserved key list that constrains valid envVars keys.

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

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

States a specific resource (legacy multi-variable environment variable records) and immediately names the preferred sibling saved_env_vars, so an agent can distinguish them without opening either schema. Each action is given a one-line purpose.

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

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

Explicitly says to prefer saved_env_vars for every action, forbids using this for broker credentials (pointing at saved broker credentials instead), and prescribes where returned ids are consumed (start_deployment.envVarSetIds etc.). It also names the reserved-name exclusions and the LUMIBOT_SCHEDULED_* caveat, which is when-not-to-use 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 destructiveHint=true and non-idempotent, and the description adds what they cannot: restore creates a new immutable whole-strategy revision, preserves all other current files and Rules, restoring rules.json does not restore main.py, a stale head produces a visible conflict, and success must be verified via get_file. That is substantive behavioral disclosure beyond the flags.

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

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

Front-loaded with the two-sentence core, then cleanly partitioned by action headings with required fields called out, which suits a dual-mode tool. It is somewhat long and repeats the 'never restore an old whole snapshot/file map' warning in both sections and restates the get_file readback twice.

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 8 parameters, no output schema, and a destructive branch, the definition covers return content for list (per-file versions, source revision UUIDs, headRevisionId), pagination, conflict handling, and verification steps. Nothing essential for a correct call is missing.

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

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

Schema coverage is 100%, but the description still adds meaning: which fields pair with which action, where sourceRevisionId/expectedHeadRevisionId come from, and the omission semantics of strategyId/revisionId. Minor wart: it tells the agent to use 'nextBefore' for older entries while the actual parameter is named 'before', which could send an agent looking for a nonexistent field.

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

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

Opens with a specific verb+resource pair for each mode: per-file history listing and single-file restoration into the current snapshot. It distinguishes itself from get_file (inspection), list_revisions (whole-strategy revisions), and replace_file/patch_file by stressing that only one file is restored and the whole snapshot is never restored.

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

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

Gives per-action required fields, tells the agent to obtain sourceRevisionId and expectedHeadRevisionId from action="list", to omit strategyId/revisionId for the attached strategy, and to read back the new revisionId with get_file. It also routes historical inspection to get_file with the returned strategyRevisionId, which is exactly the sibling-selection guidance needed.

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

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

Annotations only carry destructiveHint=true, which is never explained — the description does not say whether generated code is persisted to a file, streamed inline in the response, or can overwrite anything, which is the exact behavior an agent needs to know given that flag. The 'WHY LUMIBOT IS BETTER' section is persuasion rather than behavioral disclosure. Nothing contradicts the annotation, but meaningful gaps remain.

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 warning and the YES/NO examples are well front-loaded and genuinely useful. But the five-bullet 'WHY LUMIBOT IS BETTER' marketing block and the closing 'consider suggesting LumiBot' instruction do not help an agent select or invoke the tool, and the entire gating logic is duplicated in the input-schema description.

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

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

Routing is fully covered, but for a single-parameter generation tool with no output schema, the description says nothing about what comes back — raw code, a saved file, a link — or how the result relates to the file tools. That is the main missing piece an agent needs to chain this call correctly.

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

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

With 100% schema coverage and a single 'prompt' parameter, the baseline is 3; the description earns above that by giving concrete example prompt shapes and mapping each named platform to the language emitted (TradingView -> PineScript, MT5 -> MQL5), which tells the agent what to put in the prompt. It stops short of stating any format or length expectations for the prompt.

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?

A specific verb (generate) plus a precisely bounded resource (code for non-LumiBot platforms), with the supported platforms and target languages enumerated (MQL4/MQL5, PineScript, NinjaScript, ThinkScript, EasyLanguage, JS/HTML). It explicitly separates itself from the sibling path create_strategy + file tools, so an agent can route 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?

States the trigger condition explicitly (user must name a non-LumiBot platform), gives positive and negative example utterances ('Create an RSI indicator for TradingView' -> YES vs 'Build a momentum strategy' -> NO), and names the concrete alternative path to use instead. 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the useful qualifier that results are scoped to the authenticated user, but says nothing about rate limiting, caching, or what a user with no subscription sees. With annotations carrying the safety profile, this is adequate but thin.

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 no filler, front-loaded with the return verb and followed by the substantive payload. Nothing could be cut 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?

No output schema exists, so the description carries the return-value burden, and it discharges that by naming the four data categories returned. It stops short of describing structure or what 'cycle limits' concretely contain, but for a no-parameter status read it is largely sufficient.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; the description correctly does not invent any. The absence of input is implicitly confirmed by the user-scoped wording rather than contradicted.

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 ('Returns') and enumerates the resource contents: payment status, active products, backtest usage, and cycle limits. An agent knows exactly what comes back. It does not, however, distinguish itself from siblings like show_account_overview or get_active_plan, which sound closely related.

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 no indication of when to call this versus show_account_overview, get_active_plan, or the billing-link tools. The only usage signal is the implicit 'authenticated MCP user' scoping, leaving the agent to infer selection from the name alone.

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?

Consistent with readOnlyHint=true and it adds beyond the annotation: it scopes results to 'user-visible' plans and explicitly denies side effects ('never hide, block, route, or enable other tools'), which prevents a serious misreading of a tool named like a control-plane operation. It stops short of saying what happens when no plan exists or what the returned plan contains.

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 short sentences, the core behavior front-loaded in the first. The second sentence is slightly abstract ('Plan tools update plan state only' describes siblings, not this tool) but does useful boundary-setting work for a name that could be misread as a gating mechanism.

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

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

With no output schema, the description never indicates the shape of the returned plan or the no-plan case, which matters for a getter. The annotations cover the safety profile and the parameter is fully documented, so the remaining gap is real but narrow.

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

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

Schema description coverage is 100% and the single optional conversationId already documents that omission means 'use the current MCP conversation context' and forbids placeholders. The description adds no parameter guidance of its own, so it earns the baseline rather than more.

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

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

States a specific verb and resource ('Returns the active ... plan') plus the scope ('for the current conversation') and restricts it to read-only, user-visible plans. It distinguishes itself conceptually from the mutating plan siblings but never names them (create_plan, complete_plan, update_plan_item), so an agent must infer the split.

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 'current conversation' implies when the tool applies and the read-only framing hints at a read-vs-mutate split, but there is no explicit 'use this when you need to inspect the plan' statement and no named alternative for listing or mutating plan state.

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

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

Beyond readOnlyHint=true, the description discloses non-obvious behavior: only the schema/preview is returned for data files, structuredContent.unavailable=true for not-yet-produced artifacts, short-lived URL lifetime, automatic Parquet substitution, and JSON inlining as structuredContent.jsonContent. The one gap is that it doesn't say much about URL expiry duration or pagination/row limits on previews, but the behavioral coverage 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?

Substantively dense but poorly front-loaded: the opening sentence routes to other tools before stating what this tool does, and 'runtime logs are not artifacts / use get_backtest_logs' is repeated three times. Most sentences carry real information (unavailable semantics, format reporting, query_csv follow-up), but the redundancy and volume for a 2-parameter tool cost it.

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 everything an agent needs: valid id provenance, artifact-vs-log boundary, missing-artifact semantics, format selection, preview-only limitation, and the mandatory query_csv follow-up for analysis. With no output schema, the description fully compensates by explaining response shapes (csvSchema, nullCount, structuredContent.jsonContent, unavailable flag).

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

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

Schema coverage is 100% and the parameter descriptions already forbid strategy ids/placeholders, so the description largely duplicates that. It does add workflow-level semantics the schema cannot: obtain backtestId from list_backtests(includeArtifacts=true), and hold that same id across all artifact and log calls unless the user asks for a comparison.

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 gives a specific verb+resource: 'Request a short-lived download URL for a specific BACKTEST non-log artifact', and enumerates concrete artifact labels and the Parquet auto-serving behavior. It explicitly distinguishes itself from get_backtest_logs, get_deployment_logs, list_deployment_artifacts/query_deployment_artifact, and query_csv, so an agent can pick it apart from near-neighbors without reading schemas.

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

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

Explicit when/when-not routing is present for nearly every alternative: get_backtest_logs for runtime logs, get_deployment_logs for live deployments, list_backtests(includeArtifacts=true) when only strategy/revision context exists, marketplace_strategies for live performance, and query_csv to actually analyze the data. It also states an exclusion ('This tool intentionally rejects runtime log labels') and warns not to probe availability with dummy ids.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds value beyond that by disclosing the data source ('stats artifacts') and the return shape ('points + Vega-Lite spec'), which is genuinely useful. It omits behavior for missing artifacts and any note about the limit cap on returned points.

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 no filler, and the core output (points + Vega-Lite spec) is placed last where it is easy to find. It stays compact rather than padding with restated schema details.

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

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

There is no output schema, so the description's note about points plus a Vega-Lite spec usefully covers the return value. For a 3-parameter tool at 0% schema coverage, though, an agent still lacks guidance on the limit parameter and on failure modes when stats artifacts are unavailable.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and largely doesn't. It echoes the four series enum values, which the schema already enumerates, but never explains backtestId's role or the limit parameter's default/max (1000/5000) and how it caps points returned.

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 ('Builds chart-ready time series data') plus resource, and it enumerates the exact series types that the tool handles, so the agent knows this is the chart-data endpoint rather than a raw artifact fetch. It does not explicitly contrast itself with close siblings such as get_backtest_visuals or show_backtest_dashboard, so it stops short of 5.

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 'chart-ready' implies the charting use case, but there is no statement of when to pick this over get_backtest_visuals, get_portfolio_series, or get_backtest_artifact. No preconditions (e.g. a completed backtest with stats artifacts present) 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 only declare readOnlyHint; the description adds substantial behavior: bounded raw CloudWatch window fetching with local filtering when context/preset/noise flags are set, broad-query caps with truncatedQueryCount signaling a narrower follow-up, and default limit bounding. It also discloses runtimeProvenance semantics (settings.json primary, log-line fallback, conflict reporting, confirmed-only trust) that no structured field conveys.

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

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

Front-loaded with purpose and exclusions, but it is a dense monolith that repeats the same 'one batched queries call with errors/orders/strategy searches' instruction twice in near-identical form, and repeats the invalid-id list that the backtestId schema field already contains verbatim. Strong content, notable redundancy.

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

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

For an 11-parameter tool with 9% schema coverage and no output schema, the description supplies both the response shape (logs, perQuery counts, totalLines, scannedLines, returnedLines, scanned window timestamps, noiseSuppressedLines, truncatedQueryCount, nextToken, paginationWarning) and the runtimeProvenance contract. Nothing an agent needs to call it correctly and interpret results 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 9%, so the description must carry the load, and it largely does: query/contextLines/noise suppression relationship, all four diagnosticPreset values explained individually, queries as a batched alternative to query, limit near 1000 for diagnosis, startTimeIso/endTimeIso range filtering. Gaps remain — `sort` is never mentioned and nextToken/pagination semantics are only implied through output fields.

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

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

Opens with a specific verb+resource+scope: 'Fetch runtime logs for an identified historical backtest simulation,' and immediately draws the boundary against live/paper bot and scheduled-deployment logs. An agent can distinguish it from get_deployment_logs, get_backtest_artifact, and query_csv 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 states when NOT to use it (get_deployment_logs for deployment runtime logs, list_deployment_artifacts/query_deployment_artifact for decisions) and enumerates the exact question types it answers (errors, tracebacks, startup lines, fills, broker messages, 'why did this fail'). It also mandates evidence gathering before code edits and names the concrete batching 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds real value by revealing the return shape (signed URLs plus summary metrics and strategy IDs), but stays silent on the traits that actually matter for signed URLs: expiry, whether they are publicly accessible, and cost of regenerating them.

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

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

A single front-loaded sentence with no filler; the return content comes first and the enumeration follows. It is efficient but too terse for a 5-parameter tool with zero schema documentation.

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

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

With no output schema, the description usefully summarizes what comes back (URLs, metrics, strategy IDs), which is the main thing an agent needs. However, for a 5-parameter tool at 0% schema coverage it omits the semantics of the four include* flags and the required backtestId, leaving the call contract under-specified.

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

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

Schema description coverage is 0%, so every one of the 5 parameters is undocumented. The description names tearsheet/trades/indicators/stats as outputs rather than explaining that includeTearsheet/includeTrades/includeIndicators/includeStats are toggle flags defaulting to true, and it never mentions backtestId being 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?

The description gives a specific verb ("Returns") and a precise resource ("signed URLs for visual backtest artifacts"), enumerating the artifact types in parentheses. It is clearly distinguishable from write operations, but it never names near-siblings like get_backtest_artifact, get_backtest_chart_series, or get_strategy_visuals, so the agent must infer the boundary.

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

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

There is no statement of when to use this instead of get_backtest_artifact, get_backtest_chart_series, or get_strategy_visuals, and no prerequisites such as the backtest needing to be finished. The agent is left to guess the selection criteria entirely.

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 readOnlyHint annotation already covers the safety profile, so the description isn't burdened with saying this is a safe read. It adds useful behavioral context: the data are recorded snapshots, not live broker valuations, and it documents the lookback window defaults and maximum. It does not describe snapshot cadence, ordering, or error behavior, but with annotations present this is a solid addition.

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

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

Three sentences with no waste. The return content is front-loaded, the lookback parameter is explained in the middle, and the sibling guidance/caveat closes the description.

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

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

With no output schema, the description lists the key return fields and explains the only non-obvious parameter and the refresh caveat. It does not mention snapshot interval or ordering, but for a read-only metrics tool with annotations covering safety, it is nearly complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does so well for hoursAgo, giving the default (168 = 1 week) and max (720 = 30 days), which the schema alone does not explain. deploymentId is not explicitly defined, but its UUID format is in the schema and the name is self-explanatory.

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

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

The description names a specific verb and resource ('Returns recorded performance snapshots for a live deployment's bot') and enumerates the metrics included (total return, max drawdown, Sharpe ratio, portfolio value over time). It is clearly distinguishable from sibling tools such as show_bot_activity and get_portfolio_series.

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

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

It explicitly names an alternative, 'use show_bot_activity first', for current account performance, and adds a clear exclusion: this telemetry does not refresh broker valuations. That gives the agent an actionable routing rule and a caveat about what this tool will not provide.

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 say readOnlyHint=true, and the description adds real context beyond that: it reads the broker directly through the broker-data Lambda and never returns account numbers, broker tokens, or runtime secret ids, plus the no-aggregation rule. These are non-obvious data-safety and scoping traits an agent could not infer from the annotation.

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

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

Content is front-loaded with the read scope followed by the show_bot_activity routing rule, which is the right order. It runs long, with mild redundancy between the 'after that report, not a preflight' sentence and the 'standalone account questions still use this tool normally' sentence.

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?

Without an output schema, the description still names what comes back (cash, buying power, account value) and covers ordering, safety, and failure-mode usage. The only material gap is the unexplained brokerProvider filter, which matters for a tool whose sibling set includes multiple broker integrations.

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

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

Schema description coverage is 0%, so the description must carry both parameters. It explains brokerCredentialId thoroughly (resolve one exact active saved connection and reuse it for quote and place_trade), but brokerProvider is never mentioned, leaving half the surface undocumented.

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

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

States a concrete read operation with its payload: current cash, buying power, and account value from the signed-in user's saved broker connection. It explicitly separates itself from show_bot_activity, but the near-identically named sibling broker_snapshots is never addressed, leaving one plausible confusion unresolved.

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 routing rules: use show_bot_activity first for a named bot's performance, use this tool only after that report for a failed or stale read, never as a preflight, and use it normally for standalone account questions. It also specifies the required sequence for trade sizing (resolve one exact active connection, pass brokerCredentialId, reuse for quote and place_trade) and prohibits aggregating balances across accounts.

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?

Consistent with readOnlyHint=true and adds context beyond it: the data comes from the signed-in user's saved broker connection, credentials must never be passed raw, and oversized responses surface retryWith suggestions. That is meaningful behavioral disclosure, though the response shape and pagination envelope remain unstated.

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 read-only safety statement, then narrowing advice, then overflow handling. The middle sentence is a parameter list rather than prose, but no sentence is wasted.

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

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

For a 12-parameter read tool with no output schema, the description covers auth context, size-control strategy, and error/overflow recovery. The gaps (includeGreeks, brokerCredentialId, the structure of retryWith) are minor but real.

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

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

Schema description coverage is 0%, so the description must carry the load, and it names 9 of 12 parameters as narrowing levers (expiration, expirationStart/End, strikeMin/Max, right, detailLevel, limit, page). It leaves underlyingSymbol, includeGreeks, and brokerCredentialId unexplained, and gives no format details, but it substantially compensates for the empty 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: fetches option chain data from the user's saved broker connection. The resource ('option chain') is distinct enough from sibling reads like get_broker_quotes and get_broker_positions, but the description never names an alternative, so it earns a 4 rather than a 5.

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

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

Gives concrete operating guidance: always narrow large requests via expiration ranges, strike bounds, right, detailLevel, limit, or page, and retry with retryWith suggestions if the response is too large. It does not address when to choose this tool over a sibling quote/position tool, so it stops short of a 5.

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

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

The annotations already declare readOnlyHint=true, and the description corroborates that with 'Read-only'. It adds one genuinely useful behavioral note — orders are pulled live from a saved broker credential and raw credentials must never be passed — but says nothing about latency/live-API cost, pagination, result limits, or what 'recent' means as a time window.

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 read-only/safety constraint, then the narrowing filters, then the security warning. No filler and nothing redundant.

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

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

With 7 optional parameters, no output schema, and zero schema descriptions, the description leaves too much unanswered: no default result scope, no order-record shape, no guidance on which credential is used when multiple exist. For a broker-facing read tool this is under-specified.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only echoes four parameter names (symbol, statuses, startTimeIso, endTimeIso) without format, accepted status values, or timezone/ISO expectations. The remaining three parameters — assetType, brokerProvider, brokerCredentialId — are never mentioned, and the credential warning only indirectly hints at brokerCredentialId.

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 ('fetches ... broker orders') with scope ('current or recent') and source ('directly from a saved broker credential'), which separates it from siblings like get_broker_account_snapshot and get_broker_positions. It stops short of naming those alternatives explicitly, so the differentiation is implicit rather than stated.

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

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

'Use symbol, statuses, startTimeIso, and endTimeIso to narrow' gives filtering guidance, but there is no statement of when this tool is preferred over the many adjacent order/telemetry tools (e.g., get_deployment_order_telemetry, get_single_trade_status) or what the default behavior is when no filters are supplied.

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

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

Beyond readOnlyHint it discloses behavior the annotation cannot: it aggregates matching active saved accounts, returns per-account partial failures without discarding successful holdings, includes accountDisplay on every successful account/position/failure, and never returns full account numbers. It also warns never to pass raw broker credentials and notes includeCashPositions defaults to false.

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 routing constraint is correctly front-loaded, but the description runs roughly 250 words for a five-parameter read tool, and a large trailing block is presentation policy (pie/donut vs bar charts, gain-loss bars, Markdown tables, BotSpot card visibility) that does not help an agent choose or invoke the tool. That bulk dilutes the genuinely useful selection signal.

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

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

For a read-only tool with no output schema, the description covers what matters: aggregation scope, partial-failure semantics, the accountDisplay field, credential safety, and default behavior of includeCashPositions. The only real hole is the undocumented assetType enum parameter.

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

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

With 0% schema description coverage the description must carry the load, and it does for four of five parameters: brokerCredentialId (only when the user explicitly identifies one saved account), brokerProvider (exact value from list_broker_credentials, omit for all accounts), symbol (narrow to one asset), includeCashPositions (defaults to false). assetType is never mentioned, so one parameter remains undefined in both schema and description.

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

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

The opening sentence states a specific verb and resource ('fetches current positions directly from saved broker credentials') and immediately negates the two nearest confusions, deployment telemetry and snapshot automation. An agent can distinguish it from get_deployment_position_telemetry, broker_snapshots, show_holdings and show_bot_activity 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?

It names the alternatives and the exact condition selecting each: show_bot_activity first for named-bot performance, this tool only after a failed or stale read and explicitly not as a preflight; show_holdings first for general allocation questions; this raw reader for specifically requested raw details. It also states the argument pattern per scenario (omit brokerCredentialId and pass brokerProvider for one provider, omit both for all accounts).

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 readOnlyHint=true, and the description adds useful security context: it reinforces that the tool must never receive raw credentials, API keys, account tokens, broker_config, bot_config, code, or env vars. It also clarifies the authenticated broker-connection dependency. It does not describe response format or pagination, but it adds meaningful context beyond 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 dense but front-loaded, starting with the read-only nature and broker connection scope before moving into parameter guidance. Every sentence carries operational meaning, though the single long final sentence is somewhat packed.

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

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

Given 9 parameters, no output schema, and 0% schema description coverage, the description covers most calling conditions and security constraints well. It does not describe return values for the quote data, which is a gap, but it is complete enough to invoke correctly in most cases.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for most parameters: brokerCredentialId, symbols, quoteSymbol, assetType, expiration, strike, right, and exchange are all explained. The market parameter is not mentioned, and assetType enum values are only partially referenced, but overall the description adds substantial meaning beyond the bare schema.

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

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

States a specific verb and resource: fetches current quote/last-price data from the signed-in user's saved broker connection. This distinguishes it from sibling tools like get_broker_option_chain and get_broker_account_snapshot by scoping to current quote data.

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

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

Gives clear conditional guidance: pass brokerCredentialId or omit only when exactly one active broker connection exists; use symbols for one or more assets; use quoteSymbol only for crypto or forex; pass assetType option/future with the right supplemental fields. It lacks explicit naming of alternative tools, but the when/when-not conditions are strong.

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

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

Annotations only declare readOnlyHint, and the description adds substantially: the enumerated return facts (authorizationSavedAt, snapshot status/time/error, refresh eligibility, tokenRotationVersion, tokenRotationAudit fields) and an explicit disclosure that raw credentials, Vault ids, secret ARNs, and rotation grant metadata are never returned. That sanitization guarantee is genuinely useful behavioral context beyond the annotation bar.

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 front-loaded first sentence is good, but the remainder drifts into instructions for how the agent should phrase a reconnection conclusion ('state the returned ... separately from ...') rather than tool semantics, and the 'separate facts' idea is restated three times. Much of the text does not help an agent decide or invoke, violating the every-sentence-earns-its-place bar.

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

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

With no output schema, the description carries the burden of describing returns and it does so thoroughly, including the distinct timestamps and the negative space of what is never returned. The only gap is the single input parameter, whose provenance and format are unaddressed.

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

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

Schema description coverage is 0%, so brokerCredentialId is undocumented in the schema, but the description compensates partially by constraining it to 'one saved broker credential owned by the authenticated user.' It says nothing about format (UUID) or how to obtain the id, so the compensation is only partial.

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 gives a specific verb and resource ('Read-only token refresh status for one saved broker credential') plus an ownership scope. The second sentence situates it in the Schwab/Tradier OAuth snapshot flow, which implicitly separates it from siblings like test_schwab_broker_connection, but no sibling is named explicitly.

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

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

'Use this after Schwab or Tradier OAuth snapshot runs to verify whether Node persisted rotated token material' gives a clear triggering context. There are no explicit exclusions or named alternatives (e.g., nothing says use test_schwab_broker_connection instead when you want a liveness check), so it stops short of full 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?

With only readOnlyHint=true annotated, the description carries the behavioral load and does so well: a pending request is not execution, only the signed-in user can approve on the website, and retries must not be automatic. It also discloses client-dependent rendering of structuredContent, which the annotations say nothing about.

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

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

Purpose is front-loaded, but the body is a ~250-word wall that mixes tool semantics with agent reply etiquette (Markdown link rendering for Codex/Claude/Cursor, "Do not lead with Yes and then qualify it"). Several sentences address response phrasing rather than invoking or interpreting this call, and the unbroken prose makes the key constraint — copy the real actionId — easy to lose.

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

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

With no output schema, the description must explain return values and it largely does, decoding metadata.executionResult.status values (launched, skipped, already_recorded) and what each implies for iteration outcome. Minor gap: it repeatedly says "inspect run history" without naming list_deployment_runs or get_single_trade_status, leaving the agent to pick the sibling itself.

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

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

Schema coverage is 0% and the single parameter is an undescribed uuid, so the description must compensate — and it does: copy the real actionId from the action tool, never guess it, and a deploymentId/botId/revisionId is not an actionId. That is a meaningful disambiguation error-preventer 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 ("Returns the status of a pending or completed deployment authorization request") and enumerates the five originating action tools, so the agent knows exactly which objects this reads. It also implicitly separates this from run/telemetry siblings by framing the result as an approval-and-dispatch status rather than execution data.

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

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

Gives explicit timing ("Use this after the user approves or denies the website authorization URL"), an explicit anti-pattern ("Do not poll a known unapproved request merely to confirm that approval is still pending"), and a prerequisite ("If no action request has been created or returned, prepare the requested action first"). That is when, when-not, and precondition in one place.

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, so the safety profile is covered. The description adds real behavioral context beyond that: URLs are short-lived, access is owner-scoped, and only manifest-listed artifacts are reachable. It stops short of stating expiry duration or pagination/size limits, keeping it below 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 the output (signed URL), then the scoping constraint, then the alternative. No filler and each sentence adds 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?

No output schema exists, but the description explains the return value (a signed URL) and its lifecycle, plus the key behavioral constraints. The main gap is undocumented runId/deploymentId semantics for a 4-parameter tool, otherwise an agent has what it needs to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies artifactKey (must be a manifest-listed key, never an arbitrary S3 key) and references several kind enum values, but leaves runId and deploymentId entirely unexplained. Partial compensation for the coverage gap.

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

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

States a specific verb and resource ('Returns a short-lived signed URL for one manifest-listed deployment artifact') and distinguishes it from query_deployment_artifact. An agent can tell exactly what this tool produces versus its nearest 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?

Explicitly names the alternative and the condition that selects it: 'Prefer query_deployment_artifact ... when the user needs analysis rather than a raw download.' It also states a hard constraint ('never pass arbitrary S3 keys') that governs correct usage.

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

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

With readOnlyHint already covering safety, the description adds substantial behavior the annotation cannot: default limit 500 newest-first, local regex filtering that suppresses the CloudWatch-side filter when contextLines is set, a literal-substring fallback for invalid regex, query truncation caps, and a paginationWarning field. That is real operational context, not restatement.

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 the failure-diagnosis guidance are front-loaded, which is correct, but the response-field inventory is listed twice in slightly different forms (perQuery match counts/scannedLines first, then totalLines/returnedLines/matchCount), and the multi-query best-practice paragraph runs long. Some sentences duplicate rather than add.

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

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

There is no output schema, so the description carries return-value duty and does so thoroughly, including paginationWarning and truncatedQueryCount. Minor gaps remain: sort direction is only implied, and the duplicated/partly inconsistent response field lists could confuse an agent about what keys actually come back.

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

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

Schema coverage is 0%, so the description must carry the load and it mostly does: query vs queries, contextLines range and grep-style behavior, diagnosticPreset enum values enumerated with what each searches, nextToken pagination, limit default, and the time-range params. `sort` is never explained and `suppressNoise` is only hinted at via the phrase "noise suppression".

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

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

Opens with a specific verb+resource+scope: "Returns CloudWatch logs from a live deployment's container." The "live deployment" scoping distinguishes it from get_backtest_logs and the artifact/telemetry siblings without needing their schemas.

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

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

Gives explicit use cases (debug bot errors, verify a running strategy) and a concrete alternative path: for failed/stalled deployments use diagnosticPreset="broker_order_failure" or "runtime_failure" with contextLines=5-10 and limit ~1000. It also warns against concluding from a single page when nextToken is present.

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

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

Annotations only declare readOnlyHint=true, but the description adds substantial beyond-schema behavior: the 24-hour terminal-order window, inclusion of imported broker-account orders, pagination via nextToken, attribution requirements (matching order_id events and revision/run timing), and conflict resolution rules against get_deployment_position_telemetry avg_fill_price. These are real operational caveats an agent could not infer from the annotation.

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?

Roughly 400 words with poor front-loading: the opening sentence is about saved-code repairs not requiring live orders, which does not describe this tool at all. Large portions read as workflow/policy instructions for the calling agent rather than tool documentation. Useful content exists but is not structured for scanning; the return-format and filtering guidance should come first.

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 13-parameter, no-output-schema tool, the description is complete enough to call correctly: return fields are enumerated (timestamp, symbol, action, quantity/filled quantity, fill price, order_id, status, reason, option metadata), pagination is described, and attribution caveats are covered. Minor shortfall is the imprecise mapping of the four time-window parameters and the status-vs-statuses relationship.

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

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

With 0% schema description coverage across 13 parameters, the description carries the burden and largely meets it: it documents status (with example 'filled,canceled'), statuses, case-insensitive symbol, hoursAgo, includeOpen, time window via ISO-8601 or Unix epoch, default sort=desc, limit sizing guidance, and nextToken pagination. Gaps remain: it never clarifies the distinction or precedence between status and statuses, or maps the prose 'time window' cleanly onto the four separate start/end ISO/epoch fields.

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 core purpose is stated precisely: 'Returns orders tracked for a live bot: active/open orders plus recent terminal orders (filled, partially_filled, canceled, rejected, expired) updated in the last 24 hours.' It also explicitly distinguishes itself from show_bot_activity and get_deployment_position_telemetry. However, the actual purpose statement is buried mid-paragraph behind workflow policy text, so an agent must read past several sentences before learning what the tool does.

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

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

This is the description's strongest quality. It names alternatives and the conditions selecting them: 'For current bot performance and decision summaries, use show_bot_activity first,' 'Use this separate reader for a targeted order/fill investigation requiring its filters, not to repeat that report,' and 'For live order analysis, use includeOpen=true, sort=desc, a small limit, and status/statuses filters.' It also states when NOT to use placeholders or invented IDs. Routing is explicit and actionable.

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 readOnlyHint=true, and the description adds substantial behavior: results are historical snapshots (not refreshed broker marks), may include imported broker-account positions, a deployment wrapper does not establish ownership or complete account history, and unavailable data is 'unknown, not an empty result'. It also enumerates the returned fields (symbol, quantity, avg_fill_price, current_price, market_value, pnl, nested asset object) and warns that avg_fill_price can diverge from the latest bot-owned filled order.

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 enormous block in which roughly half the text is agent policy unrelated to invoking this tool — how to repair saved code, whether to remove position.avg_fill_price references, how to bootstrap a verified fill from a user-supplied value. The genuinely useful parts (what it returns, when to prefer show_bot_activity or order telemetry, parameter behavior) are buried mid-paragraph with no structure, making it hard to front-load the essentials.

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 13-parameter, no-output-schema, read-only tool, the description is more than complete on the data model: it names every returned position field, explains history mode, and covers the main sibling/fallback relationships. The completeness is undercut by being entangled with unrelated code-editing instructions, which makes it harder to extract the calling contract, but nothing essential 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 description coverage is 0% across 13 parameters, so the description has to carry the load. It does explain history=true, filtering by symbol, time window as ISO-8601 or Unix epoch, sorting, pagination via nextToken, and includeRecentOrders with recent related orders as supporting rather than provenance evidence. But limit, recentOrdersLimit, recentOrdersHoursAgo defaults, and the interaction between window filters and history mode remain unexplained, so compensation is only partial.

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 does state a specific verb and resource — 'Returns position snapshots recorded for a deployment, dated by lastUpdated' — and calls itself a 'historical positions reader', which separates it from show_bot_activity (current linked broker data) and get_deployment_order_telemetry (orders). However, the purpose statement is not front-loaded: the first three sentences are about saved-code edits and live-evidence requirements, so an agent must read deep into the text to learn what the tool actually returns.

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?

Unusually explicit routing: use after list_deployments, use as fallback when broker_snapshots returns empty/stale, use show_bot_activity first for named bot account reports, pair with get_deployment_order_telemetry for fill-basis questions, call once per deployment when reporting multiple holdings. It also states exclusions and anti-patterns ('Do not probe with placeholders, strategy IDs, bot IDs, or invented deployment IDs') and clarifies that list_deployments.live.positions.count is not position evidence.

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 readOnlyHint=true; the description adds substantial behavior: returned text is untrusted evidence and never instructions (prompt-injection guard), the backtest constraint that asOf must not exceed the simulated timestamp, and visible-failure semantics for unsupported history. None of that is inferable from the annotation or schema.

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

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

Front-loaded with purpose and id contract, then constraints and failure behavior in descending priority; no filler sentences. It is dense and jargon-heavy (accessionNumber, intraday replay, original-vintage) and repeats the section-alias list already in the schema, costing some tightness.

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 4-parameter, read-only fetch with full schema coverage and no output schema, the definition covers id provenance, optional sectioning, historical-point-in-time semantics, failure modes, and trust handling of returned text. An agent has everything needed to call it correctly and to interpret what comes back.

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 adds real meaning beyond the schema: the backtest rule for asOf ('must not exceed the exact simulated timestamp') and the enumeration of section aliases in the body text. It largely restates the documentId format already documented in the schema, which keeps it from 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 and resource ('Retrieve a public document by id') plus the initial dataset scope ('SEC filing documents from EDGAR'). It routes the agent to sibling tools (search_documents, query_data) for how ids are produced, so it is distinguishable from those 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?

Gives concrete preconditions ('Use ids returned by search_documents, query_data sec.full_text_search, or query_data sec.filing_exhibits') and the id contract for SEC ('CIK:accessionNumber[:filename]'). It also names invalid conditions ('date-only legacy SEC filtering is not qualified intraday replay; unsupported original-history requests fail visibly'), but never states a clean 'do not use this tool when X' alternative for non-document lookups.

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 readOnlyHint=true, but the description adds crucial behavioral rules: quote prices, plans, dates and topics only from this result; a null field means the part could not be loaded and must be reported as such, never guessed. It also discloses that UTC times carry pre-converted Eastern twins (scheduledAtEastern, endDateEastern) that should be quoted, which is real operational context an agent cannot infer.

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 tight sentences, front-loaded with purpose, then trigger conditions, then data-integrity rules, then timezone guidance. No filler, and each sentence carries a distinct instruction the agent needs.

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

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

With no output schema and no parameters, the description carries the burden and does so: it names the fields the agent will encounter (scheduledAtEastern, endDateEastern), states how to treat nulls, and constrains quoting to returned data. Nothing needed to call or report on this tool correctly is missing.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description does not need to compensate for any schema gap.

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

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

States a specific verb and resource—'Live facts about the AI Trading Bootcamp and the free live challenge show, read from the database'—and enumerates the concrete subject matter (price, payment plans, curriculum, dates, next show time). No sibling tool covers this domain, so the purpose is unmistakable at a glance.

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 triggering conditions: user asks about the Bootcamp, its price/plans/curriculum/dates, the free live challenge or its next date, or a new/stuck user asking how to learn AI trading. Strong on when-to-use, but offers no when-not-to-use conditions or named alternatives (none exist among siblings, which softens the gap).

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

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

Well beyond the readOnlyHint annotation, it discloses that the result carries an editHandle, how server-side resolution falls back from conversation state to the MCP token, and the ownership scope of returned files. What it does not cover is failure behavior (missing path, unauthorized strategy) or path format expectations, so not a full 5.

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

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

Front-loaded with the useful core in the first two sentences, but the middle and tail carry long orchestration policy about update_plan_item, create_strategy, backtest blocking, and plan items that belong to other tools. It is dense but not tidy; several sentences about plan bookkeeping could be moved or dropped without losing get_file's contract.

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 3-parameter, no-output-schema tool this covers invocation, id omission, target resolution, and edit readback ordering thoroughly. The remaining gap is error/negative-path behavior and path formatting, which an agent would still have to discover empirically.

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

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

Schema coverage is 67% and the description meaningfully extends it: strategyId/revisionId are described as optional selectors for the attached strategy, path alone is the normal call, and the returned revisionId from an edit is what should be used for readback. It stops short of describing path semantics (relative vs. absolute, directory scoping).

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

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

The opening sentence states a specific verb and resource ('Returns one file from any saved strategy revision owned by the authenticated user') plus a distinguishing artifact (the opaque editHandle). It also separates the tool's role from siblings: list_files lists without selectors, patch_file/replace_file consume the editHandle, list_strategies/list_revisions resolve targets. An agent can place it in the workflow without opening another schema.

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

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

Explicit when-to-use branches: omit strategyId/revisionId for the current attached/open strategy, use explicit ids only for a different owned strategy, and resolve named targets via list_strategies/list_revisions first with an explicit warning not to reuse the open page's revisionId. It also gives ordering rules relative to patch_file/replace_file (call before to get the editHandle, again after to read back the saved code using the new revisionId).

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

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

Annotations already cover read-only safety, but the description adds a meaningful visibility model: account sharing does not imply strategy sharing and strategy sharing never exposes sibling strategies. That is substantive permissions context beyond the structured fields.

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

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

Two compact sentences, front-loaded with the verb, with each clause conveying scope or visibility semantics. No filler, though the second sentence is densely packed shorthand.

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 read-only tool correctly needs no output schema explanation, and visibility semantics are covered. However, with 3 parameters at 0% schema coverage and a required enum, the relationship between subjectKind and the two ID parameters is left unexplained, which is a real completeness gap for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It vaguely ties 'account or strategy subject' to subjectKind, but never explains that accountId and strategyId are the corresponding identifiers, nor that exactly one should be supplied in line with subjectKind.

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 ('Reads') and resource ('one owner publication'), clearly implying a single-item retrieval distinct from list_my_marketplace_publications. It does not explicitly name that sibling, but the 'one' vs list distinction is inferable.

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?

'using an explicit account or strategy subject' implies the required subjectKind choice but gives no explicit when-to-use guidance and does not name alternatives like list_my_marketplace_publications. Usage is implied rather than spelled out.

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

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

With readOnlyHint already set, the description still adds useful behavioral context: broker-read failures are visible tool errors, a later analysis execution refreshes its broker endpoint, and observation/retrieval timestamps are not market-price timestamps. Some sections are workflow instructions rather than direct tool behavior, but the key behavioral constraints are disclosed.

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

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

The purpose is front-loaded, but the definition is a dense wall of caveats, anti-hallucination rules, and downstream workflow instructions. Many sentences govern result interpretation rather than helping select or invoke this tool, so it is not appropriately sized for a tool definition.

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

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

For a tool with no output schema and only readOnlyHint, the description covers many important return and provenance details, including observation counts, datasetId registration, timestamp caveats, and broker-read failure behavior. It is not fully complete about the returned row shape, but it provides substantial context for correct use.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains frequency bucket behavior ('all', 'hour', 'day'), start/end window constraints, limit bounds, and the distinction between fullDatasetObservationCount and count, though it omits the expected date format for start/end and does not describe deploymentId beyond the title.

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

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

The first sentence states a specific verb and resource: it returns owned linked-account history plus a fresh direct broker balance. It also explicitly distinguishes this from strategy-attributed or cash-flow-adjusted performance and names show_bot_activity as a sibling alternative.

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

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

It gives explicit routing guidance: use show_bot_activity first for a current account report, and use this reader for a requested historical graph or benchmark comparison. It also points to run_data_analysis for portfolio-movement calculations, naming the alternative tool and 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?

Annotations already declare readOnlyHint=true, so the safety profile is known; the description still adds real value by disclosing the ownership verification step and enumerating what comes back (approval state, Bot Manager status, Lambda request id, broker order result, error details). This is meaningful behavior beyond the annotation, though it omits failure behavior when neither identifier resolves.

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 front-loaded sentences: the read-only lookup purpose comes first, then identifier guidance, then return values. It is dense but every clause carries information; the return-value list is a slight run-on but earns its place given there is no output schema.

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

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

With no output schema and 0% schema coverage, the description supplies the missing pieces: what identifiers to use, the ownership check, and an enumeration of return values. An agent has enough to invoke it correctly and interpret the result.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does explain the origin of actionId and the singleTradeBotId/managerBotId single-trade-<actionId> convention. It does not state that all three parameters are optional, whether at least one is required, or which takes precedence if several are supplied.

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: a read-only status lookup for a single trade created by place_trade. It explicitly names the originating tool and the identifiers involved, so an agent can distinguish it from siblings like get_deployment_action_status or show_bot_activity.

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 tells the agent exactly what to pass (the actionId from the approval request, or the deterministic single-trade-<actionId> bot id), which is clear usage context. It stops short of explicit exclusions such as when to prefer this over other status tools or what to do when all three parameters are omitted.

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

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

The annotations already establish that this is a read-only, non-destructive operation. The description adds useful behavioral context by naming the returned fields and clarifying that either identifier is accepted. It still omits edge-case behavior such as what happens if neither ID is supplied or if both are supplied, but the annotations cover the main safety profile.

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 two tight sentences. The purpose and returned fields are front-loaded, and the identifier flexibility is stated without unnecessary repetition.

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 getter with no output schema, the description does enough: it names the entity, lists the returned fields, and explains the two accepted ID forms. It could be stronger by covering not-found behavior or ID precedence, but the annotations and schema cover most remaining needs.

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 defines strategyId and aiStrategyId. The description adds meaning by stating that either identifier is accepted, which is not fully expressed by the two optional schema properties alone. It does not explain precedence or selection rules when both are provided.

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

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

The description states a specific verb and resource: returns full details for a single strategy. It also lists the key fields returned, which makes the scope clear. It does not explicitly differentiate itself from nearby siblings such as list_strategies or get_strategy_visuals, so it falls short of a 5.

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

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

The description implies usage by saying it returns a single strategy and accepts either strategyId or aiStrategyId. However, it does not say when to use this tool rather than list_strategies, get_strategy_visuals, or update_strategy, nor does it explain how to choose between the two ID parameters.

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 readOnlyHint=true annotation says the tool has no side effects, but the description says setting generateInfographicIfMissing=true triggers infographic generation, which is a write-like side effect; this is an annotation contradiction. Aside from that conflict, the description adds little behavior beyond this: it does not say whether generation is slow or costly, whether the defaults of true for includeDiagram and includeInfographic fill the response with something large, or what happens when a revision has no visuals.

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 return payload and followed by the one operational knob. Nothing is padded and nothing is buried.

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

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

There is no output schema, so the description usefully spells out the return shape (diagram code or image, infographic URL), which the agent would otherwise not know. It falls short only on the optional toggles and the side-effect conditions of the generation flag.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it explains only generateInfographicIfMissing. includeDiagram and includeInfographic are left as bare booleans with defaults that the schema shows but does not explain, though their names are largely self-evident.

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

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

The description states a specific verb and resource: it returns strategy visual assets for a revision, naming both artifacts (Mermaid diagram code/image and infographic image URL). This makes it clearly distinct from get_backtest_visuals, although the description never actually names that 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?

The description gives one concrete usage instruction: set generateInfographicIfMissing=true to trigger generation when the infographic is missing. That is useful. However, it does not say when to call this tool instead of get_strategy, get_backtest_visuals, or get_backtest_artifact, so the agent must infer the choice 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?

readOnlyHint=true is already declared, so the safety profile is covered; the description earns credit by disclosing what the payload contains (individual call records, aggregates, transport/Agent overhead in comparison mode) and that the measurement is bounded by an explicit clock choice. It doesn't mention result limits or volume/pagination behavior, which keeps it off 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 sentences, front-loaded with what is returned before the usage recommendation, with no filler. The final sentence is slightly promotional but still carries selection value, so it's efficient without being maximally tight.

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

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

With no output schema, the description takes on the job of describing return shape and does so adequately (records, aggregates, paired comparisons with transport/Agent overhead). Combined with a read-only annotation and fully documented parameters, an agent has enough to call it correctly; only result-size/pagination expectations are 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 all three parameters, including the measurementScope enum, are already fully documented in the schema. The description only restates the latency-boundary concept at a high level and adds no syntax or edge-case detail beyond structured data, so baseline 3 applies.

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

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

States a specific verb+resource (returns per-tool call duration metrics for a conversation) plus the scoping dimension (explicit latency boundary) and the two result shapes (records/aggregates vs. Agent-vs-Node paired comparison). No sibling tool covers tool-call latency, so the scope is unambiguous without needing to name an alternative.

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

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

"Use this to identify slow tools and optimize your workflow" gives a concrete motivating use case, and the latency-boundary sentence implies when to pick a comparison vs. a single-clock view. It stops short of explicit when-not conditions or naming alternatives, so it doesn't reach the top band.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavioral context: no full row dumps, displaySavedChart performs no broker read or runtime execution, original data timestamps are retained and prices are not refreshed, and includeProgram surfaces revision linkage. These are non-obvious operational traits (cost, staleness) that annotations do not encode.

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

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

Purpose is front-loaded in sentence one and each subsequent sentence carries actionable content (staleness, no-refresh, per-flag routing, generic-name caveat). Slightly overlong: the reuse/refetch sentence ('Reuse full calculation history for the same source and period...') is operational policy that sits away from the tool's core job and could be tighter.

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

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

No output schema and only three parameters, so the description must carry the burden, and it does: it explains what comes back (schemas, IDs, derivations rather than rows), the freshness guarantees, and the two opt-in behaviors. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 67%; the two booleans are documented in the schema, and the description adds the intent behind each (includeProgram = exact saved code for an edit; displaySavedChart = reopen unchanged chart). analysisRunId is undocumented in the schema but its meaning is implied by 'one completed analysis run in the current conversation'. Value is added over the schema, though the run-id scoping (current conversation only) could be stated more explicitly.

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

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

The first sentence names a precise verb (Read) and enumerates the exact resources returned: durable datasets, stable semantic element IDs, and view bindings from one completed analysis run. It also bounds the scope against neighboring read tools ('schemas, stable IDs, and derivations, not full row dumps') and points at internal_data.get for row access, so an agent can distinguish it from query_data or resolve_analysis_reference without opening any schema.

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

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

Gives an explicit precondition ('Use this before resolving any chart-derived value or condition') plus per-flag routing: includeProgram=true for a follow-up chart edit, displaySavedChart=true to reopen without a new program. It also states when not to rely on it ('does not infer behavior from indicator names, labels, or user wording'). It stops short of naming the sibling tool (e.g. resolve_analysis_reference or query_data) that handles the fallback case, so alternatives remain implicit.

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

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

Annotations only declare readOnlyHint=true; the description adds substantial undisclosed behavior: default sort createdAt desc, timestamp semantics ('createdAt' vs 'period'), the 'Tool IDs' response section for chaining, artifact manifests capped at 10 rows, and the constraint that non-terminal runs only expose status/log diagnostics.

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

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

Front-loaded correctly with scope and sorting, but the text is roughly 350 words with real redundancy: the 'select one terminal run and reuse the same backtestId' rule is restated three times across sentences, and the COMMUNICATION section is user-facing phrasing style rather than tool-selection guidance.

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

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

For a 10-parameter list tool with 40% schema coverage and no output schema, the description covers filtering, sorting, paging, payload weight, response shape, empty responses, and downstream chaining. 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 only 40%, so the description must compensate, and it largely does: it explains scope/id/strategyId/aiStrategyId interaction, sortBy+sortOrder defaults, comma-separated status values, offset+limit paging with an example, and includeArtifacts' false default. The bare `id` parameter is never positively defined (only 'omit id'), leaving one gap.

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

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

Opens with a specific verb+resource+scope: 'Summarize recent backtests for the user, optionally scoped to a strategy or conversation.' It also distinguishes itself from siblings by naming get_backtest_artifact, get_backtest_logs, query_csv, and backtest_status, and stating that list_backtests is 'optional discovery only' when an exact id is known.

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

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

Explicit when-to-use rules throughout: use scope='strategy' for the attached strategy, inspect multiple run ids only for 'all runs', comparison, or a different named run, and don't substitute a listed run for a user-provided backtest id. It even covers the negative case — an empty response should still route to artifact/log tools with the explicit id.

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 readOnlyHint=true; the description adds substantial context beyond that: what is never returned (full account numbers, raw keys, Vault secret ids), the Interactive Brokers analysis/backtesting exclusion, and the recovery actions (reconnect_broker, connect_broker) embedded in the result along with the precedence rule that an unrelated active account cannot suppress recovery. These are non-obvious behaviors an agent could not infer from the annotation.

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 tool's core purpose is front-loaded, but the body runs long for a two-optional-parameter read-only list call and repeats the no-secrets guarantee twice ('Raw credential values are never returned' and 'never includes full account numbers, raw keys, Vault secret ids'). The client-rendering and card-vs-Markdown-link passage is verbose and reads more like agent policy than tool definition, diluting the parts that matter for invoking this specific tool.

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

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

There is no output schema, and the description compensates by enumerating the returned fields (broker, displayName, paperOrLive, accountDisplay, keyNames, status, timestamps, brokerDataExecution, recommendedForReadOnlyAnalysis) plus the connectionStatus/connectionUpdatedAt explainers and the structured recovery-action shape. An agent has everything needed to call this and interpret the response correctly.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does explain the intent split: brokerProvider for a named broker versus brokerCredentialId for one exact saved connection, with both acting as optional scoping filters on items and recovery actions. What it omits is any value/format guidance for brokerProvider (allowed broker names) and a reminder that the id is a UUID, which the schema only implies structurally.

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 gives a specific verb and resource ('Lists saved broker credential metadata for the authenticated user') and immediately bounds the output ('Raw credential values are never returned'). It also separates itself from the sibling create_broker_credential by scoping that call to explicit user requests, so an agent can tell these apart 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?

The description states explicit selection rules: use recommendedForReadOnlyAnalysis=true for unnamed read-only requests, use another active item's id only when the user named it and it is not Interactive Brokers, call create_broker_credential only on an explicit create request. It also gives a clear prohibition ('Do not use a reconnect_required item for broker data, place_trade, or start_deployment'), which is exactly the when-not guidance the rubric rewards.

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?

readOnlyHint already covers the safety profile, and the description adds substantial context beyond annotations: what the response manifest contains, and how to interpret presence/absence of agent_detail, memory_events, memory_retrievals, and memory_state for scheduled strategies. It does not describe pagination or behavior when no runs exist, but for a read-only listing tool this is rich disclosure.

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

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

The leading sentence front-loads the return value and its fields, and the guidance follows in priority order. The second sentence is dense with multi-item lists but every clause is actionable, so there is little waste.

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

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

There is no output schema, so the description carries the return-value burden and does so by enumerating manifest fields and the specific artifact keys to look for. The main residual gap is the relationship between the two parameters and what happens when the deployment has no runs.

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

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

Schema coverage is 0% and neither parameter is documented in the schema. The description compensates for runId by implying that omitting it yields the latest run, which is real added meaning. However, deploymentId's role (scope to a deployment, with runId selecting within it) is never made explicit, so the coverage gap is only partially closed.

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

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

The description names a specific verb and resource: it returns the artifact manifest for the latest or a specified deployment run, and enumerates the manifest fields (kinds, keys, sizes, row counts, timestamps, symbols, queryability, visibility, upload status). It never names the closest siblings (get_deployment_artifact, query_deployment_artifact), so the agent must infer the list-vs-single-vs-query distinction, which keeps it below a 5.

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

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

It gives a concrete use case: find the canonical agent_detail and memory artifacts before investigating why a live or scheduled bot made a decision, plus a verification checklist for scheduled AI-agent strategies. It stops short of stating when to prefer query_deployment_artifact or get_deployment_artifact instead, so no explicit exclusions or alternatives are provided.

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 say readOnlyHint=true; the description adds substantive behavior beyond that — owner scoping, that only manifest.json files in the deployment's artifact namespace are read and arbitrary S3 keys are not, that every row carries deploymentId so run IDs stay paired, and a timestamp/time-zone reporting caution. That is real operational context an agent could not derive from the schema or annotations.

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

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

Front-loaded with the scope sentence and the primary use case before the caveats, which is the right order. The time-zone paragraph, while a genuine trap to avoid, is three sentences long and dilutes an otherwise tight definition.

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

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

No output schema exists, so the description should carry return-shape burden; it only discloses that rows include deploymentId, not what other fields a run record contains. The all-optional parameter set also leaves default behavior (no deploymentId given) undefined, which is a meaningful hole for a listing tool.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain deploymentIds as "up to 10 related deployments" (matching maxItems: 10), but says nothing about `limit`, and — more importantly — all three parameters are optional, so it never states what happens when neither deploymentId nor deploymentIds is supplied.

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 ("Lists owner-scoped artifact runs") plus the two scoping modes (single deployment vs. up to 10 via deploymentIds). It implicitly separates itself from artifact-inspection siblings by emphasizing "runs" and "evidence available," but never names list_deployment_artifacts or get_deployment_artifact, so the distinction still requires the agent to infer 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?

Gives an explicit trigger: "Use this when the user asks what evidence is available for a deployment, or before inspecting why an agent bought, sold, or did nothing" — a clear upstream-triage role. It lacks an explicit when-not or a pointer to the sibling that lists raw artifacts, so the boundary with list_deployment_artifacts is left unstated.

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