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

Annotations indicate idempotence and non-destructive nature. Description adds compliance context, key requirement, and two-step behavior. No contradictions.

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

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

Three sentences, each adding value: purpose, procedure, compliance. 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?

Covers essential flow: two-step process, compliance gate, key requirement. No output schema but description implies return of text on first call.

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 of 'acknowledgment' is generic. Description enriches it by explaining its role in the second call and how to obtain the exact phrase.

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?

Clearly states the action (record acknowledgment) and the resource (futures risk disclosure & Terms of Service). Links it to the prerequisite for join_bot. Could explicitly differentiate from siblings like approve_intent or complete_password_reset but context is strong.

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 it's required before join_bot and outlines the two-call procedure. Does not list when not to use or alternatives, but the usage context is well-defined.

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

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

Description says 'Creates an auditable timestamp' (mutation), but annotations declare readOnlyHint: true, which is a contradiction. The description does disclose the behavior, but the annotation conflict severely undermines transparency.

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

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

Two sentences, no fluff. First sentence states purpose, second details requirement and effect. Extremely concise and well-structured.

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 one-parameter tool with no output schema, the description covers the prerequisite and effect. However, the annotation contradiction creates a gap in expected behavior, reducing completeness.

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

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

The single parameter's description is already in the schema, but the tool description adds critical context: the text must match exactly what start_onboarding() shows. This adds value 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?

Clearly states the tool acknowledges a risk disclosure to unlock trading tools. It specifies the exact text requirement from start_onboarding. However, it does not differentiate from sibling 'accept_subscriber_terms'.

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

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

Explicitly instructs the user to provide the exact acknowledgment text from start_onboarding. No exclusions or alternatives are given, but the context is clear for a single-purpose tool.

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

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

Annotations already mark destructiveHint=true. The description adds that the plan must be in 'pending_approval' status and the parameter description hints at execution ('approve and execute'), providing additional 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?

Two short, front-loaded sentences with no wasted words. Every sentence adds value.

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

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

For a simple one-parameter tool with full schema coverage and annotations, the description is sufficient. It could elaborate on the outcome or prerequisites, but overall it's complete enough for agent 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 coverage is 100%, so baseline is 3. The parameter description is minimal, repeating the tool's purpose without extra details like format or examples. It adds little beyond the schema.

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

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

The description clearly states it approves a pending intent plan, specifies the required status condition ('pending_approval'), and distinguishes from sibling tools like execute_intent.

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 indicates when to use the tool (when plan is in 'pending_approval' status). It doesn't explicitly exclude other cases or mention alternatives, but the condition implies proper 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 already declare read-only and non-destructive behavior. The description adds value by detailing the DEGRADED status condition, return fields, and the specific markets checked, providing context beyond the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds meaningful information without redundancy.

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

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

Despite no output schema, the description explains return fields and a key status condition, making the tool's behavior fully understandable for select and invoke decisions.

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

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

The tool has zero parameters, so the schema coverage is 100% by default. The description correctly does not include parameter details, and baseline is set to 4.

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

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

The description clearly identifies the tool as a live bracket audit for specific instruments (CL/MES/NQ, non-MNQ), distinguishes from siblings like get_bot_bracket_status by specifying scope, and outlines return fields and a failure condition.

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 for monitoring bracket integrity of non-MNQ positions, but does not explicitly state when to use this tool versus alternatives like get_bot_bracket_status or check_unprotected_positions.

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 reveals the append-only nature of the storage, which contradicts the idempotentHint annotation (true). While it adds context about learning after 30+ signals, the contradiction undermines trust in the tool's 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 description is concise with three sentences that front-load the core purpose. No fluff or redundant information; every sentence adds value.

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

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

The description covers purpose, usage timing, storage location, and learning outcome. For a recording tool with 9 parameters and no output schema, this is fairly complete, though it omits details on duplicate signals or side effects.

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 78% schema description coverage, the input schema already documents most parameters. The description does not add significant new semantic meaning beyond what the schema provides, such as detailed usage tips for specific parameters.

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

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

The description clearly states the verb 'Record' and the resource 'outcome of an agent action or skill invocation' with a specific purpose for continuous learning. It distinguishes itself from siblings like get_learning_signals and store_trade_lesson by focusing on recording actions for pattern emergence.

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 advises using the tool after any significant agent action, providing a general usage context. However, it does not explicitly state when not to use it or compare it to alternative tools like get_learning_signals for retrieval or store_trade_lesson for trade-specific lessons.

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

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

Annotations indicate non-destructive, idempotent behavior. Description adds that it creates a challenge and is a prerequisite, which aligns with annotations. No contradictions.

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 action and purpose, no extraneous information. Every word earns its place.

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

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

Given the tool's simplicity and the fact that no output schema is provided, the description covers the essential purpose and usage. A minor gap is the lack of return value details, but it's acceptable for a straightforward tool.

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

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

The schema provides 100% coverage for the single parameter factor_id, so the description adds no extra semantic value. Baseline score is appropriate.

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

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

The description clearly states the tool creates an MFA challenge for login step-up verification, distinguishing it from verify_mfa by noting it is a prerequisite.

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

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

Explicitly states the tool is required before verify_mfa during subsequent logins, providing clear usage context. Does not enumerate alternatives but context is sufficient.

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 provide idempotentHint=true and destructiveHint=false, indicating safe repeated calls. The description adds the list of checks and that it returns ALLOW/BLOCK, but does not elaborate on side effects, permissions, or rate limits. It provides some context beyond annotations but not rich behavioral detail.

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

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

The description is concise, consisting of two sentences that quickly convey the purpose and scope. It lists specific checks, avoiding fluff, though it could be slightly more structured.

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 8 parameters with no schema coverage, no output schema, and a moderately complex tool (13 checks), the description fails to explain parameter roles or output format. Essential information is missing, making the tool hard to use 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%, meaning the description does not mention any of the 8 parameters (qty, side, broker, symbol, etc.). The description only states the tool runs checks and returns outcomes, offering no insight into parameter meaning or usage. This is insufficient for a tool with many parameters.

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

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

