decker

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

Details raw contract, zero recompute, engine-native vocabulary, and that absent fields are null. Clearly states it is a market-state reading, not a trade instruction. No annotations to contradict.

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?

Description is lengthy and includes dense domain jargon (e.g., 'verified anchor', 'direction_resolved'). While it front-loads the core purpose, the extensive detail reduces conciseness.

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 thoroughly explains the game block fields and engine context. However, the technical depth may obscure practical usage for an AI agent.

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 covers two params with 50% description coverage; description merely restates 'symbol/timeframe' without adding new semantics beyond the schema. No additional constraints or usage details for 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 tool retrieves 'current engine structural state for a symbol/timeframe' and explicitly distinguishes from siblings like decker.get_view and decker.validate_intent. Purpose is specific and well-defined.

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 guidance on when to use alternatives (human-language view via get_view/get_reading) and includes a caution to check intent with validate_intent before execution. Lacks explicit 'when not to use' 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?

No annotations are provided, so the description carries the full burden. It discloses that output is in customer-facing language, lists the elements returned, and explicitly states that raw fields are excluded. While it could mention read-only nature or data freshness, it is fairly transparent for a read operation.

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 purpose. The first sentence lists all output components, which is informative but slightly verbose. The second sentence efficiently clarifies usage boundaries. It earns its place with no wasted words, though could be tightened slightly.

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

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

Given no output schema, the description compensates by detailing the output structure (state description, bias scores, break targets, MTF verdict, execution hint). It also explicitly states what is not included (raw fields). This provides sufficient context for an agent to understand what to expect from the tool's response.

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

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

Schema coverage is 67% (all params have descriptions except 'tf' has only enum). The description adds context by linking the tool to 'symbol/timeframe' but does not extend parameter meaning beyond the schema. A baseline of 3 is appropriate as the description does not significantly enhance parameter understanding.

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 provides an 'AI-synthesized market reading for a symbol/timeframe' and enumerates specific output components (current state, bias scores, break targets, MTF verdict, execution hint). It distinguishes itself from siblings by explicitly stating that engine-native raw fields are not exposed and directing to alternatives, making the purpose unmistakable.

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

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

The description explicitly tells when to use (get a customer-facing reading) and when not to (for raw fields use REST or decker.get_market_state). This provides clear guidance on alternative tools, which is optimal for an agent deciding between tools.

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

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

Discloses key behaviors: signals are retained on age (turn-retention policy), risk_reward_ratio computed on displayed coordinates, action_gate is a posture not an order. Warns about checking freshness_state before treating old pending rows as current. No annotations provided, so description carries burden transparently.

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?

Packs substantial detail without redundancy. Each sentence adds value. Somewhat dense but efficient for the complexity. Front-loaded with core output description; subsequent sentences add behavioral and usage nuances.

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 5 parameters, no required, no output schema, no annotations, the description is remarkably complete. Explains output shape, retention policy, gate stance, filtering, and cross-tool dependency (validate_intent). Addresses potential misinterpretation of stale signals.

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

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

Schema coverage is 80% (high), baseline 3. Description adds value beyond schema: clarifies timeframe can yield opposite directions on different horizons, explains action_gate filter excludes rows with no gate. These enrich parameter understanding.

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 returns active trading signals for the current user with overlay applied, listing key fields (coordinates, decision, action_gate, progress, MTF verdict, summary_ko). It distinguishes from siblings by being signal-specific, though not explicitly contrasting.

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

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

Provides clear guidance on when to use the tool (before placing orders, check intent with validate_intent). Explains action_gate as a stance not an order command. Does not explicitly compare with alternatives like get_reading or get_market_state.

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

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

Despite no annotations, the description discloses key behaviors: items carry a slim game tag, ascending order by bar_ts, and honest gaps where bars are absent. It explains the difference from get_market_state. Read-only nature is implied but not explicitly stated.

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, front-loads the purpose, and uses clear parenthetical clauses. It avoids redundancy while covering key aspects. Could be slightly more streamlined, but no major waste.

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

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

Given no output schema, the description adequately explains the return structure (slim game tag fields), ordering, and gap handling. It also references the sibling tool for schema context. Lacks only details on pagination beyond the limit parameter.

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

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

