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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that object_context is present only when a recent trigger bar exists and null otherwise (including for individual KRX stocks), that internal reason codes are scrubbed, that reverse_direction_conflict appears only under specific conditions, and that execution_hint.preferred_direction is independent of the setups. This is rich, transparent context beyond any structured data.

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, densely packed paragraph with long nested clauses and parentheticals (e.g., the object_context exception, the scrubbing note, the reverse_direction_conflict condition). While every detail is relevant, the lack of sentence breaks and structured formatting makes it hard to digest. It could be improved by separating the main purpose from the detailed field behavior.

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?

Since there is no output schema, the description must explain the return values. It does this thoroughly: the main output fields (current state, bias scores, break targets, MTF verdict, execution hint) are listed, and important edge cases (null object_context, scrubbed fields, conflict detection, setup mismatch) are covered. While not exhaustive (e.g., it doesn't enumerate all possible values of stance), it provides sufficient detail for an agent to correctly interpret the tool's output for a complex domain.

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 67% (symbol and include_tfs have descriptions, tf has enum/default but no description). The tool description does not go into parameter semantics; it only generically mentions 'symbol/timeframe' and 'MTF verdict per timeframe'. It adds little beyond the schema, and since coverage is moderate (not high or low), the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'AI-synthesized market reading for a symbol/timeframe' and lists the specific content (current state, bias scores, break targets, MTF verdict, execution hint). It explicitly contrasts with sibling tool decker.get_market_state by stating that 'Engine-native raw fields are NOT exposed here — use the REST raw contract (GET /public/reading) or decker.get_market_state for those', which differentiates it from its 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 guidance on when to use alternatives: 'use the REST raw contract (GET /public/reading) or decker.get_market_state for those' when raw fields are needed. It also gives actionable usage caveats about execution_hint, warning that the preferred side must have a non-null setup before treating it as actionable, and explains when object_context.reverse_direction_conflict matters.

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