The description clearly states it runs 13 pre-trade safety checks before placing an order and returns ALLOW or BLOCK with reasons. The verb 'check' and resource 'order safety' are specific, but it does not differentiate from sibling tools like 'bracket_integrity_check' or 'request_trade_confirmation'.

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 'before placing an order' implies when to use the tool, but there is no explicit guidance on when not to use it or alternatives. The list of checks and 'and more' gives some context but lacks exclusion criteria.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it checks reachability and backlog, and distinguishes between active lag and idle time to avoid false staleness signals in quiet markets. No contradictions.

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 consists of two concise, front-loaded sentences. The first sentence states the purpose and resource. The second adds crucial nuance about metric interpretation. No wasted words.

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

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

Given the tool's simplicity and rich annotations, the description covers the core purpose and metric distinction. However, without an output schema, the description could have included what the tool returns (e.g., a health status object with those fields) to be fully self-contained, which is a notable omission.

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

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

The input schema has 100% coverage for the single parameter max_lag_seconds, with a clear description in the schema. The tool description does not add any extra meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Check' and the specific resource: the AlgoChains Django signal propagation service (Roo architecture). It distinguishes this tool from sibling health check tools like get_system_health by focusing on signal propagation and copy-trade paper fanout backlog, including the nuance of separating active_lag_seconds from idle_since_last_signal_seconds.

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 explanation that the tool separates active lag from idle time so 'quiet markets do not look stalled' provides context on when to use it. However, it does not explicitly state when not to use it or mention alternatives among the many sibling health check tools, leaving some guidance implicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by stating the output format ('Returns OK | UNPROTECTED_EXPOSURE') and the importance of running it (prevents a specific loss). It does not contradict 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 three sentences, front-loaded with the core purpose and including practical usage notes. Every sentence earns its place without redundancy.

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

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

The description fully covers the tool's behavior, output, usage frequency, and importance. Given no input parameters and no output schema, it provides all necessary context for an agent to use 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?

The input schema has no parameters, so the description does not need to explain parameter semantics. Baseline 4 applies because schema coverage is 100% and description adds no parameter info beyond what is not needed.

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

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

The description clearly states the action ('cross-check ALL open Tradovate positions vs working orders') and the goal ('find unprotected exposure'). It uses a specific verb and resource, and includes example questions to distinguish usage from siblings.

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

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

The description provides explicit usage contexts: 'Use for...' and 'Do NOT use web search.' It also advises when to run ('before P&L reports and after restarts'). However, it does not mention alternative tools for similar checks, which prevents a perfect score.

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 password policy validation details (12 chars, upper/lower/number/special) beyond annotations. No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose, no extraneous 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?

Covers core functionality and inputs adequately. Could mention return value or error states, but sufficient for a straightforward action.

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?

Provides meaning for both parameters: access_token (from email URL fragment) and new_password (policy validated). Compensates for schema coverage of only 50%.

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?

Clearly states it completes a password reset using an access token, distinguishing it from the sibling 'initiate_password_reset'.

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 mentions using the access token from the reset email, indicating the post-email context. No explicit alternatives or when-not-to-use, but the flow is clear.

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

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

Annotations already indicate readOnlyHint=true (safe read), idempotentHint=true, destructiveHint=false. The description adds useful behavioral context: it uses actual daily returns, detects regime changes, and returns specific data formats. This goes beyond annotations without contradiction.

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

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

Two sentences, front-loaded with the primary action and scope. No redundant information. Every sentence adds value.

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

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

Given no output schema, the description adequately explains return values (heatmap data, average pairwise correlation, risk concentration score). It also notes the regime detection feature. A full picture is provided for a compute tool with few parameters and safe annotations.

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% (2 of 3 parameters have descriptions). The description mentions 'list of symbols' but does not add detail for period or threshold beyond what the schema provides. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description clearly states the tool computes a cross-asset correlation matrix for a list of symbols, using actual daily returns. It distinguishes from siblings like compute_factor_exposure and compute_volatility_surface by specifying the output (heatmap data, average pairwise correlation, risk concentration score) and behavior (detects regime changes).

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?

No explicit guidance on when to use this tool vs alternatives. While the purpose is clear, there is no mention of when not to use it or which sibling tools might be more appropriate for other tasks (e.g., compute_factor_exposure for factor exposure).

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already indicate safe read-only behavior. Description supplements by detailing outputs (alpha, betas, R-squared) and data source (Polygon daily data). No contradictions. Could mention cost or rate-limit implications of Polygon API calls.

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: first defines core action and data source, second lists outputs and regimes identified. No filler, every word adds value.

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

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

No output schema, but description enumerates key outputs (alpha, market beta, SMB/HML/momentum betas, R-squared, information ratio, tracking error). Sufficient for a factor decomposition tool; could add p-values or standard errors but not essential.

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 has 0% description coverage. Description mentions 'symbol' and implies 'period' (via 'daily data' and default 1y) and 'benchmark' (default SPY), but does not explain expected formats, the enum values for period, or how benchmark affects calculations. Needs explicit parameter guidance.

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

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

Description clearly states decomposing a symbol's returns into Fama-French 5-factor + momentum exposures using Polygon daily data, listing specific outputs like alpha and betas. It distinguishes from sibling analytical tools (e.g., compute_correlation_matrix) by specifying the factor model and data 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?

No explicit guidance on when to use this tool versus alternatives. The description implies it's for factor exposure analysis but doesn't mention exclusions or contrasting tools among siblings like compute_volatility_surface or detect_market_regime.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior. The description adds valuable context about data source (real Polygon options chain) and specific outputs (e.g., IV rank, percentile, vol regime), going beyond annotations. No contradictions.

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

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

Two sentences with no wasted words. Front-loaded with the core computation, then lists specific outputs and signals. Excellent efficiency.

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 explains all computed outputs and signals in detail. It lacks explicit return format (e.g., JSON) but covers the essential information for an agent to understand what the tool produces. Mostly complete for its complexity.

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%: expiry_filter has a clear description, but symbol lacks description. The description implies symbol is an equity ticker via 'Polygon options chain', but does not add format details. The description adds marginal meaning beyond the schema.

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

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