Schema coverage is 50% (2 of 4 parameters have descriptions in schema). The description adds context about ordering and gaps but not about individual parameters beyond what the schema provides. Baseline 3 is appropriate as the schema does some work, but further detail would help.

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 is a per-bar state timeline for a symbol/timeframe, and distinguishes itself from the sibling tool decker.get_market_state by noting the slimmer game tag. It provides a specific verb ('read status transitions') and resource (state timeline).

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 when to use this tool ('read status transitions across bars to see how the target game unfolded') and implies it is for detailed bar-by-bar analysis. However, it does not explicitly state when not to use it or list alternatives among siblings.

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

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

No annotations are provided, so the description must disclose behavior. It accurately describes the return content (3 base skills and the user's selected one) and implies a read-only operation, but does not mention authentication requirements or potential failure modes.

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. The key information is front-loaded, making it easy for an agent to quickly understand 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?

Given the lack of parameters and output schema, the description covers the essential return structure. However, it could be slightly more precise about the format of the user's selected skill (e.g., index or name).

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, and schema description coverage is 100% trivially. The description adds value by explaining what will be returned, meeting the baseline for zero-parameter tools.

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 that the tool retrieves a trading skill catalog and the user's currently active overlay, naming the three base skills and indicating the user's selection. This distinguishes it from sibling tools like decker.get_market_state or decker.get_signals.

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

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

The description implies the tool is for retrieving user skills but does not provide explicit guidance on when to use it versus alternatives, nor does it mention prerequisites or exclusions.

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

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

With no annotations, the description carries full burden. It discloses that the output is a 'market-state reading, NOT a trade instruction' and explains the layer and output components. However, it does not mention authentication, rate limits, or side effects, which are minimal for a read-only tool.

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

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

The description is a single paragraph that is well-structured and front-loaded with purpose. It is slightly verbose but every sentence adds value. Could be slightly more concise, but overall effective.

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 thoroughly enumerates the return values (verdict, alignment, narrative, coordinates, self-scoring verdicts). It covers the default timeframe and layer, making the output understandable for an AI agent.

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 context: for 'tf', it explains optionality and default; for 'symbol', it gives examples and notes coverage limitations, enhancing understandability 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 that the tool returns 'the engine's VIEW for a symbol' and specifies the components it includes (verdict, alignment, narrative, coordinates, etc.). It distinguishes itself from sibling tools like get_market_state by emphasizing 'interpreted view' vs. 'raw engine fields'.

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 to prefer this over get_market_state for interpreted views and instructs to check decker.validate_intent before placing orders. This provides clear when-to-use and 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?

No annotations are provided, so the description carries the burden. It discloses the behavioral side effect that it immediately affects subsequent get_signals calls and downstream channels. But it does not mention permissions, reversibility, or other safety aspects.

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, front-loaded with the action verb, and every word adds value. There is no 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?

For a simple mutation tool with one parameter and no output schema, the description covers the core behavior and impact. It lacks mention of return value or error conditions, but that is not critical given the simplicity.

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 no extra meaning beyond the schema's brief parameter description. The schema already documents the parameter as 'trading_skills.id' with an example.

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 'Change' and the resource 'active trading skill overlay'. It also notes the effect on subsequent calls, making the purpose specific and distinguishable from sibling tools which are all read or validation 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 implies when to use the tool (to change the overlay) by stating its immediate effect on get_signals calls. However, it does not explicitly state when not to use it or provide direct comparisons to 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?

Without annotations, the description carries full burden. It discloses that the tool returns a stance reading, not approval; explains the gate vocabulary and side_alignment; notes persistence to an auditable ledger; and clarifies the meaning of 'covered=false'. It does not explicitly state non-destructiveness, but the 'pre-trade check' nature implies 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 well-structured, front-loading purpose and usage. Every sentence adds value, though the text is dense and could be slightly more concise without losing meaning.

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 output schema and annotations, the description covers the essential semantics: what is checked, what is returned, how to interpret cover=false, and the non-approval nature. A minor gap is the lack of explicit return structure fields beyond stance and side_alignment.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions). The description does not add new insights beyond the schema, so baseline score 3 applies per guidelines.

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 is a 'Pre-trade gate check for a proposed order intent' and instructs to call it BEFORE placing any order. It specifies the verb 'validate intent' on the resource 'proposed order intent', and the contrast with sibling tools (which are read-only state queries) is implied by the ordering guidance.

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 'Call this BEFORE placing any order through any execution tool', providing clear context. It also explains how to interpret results (e.g., 'covered=false means ... treat as unknown'). However, it does not exclude any scenarios or mention alternatives among siblings.

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