headless-oracle

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

With no annotations, the description fully covers behavioral traits: it notes the tool is not cryptographically signed, does not reflect real-time circuit breaker halts or KV overrides, includes fail-closed behavior, latency (sub-100ms), and specifics like lunch breaks and Middle East weekend schedules.

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 detailed but well-structured with clear sections (purpose, usage, specifics, returns, caveats). It is front-loaded with the core purpose. Some redundancy could be trimmed, but overall concise for the complexity.

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

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

Given no output schema, the description adequately explains return fields (mic, name, timezone, etc.) and important context (not signed, fail-closed, lunch breaks). Missing some details on settlement_window and data_coverage_years, but overall complete for the single-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?

The only parameter (mic) is fully described in the input schema (enum, default, reference to list_exchanges). The tool description adds no additional semantic detail beyond reiterating '28 exchanges,' so 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?

The description clearly states the tool returns a holiday-aware trading session schedule with next open/close UTC timestamps for 28 exchanges. It distinguishes from siblings by noting that for authoritative signed status, one should use get_market_status.

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?

A dedicated 'WHEN TO USE' section lists specific scenarios such as planning trade execution windows, checking market hours, holiday closures, and early closes. It also provides a fail-closed instruction and implies when not to use (for signed status, use get_market_status).

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 fully discloses behavioral traits: read-only behavior, signed attestation with 60s TTL, fail-closed rule for UNKNOWN/HALTED, latency sub-200ms, and use of attestation_ref in downstream flows. 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 is lengthy but well-organized with clear sections (purpose, usage, safety rules, returns, latency, exchange list). Every sentence adds value, though it could be slightly more concise.

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

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

Covers all relevant context: 28 exchanges with MIC codes, return fields, safety rules, TTL, fail-closed, attestation for auditing, latency, and disambiguation of SMA. No output schema needed as return fields are explained.

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 a well-documented enum. The description adds value by grouping exchanges (equities, derivatives, crypto) and providing examples, plus linking to list_exchanges for discovery.

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 an Ed25519-signed market-state receipt for pre-trade verification. It distinguishes itself from siblings like get_market_schedule and list_exchanges by specifying its role as a safety gate before trade 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?

Provides explicit when-to-use instructions: 'call this BEFORE executing any trade', 'USE AS: pre-trade check', and rules for safe execution (status must be OPEN, receipt not expired). Includes fail-closed handling and guidance when tool is unreachable.

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 provided, but description fully discloses behavior: no authentication required, always returns 200, returns specific structure. No contradictions exist.

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

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

Front-loaded purpose, structured with WHEN TO USE and RETURNS sections. Slightly verbose due to list of return values, but each sentence 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?

With no params or output schema, description fully covers purpose, usage, return format, authentication, and error behavior. No gaps identified.

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 has zero parameters, baseline 4. Description adds significant meaning by detailing the return object structure (sandbox, x402_per_request, etc.) and their interpretations.

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 payment and authentication options for market data, distinguishing from sibling tools like get_market_schedule and list_exchanges which are about schedules and exchange lists.

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?

Contains explicit WHEN TO USE guidance: 'when you need to understand how to authenticate or pay before making a request that requires a key or payment.' Clarifies model-agnostic behavior.

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 provided, the description fully discloses behavior: static data, always returns 200, no authentication required, sub-50ms p95, model-agnostic, and SEC/CFTC compliant. 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 is thorough but somewhat verbose; includes a long list of exchanges. It is structured with clear sections and front-loaded key information. Every sentence adds value, but could be slightly more concise.

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

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

Given no output schema, the description provides full return structure with field names and types. It covers all necessary context: purpose, usage, behavior, and output details. Completeness is high.

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 (input schema empty), so schema coverage is 100%. Baseline for 0 params is 4. The description adds no parameter info, but that's expected; it compensates by detailing the return structure.

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 a directory of all 28 supported exchanges with specific fields, and distinguishes from siblings (get_market_status, get_market_schedule) by positioning it as a discovery step before those calls.

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 includes 'WHEN TO USE: call once at agent startup to discover supported markets before calling get_market_status or get_market_schedule', providing clear guidance on when and in what sequence 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.