The description clearly states the tool computes a full implied volatility surface from Polygon options chain data and lists specific outputs (IV per strike/expiry, skew, term structure, IV rank/percentile, regime) and generated signals. It distinguishes this tool from typical get tools but does not explicitly differentiate from siblings like get_vix_term_structure.

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 use when needing IV surface from Polygon options, but provides no explicit guidance on when to use alternatives or when not to use this tool. No context on prerequisites or limitations.

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

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

Annotations already indicate mutation (readOnlyHint=false), non-destructive, and idempotent. Description adds the env var requirement but no additional behavioral details like state changes or connection lifecycle. Adequate but shallow.

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 succinct sentences with no redundancy. Could be expanded to add value without losing conciseness, but current structure is efficient.

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

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

Missing output schema and description of return values or side effects. Agent cannot predict tool's response or downstream effects. Incomplete for a connection operation.

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 description does not explain the 'broker' parameter (e.g., expected values, format, or source). Agent must infer meaning from context, risking misuse.

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

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

Description clearly states 'Connect to a specific broker' with verb and resource. Distinguishes from siblings like 'exchange_broker_oauth_code' and 'get_broker_setup_guide', but could specify what 'connect' entails (e.g., establish a session or authenticate).

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?

Only mentions a precondition via environment variables. No guidance on when to use vs alternatives like OAuth flows, or when not to use. Lacks explicit context for decision-making.

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 that this is non-read-only, non-destructive, and idempotent. The description adds valuable context beyond annotations: it is an owner-only side effect (AC-MCP-009), requires Onyx to be running, and supports recursive directory scanning. It does not explain duplicate handling, but the idempotentHint annotation covers retry safety.

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 four concise sentences with no filler. The primary action and effect are front-loaded, followed by a capability, a prerequisite, and an access-control note. Every sentence contributes distinct information.

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

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

For a 3-parameter ingestion tool with no output schema, the description covers purpose, accepted input types, prerequisite service state, and access control. The main omission is the expected return payload or success signal, which an agent may need to confirm the indexing operation succeeded, but annotations and schema carry most of the call semantics.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by specifying accepted file extensions (PDF, Markdown, JSON, TXT) and recursive directory scanning, which enriches doc_paths beyond the schema's generic 'file or directory paths' phrasing. It also reinforces owner_token's purpose through 'Owner-only side effect.'

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 ('Index'), a specific resource ('local research documents'), and a specific target ('Onyx RAG knowledge base'). It also states the observable consequence—documents become searchable via onyx_ask() and onyx_search()—which distinguishes it from the many sibling read/query tools.

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

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

The intended scenario is clear: index local research documents so they become searchable in Onyx. It also gives a necessary precondition ('Requires Onyx to be running at ONYX_API_URL'). However, it does not explicitly contrast with sibling ingestion tools like ingest_csv_data or ingest_json_signals, so it stops short of full when-to-use versus 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?

Annotation Contradiction: the annotations declare idempotentHint=true, but the description says 'Mint a new developer API key' and that the plaintext key is returned 'ONCE ONLY,' which implies each call creates a distinct key and repeated calls produce different results. This directly contradicts the idempotency hint. The description does add useful security context (AAL2 requirement, one-time plaintext), but the contradiction forces a score of 1.

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 deliver the core action, prerequisite, and a critical security warning with no filler. The most important information is front-loaded.

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

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

For a security-sensitive creation tool with no output schema, the description appropriately highlights the prerequisite, the one-time-only return, and the need to save immediately. It could additionally mention the response shape or explicitly contrast with rotate/revoke, but the core operational context is present.

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 75%, and the description compensates by explaining the env parameter through the ac_live_*/ac_test_* prefix and the access_token requirement through the AAL2 session prerequisite. This adds meaning beyond the raw schema, especially for the undocumented env 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?

The description uses a specific verb ('Mint') with a specific resource ('developer API key') and immediately clarifies key formats (ac_live_*/ac_test_*), which clearly distinguishes it from sibling tools like list_developer_keys, rotate_developer_key, and revoke_developer_key.

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 clearly states the prerequisite workflow: 'Requires AAL2 session (enroll_mfa + verify_mfa first).' This gives the agent concrete context for when it is safe to call. It does not explicitly name alternatives or exclusions, 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?

Beyond annotations (idempotentHint, destructiveHint), the description reveals authentication requirement (ALGOCHAINS_SUBSCRIBER_KEY), return structure (code, share_url), and the referral earning incentive (20% for 3 months). No contradictions with annotations.

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

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

Two concise sentences front-load action and cover purpose, return, uniqueness, earnings, and requirement. Every sentence adds value with no redundancy.

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

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

For a simple, no-parameter tool, the description adequately explains core behavior and return values. Missing output schema is compensated by stating returns. Could mention error conditions (e.g., invalid key) but overall 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 input schema has zero parameters with 100% coverage, so the description need not add parameter details. The baseline for 0 params is 4, and the description does not waste space on parameters.

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

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

The description clearly states the tool creates or fetches a referral code for the authenticated subscriber. It distinguishes from sibling tools like get_my_referrals and get_referral_earnings by focusing on code creation/retrieval.

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

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

The description explains what the tool does and notes the 'one active code per subscriber' constraint. However, it does not explicitly advise when to use this versus alternatives like get_my_referrals, leaving inference to the agent.

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

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

Annotations already convey safety (not read-only, not destructive) and idempotency. The description adds that it tracks P&L, fills, and metrics alongside the real portfolio, but does not disclose potential side effects, rate limits, or whether duplicate names are allowed.

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

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

Two concise sentences front-load the essential information: creation action and purpose, then additional tracking feature. No redundant or extraneous content.

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

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

The description covers the core functionality and use case. However, given the absence of an output schema, it would benefit from mentioning the return value (e.g., portfolio ID). It is slightly incomplete but sufficient for a relatively simple create operation.

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 75% (3 of 4 parameters described). The description adds no additional parameter details beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Create') and the resource ('shadow (paper) portfolio') with a specific purpose ('forward-test a strategy without risking capital'). It distinguishes from siblings like 'get_kronos_shadow_stats' and 'run_backtest' by emphasizing paper trading alongside real portfolio.

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

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

