scan

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

The description adds substantial behavior beyond the readOnly/openWorld/destructive annotations: throughput caps, time estimates for sma200 scans, six-hour bar caching, the distinction between condition-false, warming-up, and no-data misses, and guaranteed truncation reporting. This is exactly the kind of operational detail an agent needs and is not present in 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 dense but every sentence earns its place: purpose, cost/throughput, caching strategy, miss semantics, and truncation guarantees. It is appropriately sized for an 11-parameter tool with no output schema and contains no filler or repetition.

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

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

For a complex tool with 11 parameters, no output schema, and no nested objects, the description covers operational behavior, cost, caching, and truncation. It stops short of describing the exact shape of the result payload, which is notable because there is no output schema to fill that gap, but the description still covers the most critical invocation concerns.

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 73%, with descriptions on many parameters already. The description adds meaningful cost semantics for max_symbols and max_seconds, noting that raising max_symbols past 30 will likely time out, and that overlays like sma200 are expensive. This goes beyond the schema's simple defaults and helps the agent set realistic parameter values.

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

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

The description opens with a specific verb and resource: 'Run a condition across many IDX stocks at once'. It also distinguishes itself from alert_check by framing the tool as 'alert_check for stocks you have no rules for', which lets an agent immediately tell it apart from a closely named sibling.

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

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

It gives clear practical guidance: use this for condition sweeps, default to watchlist, and sweep broadly once then iterate because bar pages are cached. It does not explicitly name alternative scanning tools like screener or technicals, but the alert_check contrast plus the caching/iteration advice gives enough context for most routing decisions.

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