The description provides a clear use case ('to forward-test a strategy without risking capital') and implies its benefit. However, it does not explicitly state when not to use it or compare with alternatives like 'run_backtest' or 'portfolio_summary'.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds 'returns classification, strategies, risk multiplier' but lacks deeper behavioral context (e.g., external API calls, latency, required data freshness). No contradiction with annotations.

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

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

Two clear sentences: first states purpose and inputs, second states outputs. No extraneous text, front-loaded with key 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?

Returns are partially described (regime, strategies, risk multiplier) but no output schema exists. Missing details on error handling, data timeframe, or input constraints. Given 8 undocumented parameters, completeness is adequate but not thorough.

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 has 8 parameters with 0% description coverage in schema. The description only groups inputs as 'VIX, SPY trend, breadth, credit signals', failing to explain individual parameters like 'spy_price', 'put_call_ratio', etc. This is insufficient given the lack of schema descriptions.

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

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

The description clearly states the tool detects market regime from specific inputs (VIX, SPY trend, breadth, credit signals) and lists outputs (classification, strategies, risk multiplier). It distinguishes from sibling tools like 'get_current_regime' (cached) and 'detect_regime_hmm' (different method).

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 for regime detection with live data but does not explicitly contrast with siblings like 'get_current_regime' or 'detect_regime_hmm'. No when-to-use or when-not-to-use guidance is 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?

Description adds useful behavior beyond annotations: uses hmmlearn with fallback, returns multiple metrics (probabilities, days, transitions, vol regime, Sharpe). Annotations already indicate read-only, idempotent, non-destructive; description confirms and expands.

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: first sentence states purpose and outputs, second provides implementation detail and data source. Each sentence adds value; no redundancy.

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

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

Description covers purpose, method, data source, and output types. No output schema exists, but description partially compensates by listing return metrics. Could mention output format or structure for completeness.

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 descriptions cover both parameters (symbol, lookback_days) adequately. Description does not add new parameter-specific details beyond schema, but schema coverage is reported as 50% likely due to metric calculation; baseline 3 is appropriate.

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

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

Description clearly states action ('detect'), resource ('market regime'), method ('HMM on real daily returns'), and lists possible regime outcomes (bull_trending, bear_trending, etc.). Distinguishes from sibling tools like 'detect_market_regime' by specifying HMM and fallback.

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?

No explicit guidance on when to use this tool vs alternatives. Mentions 'Real Polygon data only' but does not elaborate on prerequisites or compare to sibling regime detectors.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns top-K relevant tools with descriptions and mentions context reduction, which aids understanding of behavior without contradicting annotations.

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

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

Three concise sentences, front-loaded with purpose and usage advice. Every sentence adds value, no wasted words.

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

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

For a simple search tool with 3 parameters and no output schema, the description fully explains purpose, output (top-K tools with descriptions), and efficiency benefit. No 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 67%; query and category have descriptions, top_k has default but no description. Description does not add further parameter details beyond schema. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

Description clearly states it searches for AlgoChains tools using natural language, returns top-K relevant tools, and advises using it first. Distinguishes from listing all tools by highlighting 90%+ context reduction.

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

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

Explicitly instructs to use this tool FIRST to find available tools, implying the alternative of listing all 533 tools is inefficient. Provides clear context for when to use 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 indicate it is not read-only, not idempotent (actually idempotentHint=true, so repeatable), and not destructive. Description adds that it returns a QR code URI for TOTP and mentions the session upgrade via verify_mfa, but does not disclose potential side effects like overwriting existing factors or auth requirements.

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 purpose, and includes key details (return type, next step). No unnecessary 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?

Adequate for a simple one-parameter tool: explains the main use case and next step. Lacks completeness for phone factor enrollment and does not mention prerequisites (e.g., user session status). Output schema missing but not critical given the simple return.

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 has 0% description coverage. Description partially explains factor_type: it mentions TOTP and SMS for the two enum values, but only elaborates on TOTP behavior (QR code). It does not explain the enrollment process for 'phone' (e.g., sending SMS) or that the parameter is optional with a default.

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?

Clearly states the action ('Enroll a new MFA factor'), specifies types (TOTP or SMS), and describes the output (QR code URI for TOTP). It also distinguishes from siblings by referring to verify_mfa for completion.

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

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

Provides explicit guidance to call verify_mfa after enrollment to complete the process. However, does not explicitly contrast with other MFA tools like challenge_mfa or list_mfa_factors, or mention when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds 'uses its live stats' and 'returns ranked eligible funds with strengths/warnings', which is consistent but doesn't disclose additional behavioral traits beyond what annotations provide.

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

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

Single sentence, front-loaded with purpose. No wasted words. Efficiently conveys the core action and result.

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 and no output schema, the description is too brief. It does not clarify parameter roles (e.g., which stats are mandatory), how the scoring works, or what 'ranked' means. Insufficient for an agent to confidently invoke the tool.

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

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

Schema coverage is only 13% (only fund_key has description). The description does not explain any of the 8 parameters, leaving the agent to guess which stats are required or how they are used. Given low coverage, description should compensate but 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?

The description clearly states the verb 'Score', the resource 'strategy against prop firms', and the output 'ranked eligible funds with strengths/warnings'. It also mentions optional specificity to a single fund, distinguishing it from siblings like 'list_prop_funds'.

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

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

Implies evaluation against all or a specific fund, but lacks explicit when-to-use guidance compared to siblings like 'validate_strategy'. No mention of prerequisites (e.g., need a registered strategy) or when not to use this tool.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds that it exchanges code for tokens, but does not disclose additional behavioral traits like error handling, rate limits, or side effects beyond what annotations imply. With annotations present, the description adds minimal value.

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

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

The description is a single sentence that is front-loaded with the key action and context. No unnecessary words, every part earns its place.

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

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

The tool has no output schema and 3 parameters. The description does not explain the return value (access/refresh tokens) or error scenarios. Given the complexity of OAuth flows, an agent would benefit from knowing what the response contains and how to handle common errors. The description is too minimal for complete understanding.

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% (2 of 3 parameters have descriptions). The tool description does not add any additional parameter semantics beyond the schema. For the 'redirect_uri' parameter, which lacks a schema description, the tool description also fails to provide meaning. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the verb 'Exchange' and the resource 'OAuth authorization code for broker access/refresh tokens', and provides context ('after the user returns from the broker's authorization page'). It distinguishes from sibling tools like generate_broker_auth_url and connect_broker.

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

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

The description explicitly says when to use this tool ('Call this after the user returns from the broker's authorization page'). It does not mention when not to use it, but given the context of the OAuth flow, the guidance is clear. A perfect score would require explicit exclusion of alternatives.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds critical behavioral context: that ORDER_EXEC/DESTRUCTIVE tools need owner_token and confirm=true, which is essential for safe execution. No contradiction with annotations.

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

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

Two sentences with no redundant information. Each sentence provides crucial guidance: the first states the core function, the second adds important conditions. Highly efficient.

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

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

Given no output schema, the description adequately covers purpose, prerequisites, and special cases. Could optionally mention return behavior or errors, but the current completeness suffices for a dynamic tool that delegates execution.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining that for certain tools, arguments must include owner_token and confirm=true, which goes beyond the schema's generic descriptions.

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

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

Clearly states 'Execute any discovered tool by name with arguments' with a specific verb and resource. Differentiates from siblings by describing the discovery workflow (discover_tools -> get_tool_details -> execute).

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

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

Explicitly instructs when to use: after discover_tools and get_tool_details. Provides prerequisites: ORDER_EXEC and DESTRUCTIVE tools require owner_token and confirm=true. Guides the agent on the correct sequence.

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

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

Annotations already indicate destructive behavior. The description adds context about the approval step and execution order, but does not detail side effects like trade costs or position changes. It is adequate but not exhaustive.

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

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

The description is two sentences plus an example, with no wasted words. It front-loads the core action and is immediately scannable.

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

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

Given the complexity (multi-step approval and execution) and the absence of an output schema, the description provides a reasonable overview. It could clarify return values, but annotations and the example compensate somewhat.

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 value by providing an example of the 'intent' parameter ('Get me $10K AI exposure...'), which helps the agent understand the expected input format beyond the schema 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 tool description clearly specifies that it transforms a natural language trading intent into a concrete plan and executes it, using a concrete example. It distinguishes itself from siblings like 'approve_intent' or 'request_trade_confirmation' by encompassing both parsing and execution.

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 mentions that the tool 'presents plan for approval' before execution, implying a workflow. However, it does not explicitly state when to use this tool versus alternatives like 'approve_intent', leaving some ambiguity.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's job is light. It adds that the tool returns a URL but does not elaborate on side effects (e.g., invalidating previous tokens). No contradiction with annotations.

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

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

Two sentences front-load the purpose and return value, with no extraneous content. Every sentence is necessary and efficient.

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

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

The description covers the tool's action and return value sufficiently for a simple, well-annotated tool. It lacks mention of how to use the URL (redirect user) and the subsequent exchange step, but given sibling tools, this is acceptable.

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 value by listing broker options in parentheses but does not detail user_id or redirect_uri beyond the schema.

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

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

The description clearly states the action ('generate') and the resource ('OAuth authorization URL for a user to connect their broker account'), lists supported brokers in parentheses, and distinguishes this from siblings like 'connect_broker' and 'exchange_broker_oauth_code' by focusing on URL generation.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as prerequisites (user must have a broker account) or next steps (after URL, redirect user and exchange code). It lacks explicit usage context.

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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false. The description adds context about generating a config file and including install instructions, which aligns with the annotations. No contradictions; the description provides additional behavioral context beyond the annotations.

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

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

The description is two sentences with no waste. It front-loads the core purpose, then concisely lists the key options. Every sentence adds value.

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

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

Given the tool has only 2 parameters with simple enums and no output schema, the description is fairly complete. It explains what the tool does, the inputs, and what the output includes. It does not cover error handling or prerequisites, but for a config generation tool, the provided information is 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 input schema has 0% description coverage, so the description must compensate. It lists the IDE options and mode options, adding meaning by specifying tool counts for modes (smart: 181, full: 533). However, it does not explain the effect of different IDEs or the content of the output beyond 'install instructions'. This is adequate for a simple tool but leaves some gaps.

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

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

The description clearly states the tool generates MCP config files for IDEs based on connected brokers and data providers, specifying the file names (mcporter.json / mcp.json) and the supported IDEs and modes. This distinguishes it from the many sibling tools focused on market data, accounts, and other operations.

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 lists the supported IDEs and modes (smart/full with tool counts), providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or alternatives, nor does it state prerequisites (e.g., needing connected brokers). The guidance is mostly implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description complements these by specifying the return type (shareable URL) and noting that no email is needed upfront. It also includes post-payment instructions, adding value beyond 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?

Three precise sentences: first states purpose, second distinguishes from sibling, third provides pricing and actionable next step. No redundant or irrelevant 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 one optional parameter, no output schema, and rich annotations, the description covers the tool's purpose, differentiation, pricing, and post-payment action. It lacks explicit mention of the link format or authentication requirements, but these are either implicit or covered by annotations.

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 coverage, the description partially compensates by noting pricing for each enum option (paper=$29/mo, live=$99/mo). However, it does not explicitly explain the parameter name 'tier' or its default value, leaving some semantic gap.

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

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

The description explicitly states the tool returns a direct payment link for an AlgoChains subscription tier, using a specific verb and resource. It distinguishes from the sibling get_checkout_url by highlighting the pre-configured, shareable nature without email requirement.

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 clearly indicates when to use this tool (when a pre-configured, shareable link is needed) and contrasts it with get_checkout_url. It provides pricing for both tier options, aiding decision-making, but does not explicitly state when not to use it or mention other alternatives.

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

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

Annotations (readOnlyHint, destructiveHint) already confirm safety. The description adds that it returns equity, cash, and buying power, but does not disclose potential pagination, rate limits, or error scenarios. This is adequate but not 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?

A single, front-loaded 12-word sentence efficiently communicates the tool's purpose with no filler. Every word is meaningful.

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

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

The tool is simple with one parameter and an output schema, but the description omits parameter details and context about broker connectivity. It is adequate for retrieval but not fully self-contained.

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 explain the 'broker' parameter. It simply says 'from a broker' without specifying format, allowed values, or meaning (e.g., ID vs name). This fails to add value beyond the schema.

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

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

The description clearly states the action (Get), resource (account information), and specific fields (equity, cash, buying power). It effectively distinguishes this tool from siblings like get_positions or get_connected_brokers.

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 lacks guidance on when to use this tool versus alternatives. No prerequisites, limitations, or contextual conditions are provided. For a simple retrieval tool, some guidelines on broker specification would be helpful.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds valuable detail: it reads from bounded process, script, state, and log evidence, and emphasizes no mutation. This goes beyond annotations by explaining the evidence sources and confirming no side effects.

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 sentences (22 words) with no fluff. It front-loads the core action and adds a clarifying sentence about read-only behavior. Every word earns its place.

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

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

Given the tool's simplicity (no params, no output schema) and rich annotations, the description covers the purpose and evidence sources well. It could hint at the return value format (e.g., 'returns liveness status'), but the lack of output schema makes this acceptable.

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?

No parameters exist, so schema coverage is 100%. The description does not need to explain parameters. Baseline 3 is appropriate; no additional param info is required or 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 clearly specifies reading liveness of adaptive_brain.py daemon from multiple evidence sources (bounded process, script, state, log). This uniquely identifies the tool among many sibling get_* status tools, providing a specific verb and resource.

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

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

The description states the tool is read-only and does not mutate, giving implicit usage context. However, it does not explicitly contrast with sibling tools or specify when to use this over alternatives like get_agent_loop_status. Guidance is adequate but lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by specifying circuit breaker behavior and that limits are hard-coded constants, providing context beyond annotations. No contradictions.

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, no waste. First sentence lists key metrics, second adds behavioral context. Front-loaded and efficient.

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

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

Given no parameters, no output schema, and annotations covering safety, the description fully explains what the tool returns and the circuit breaker consequence. Complete for its complexity.

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?

No parameters exist; baseline for 0 params is 4. Description fully explains all returned metrics and behavior, compensating for lack of output schema. Adds clear value.

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

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

Description clearly states the tool checks AI agent loop detection metrics, listing specific outputs (calls in last 60s, unique call signatures, max identical call count, loop risk level). This distinguishes it from numerous sibling get_* tools, no ambiguity.

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

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

Description implies use for monitoring loop risk but does not explicitly state when to use this versus other monitoring tools like get_system_health. No direct differentiation or alternatives mentioned.

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

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

Annotations already indicate read-only and idempotent, but the description adds value by specifying the advisory nature of the pipeline and what errors are detected, which goes 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 two sentences, front-loads purpose, and provides essential details without fluff.

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

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

The description explains what the tool detects but does not describe the return format or output. Since no output schema exists, this is a gap, though the tool is simple.

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

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

The schema has 0% parameter descriptions and the description does not explain the bot_id parameter (enum mnq, cl, mes, nq). With low schema coverage, the description should fill this gap but 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?

The description clearly states the tool checks 'AI ensemble/debate pipeline health' and lists specific detections (Anthropic quota errors, etc.), making it distinct from sibling health tools.

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

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

The description implies when to use (for pipeline health monitoring) but does not explicitly differentiate from other health tools like get_system_health or specify when not to use 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 declare readOnly and idempotent hints; the description adds detail on what data is returned (mission, goals, etc.) and that it's safe to use. No contradictions with annotations.

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

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

Two short, front-loaded sentences. Every word serves a purpose: clarity, usage guidance, and parameter explanation. No redundancy.

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

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

For a simple read tool with one optional parameter, the description covers what the tool returns and when to use it. No output schema exists, but the description adequately sets expectations.

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 rephrases the schema's enum list and explains the 'all' option, but adds only marginal value beyond the schema's own description. Baseline 3 is appropriate due to high schema coverage.

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

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

The description clearly states the tool reads AlgoChains business identity files (TELOS system) and lists the specific sections returned. It distinguishes from the sibling update_algochains_telos, making the purpose unambiguous.

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

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

Explicitly advises agents to read TELOS at session start for full context and explains how to use the section parameter. Lacks explicit when-not-to-use guidance, but the context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint; the description adds valuable behavioral context by listing the returned fields (daily P&L, win rates, etc.) and data source (real log files), fully informing the agent of expected output.

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

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

The description is two sentences front-loaded with the core action and resource, then output specifics; no wasted words.

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

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

Given no output schema, the description adequately explains the return values and data source, making it complete for a read-only, no-parameter tool.

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

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

With zero parameters and 100% schema coverage, the baseline is 4. The description adds no parameter details, but none are needed.

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

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

The description clearly states the tool returns real-time trading metrics for all 4 specific Tradovate bots (MNQ, CL, MES, NQ) in a single call, distinguishing it from sibling tools that may target individual bots or other metrics.

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

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

The description implies usage for a batch snapshot of all bots but does not explicitly mention when not to use it or suggest alternatives like get_live_bot_metrics.

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

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

Annotations already indicate a safe read-only operation. The description adds value by specifying the exact data elements returned (total events, unique users, etc.), providing useful behavioral context beyond the annotations.

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

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

Single sentence with no wasted words. Information is front-loaded and directly addresses the tool's purpose.

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 analytics tool with two optional parameters and no output schema, the description adequately covers the main output components. It could mention return format or pagination, but is still sufficiently complete.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description only implicitly references the 'days' parameter via 'last N days' but adds no new meaning beyond the schema's 'Lookback period in days'. The 'event_type' parameter is not elaborated.

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

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

The description clearly states the verb 'Get', the resource 'platform analytics summary', and lists specific included metrics (total events, unique users, conversion funnel, top pages, by-day breakdown). This distinguishes it from other 'get_' siblings which cover different analytics or entities.

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?

No usage guidance is provided. The description does not specify when to use this tool versus alternatives, nor does it mention prerequisites, limitations, or when not to use 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 confirm safe read (readOnlyHint=true, destructiveHint=false). The description supplements by detailing what the tool computes (mode, order IDs, prices, protection status) and its purpose (detecting missing stops). No contradictions. The description adds meaningful behavioral context beyond the annotations.

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

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

The description is three sentences, front-loaded with the primary action ('Parse the bot log...'). It covers purpose and return values efficiently. A minor improvement could be combining the last two sentences, but overall concise and free of fluff.

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

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

The tool has one parameter with enum, no output schema, and moderate complexity. The description explains the return categories (mode, IDs, prices, protection status) and the use case, providing most of what an agent needs to interpret results. However, the exact structure of the response (e.g., JSON fields) is not specified, and for a tool lacking an output schema, slightly more detail on the return format would be beneficial.

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

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

Schema coverage is 0%—the schema provides no description. The tool description does not explain the bot_id parameter or its enum values. While the enum values (mnq, cl, mes, nq) are domain-specific, the agent would benefit from explicit clarification that these are bot identifiers for different instruments. The description misses an opportunity to add value.

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

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

The description clearly states the tool parses the bot log to determine bracket order status and lists the return values (mode, order IDs, prices, protection status). It also provides a use case ('critical for detecting missing stops after an entry'), which adds context. However, it does not explicitly distinguish itself from sibling tools like bracket_integrity_check or check_unprotected_positions.

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

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

The description only implies when to use ('after an entry') via the phrase 'critical for detecting missing stops after an entry'. There is no explicit guidance on when not to use this tool or mention of alternatives among the many sibling tools. The agent lacks clear decision rules.

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

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

Annotations indicate read-only and non-destructive behavior. The description adds value by listing the content of the payload (strategy summary, citations, artifact paths, etc.), providing transparency beyond the annotations. No contradictions.

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: first states function, second lists contents and usage. Efficient and well-structured with no wasted words.

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

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

For a simple read operation with one parameter and no output schema, the description provides sufficient context: purpose, contents, and use case. Agent can confidently invoke this tool.

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

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

The single parameter (bot_id) is fully documented in the schema with enum and description. The description adds no additional parameter details. With 100% schema coverage, baseline is 3.

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

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

The description clearly states the tool retrieves complete bot card data for marketplace display, listing specific components (strategy summary, academic citations, etc.). It distinguishes itself from many sibling get_ tools by specifying its purpose.

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

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

The description explicitly mentions using it to populate or refresh a bot card on the marketplace site. Although it doesn't mention when not to use it, the context makes the usage clear. It could be improved by noting alternatives like get_marketplace_listings.

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. The description adds value by specifying the data source (~/.algochains/bot_metrics.db) and that win rates are computed from fill history, which are behavioral details 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 exceptionally concise: two sentences covering purpose, data fields, and source. No filler or redundancy, fitting the critical information into minimal space.

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

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

Given no parameters and no output schema, the description fully informs the agent of the tool's return contents (PIDs, positions, P&L, signals, win rates) and data provenance. It is complete for the tool's low complexity and typical dashboard use case.

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

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

The input schema has zero parameters with 100% coverage, so the baseline is 4. The description does not need to add parameter details, but it also does not mention any optional inputs that might be expected for a dashboard (e.g., date filter), which is acceptable given the explicit real-time nature.

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

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

The description clearly states it returns a real-time dashboard of all live trading bots with specific data fields. However, it does not distinguish itself from siblings like get_all_bot_metrics or get_live_bot_metrics, which may cause confusion for an agent choosing between them.

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

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

No guidance is provided on when to use this tool versus alternatives. With many similar get_* tools for bot metrics, the absence of usage context or exclusions forces the agent to infer appropriateness, risking incorrect selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds context: reads from control-tower host (logs/, state/, ps), no contradiction. Adds value 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?

Three sentences, first sentence defines purpose and scope, second gives examples, third clarifies exclusions and host. No wasted words, well-structured.

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

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

Even without output schema, the description lists what information is returned (process up, log mtime, etc.) and where it reads from. Sufficient for an agent to understand the tool's function.

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

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

Input schema coverage is 100%; the one parameter (bot) is described with defaults and allowed values. Description matches schema, so adds minimal extra meaning.

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

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

The description clearly states the tool provides unified health for live futures bots (MNQ, CL, MES, NQ) and Kalshi, listing specific health indicators. It distinguishes from sibling tools like get_quote and web search.

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

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

Explicitly provides use cases: 'Use for MNQ health check, is the bot running, bot status.' Directly tells when not to use (web search) and offers alternative for live market price (get_quote).

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?

Description adds context beyond annotations: file location, trigger (fill-triggered, not watchdog), and typical schema. Annotations already indicate read-only and non-destructive, so the description enriches behavior without contradiction.

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

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

Concise yet informative. The core action is front-loaded, followed by essential details about trigger and alternatives. No redundant sentences.

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

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

Despite no output schema, the description explains the typical schema and clarifies the file's role versus other monitoring tools. Sufficient for an agent to decide proper 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?

No parameters in input schema, so high coverage. Description adds meaning by detailing that the file is MNQ-only and the schema includes {ts, bot, symbol}, which is useful for understanding what the tool reads.

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

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

The description clearly states the action 'Read ~/.openclaw/bot_heartbeat.json' and specifies the resource, distinguishing it from sibling tools by explaining the file's purpose and trigger mechanism.

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 guidance on when to use this tool versus alternatives: 'For fleet process liveness use get_bot_health / get_all_bot_ops_status; for failover primary use control-tower logs/bot_heartbeat.json.' Also explains the file is MNQ-only and fill-triggered.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it reads a file and returns specific fields, which is useful but does not significantly extend the behavioral profile. The description is consistent with annotations and adds moderate context.

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 sentences long, each serving a distinct purpose: stating the function and return values, and providing usage context. No wasted words, and it is well-structured for quick comprehension.

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 absence of an output schema, the description reasonably explains the return values. It also provides essential context relative to a sibling tool. However, it could mention that the tool is safe and idempotent (though annotations cover that) or potential error conditions. Still, for a simple read tool, it is largely 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?

With schema description coverage at 0%, the description should compensate by explaining the 'bot_id' parameter. However, it provides no additional meaning beyond what the enum schema already shows. The agent must infer the parameter's role from the tool name and description, which is a missed opportunity.

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

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

The description clearly states the verb 'Read' and the resource 'persisted position state file for a bot'. It lists the returned fields and explicitly distinguishes itself from 'get_positions' via comparison for drift detection. This makes it easy to understand exactly what the tool does and how it differs from siblings.

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

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

The description explicitly tells when to use the tool ('internal bot tracking') and provides a comparison to 'Tradovate get_positions()' for drift detection, which serves as a clear alternative. This gives the agent unambiguous guidance on tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it may perform a live bracket integrity check against Tradovate under certain conditions, which is a non-obvious side effect beyond the annotations.

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

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

The description is three sentences: the first states purpose and outputs, the second and third explain conditional behavior. It is efficient but could be slightly more structured (e.g., bullet points for outputs). No unnecessary words.

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

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

The description outlines return values and conditional behavior, but it does not clarify whether the results of the live bracket check are included in the output, nor does it describe error states or format details. Given no output schema, this leaves some ambiguity.

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

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

There are no parameters, so schema coverage is 100%. The description adds value by specifying what the tool returns (last check time, unprotected positions, auto-flatten status), which is meaningful beyond 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?

The description clearly states the tool reads the bracket integrity guardian daemon state and lists what it returns. It uses a specific verb ('Read') and resource, and implicitly distinguishes from sibling 'bracket_integrity_check' by explaining the conditional relationship.

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 explains that the tool may run a live check when guardian is inactive or has zero positions, but it does not explicitly state when to prefer this tool over alternatives like 'bracket_integrity_check'. Usage guidance is implied rather than direct.

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?

Descriptions adds rich behavioral context beyond annotations: it details the guide's contents and enumerates supported brokers. Consistent with readOnlyHint and idempotentHint.

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 key information. Every word adds value—no redundancy or fluff.

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

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

Covers the tool's purpose, outputs, and parameters adequately for a simple retrieval tool. No output schema, but description makes return value expectations clear.

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 parameter 'broker' has no schema description, but the description lists the enum values in text. Doesn't elaborate on the parameter's meaning or constraints beyond that list.

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

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

Clearly states it gets a step-by-step setup guide for specific brokers, listing exactly what's included (env vars, credentials, paper trading instructions, rate limits, risk warnings). Distinguishes from sibling tools like connect_broker or validate_broker_connection.

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?

Implies usage when setting up a broker, but no explicit when-to-use or when-not-to-use guidance. Does not mention alternatives or prerequisites.

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

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

Annotations indicate idempotentHint=true and readOnlyHint=false, meaning the tool is safe to retry and not read-only. The description adds context about post-payment email and activation, but does not disclose whether repeated calls create multiple checkout sessions, or if the URL expires. It also doesn't detail error cases or side effects beyond the stated flow.

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 front-loads the main purpose but is somewhat verbose, repeating tier details already in the schema. It is structured logically (purpose, flow, tiers, instruction) but could be more concise without losing clarity.

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?

Although there is no output schema, the description only says 'Returns a URL' without specifying the exact format or example. It also omits immediate return behavior (is it a redirect URL?), error conditions, and what happens if the email is invalid. The post-payment flow is detailed, but the tool's immediate output is underspecified.

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?

All three parameters are described in the schema (100% coverage), so baseline is 3. The description adds significant value by explaining the tier options with pricing and details, and the referral code purpose, which are not fully captured in the schema descriptions. This makes the parameter meaning clearer and more actionable.

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

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

The description clearly states the tool generates a Stripe checkout URL for an AlgoChains subscription, with a specific verb ('Generate') and resource. It distinguishes the action from siblings like get_started or generate_payment_link by detailing the subscription flow and tier options, though it doesn't explicitly contrast with alternatives.

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

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

The description lacks guidance on when to use this tool versus sibling tools like generate_payment_link or get_started. It explains the tiers but does not specify prerequisites, alternative tools, or scenarios where this tool is inappropriate (e.g., existing subscriptions).

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat that. It adds value by specifying the exact data returned (broker states, trip reasons, timers, velocity) and the nature of the limits (hard-coded, code-level constants). This contextualizes the tool's behavior beyond what annotations provide.

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

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

Two sentences, no filler. First sentence front-loads the action and outputs. Second sentence adds the important constraint that limits are unmodifiable and clarifies usage. Every word earns its place.

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

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

For a parameterless tool with full annotation coverage and no output schema, the description is complete. It explains what the tool returns, its read-only nature, and when to use it. No additional context is necessary.

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?

Tool has zero parameters, so schema coverage is 100%. Per guidelines, baseline is 4. Description adds no parameter instructions, which is appropriate since there are none. The description does not need to elaborate on parameters.

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

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

Description clearly states the tool reads the current state of all hard-coded trading circuit breakers, listing specific outputs like broker states, trip reasons, cooldown timers, and order velocity. It distinguishes itself from siblings by emphasizing these are code-level constants that the AI cannot modify, making its read-only diagnostic purpose unambiguous.

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

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

Explicitly states 'Use to understand why orders are being blocked,' providing a clear scenario for invocation. It also notes the AI cannot modify these limits, indirectly advising against attempting mutation. This guidance is sufficient given the tool's simplicity and the presence of sibling tools like check_order_safety.

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 indicates a read operation ('list'), but annotations show destructiveHint=true and readOnlyHint=false, suggesting mutation. This contradiction severely misleads the agent about the tool's 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 description is a single, clear sentence. It is concise but lacks important details; nevertheless, it earns points for being front-loaded and well-structured.

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

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

Despite having only one parameter and no output schema, the description does not cover token expiry format, scope details, or potential pagination. Given the contradictory annotations, the tool definition is incomplete.

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 does not explain the single required parameter user_id. With 0% schema description coverage, the description fails to add meaning beyond the parameter name and type.

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

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

The description clearly states it lists all brokers a user has connected via OAuth, including token expiry and scope information. This is specific and distinguishes from sibling tools like connect_broker and revoke_broker_connection.

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?

No guidance on when to use this tool versus alternatives, or any prerequisites. The description only states the function without any contextual usage advice.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, etc., so the description adds contextual behavior: 24-hour caching via a parameter, weekly release schedule, and the requirement of an EIA_API_KEY. No contradictions with annotations.

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

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