NakamotoNotes Bitcoin Barometer

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds behavioral value by disclosing the response content (measurement, current value, heat, score contribution), which matters because there is no output schema.

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 with the tool's function in the first clause, then the valid names. The name list is long but carries real information absent from the schema; no wasted 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?

With no output schema, the description steps in to say what comes back (value, heat, score contribution), and the enumerated names cover the main failure mode of an invalid parameter. Minor gap: no note on error behavior for an unrecognized 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?

Schema coverage is nominally 100%, but the only schema text is the bare 'Indicator name' and there is no enum constraint. The description compensates meaningfully by enumerating the ten valid names (monthlyRSI, mvrvZScore, fearAndGreed, etc.), which the schema does not provide.

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?

States a specific verb (explain) and resource (one Barometer indicator) plus the three things it returns: what it measures, current value/heat, and score contribution. This is clearly distinct from siblings get_history and get_market_snapshot, which concern history and snapshots rather than single-indicator explanation.

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?

Usage is only implied by the phrasing 'what one indicator measures' – an agent can infer this is the lookup-by-name tool, but there is no explicit statement of when to use this versus get_history or get_market_snapshot, and no exclusions 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, covering the safety and mutability profile. The description adds useful context that the source is 'public' daily history and that boundaries are inclusive, but says nothing about range limits, pagination, or partial-data behavior for a potentially large date span.

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 fragment with no filler, immediately delivering resource, range semantics, format, and source. It is a sentence fragment lacking an explicit verb ('Returns...'), which is a minor stylistic weakness but costs no 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?

With no output schema, the description must convey return shape, and it only implies one record per day via 'Daily' without stating whether a multi-day range yields an array of day entries or how zones are represented. For a simple two-param read with rich annotations, this is adequate but leaves the response contract partly unspecified.

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% and both schema descriptions already state 'YYYY-MM-DD' for first/last day, so the description largely repeats the format. The one genuine addition is the word 'inclusive', clarifying boundary handling, which the schema does not state — enough for a solid baseline but not rich param 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?

The description names the returned resource concretely — 'Daily Heat Score and zone between two dates' — and its source, 'the public daily history,' so an agent knows this is a historical daily-metric fetch rather than a live lookup. It does not distinguish itself from siblings like get_market_snapshot or explain_indicator, which is the only gap preventing a 5.

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?

There is no statement of when to use this tool versus get_market_snapshot (current state) or explain_indicator (metric explanation). The date-range phrasing implies historical retrieval, but no alternative is named and no exclusion is given, leaving the agent to infer routing.

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, openWorld, non-destructive, so the safety profile is covered. The description usefully adds that the output is descriptive rather than advisory, but with no output schema it could say more about the shape and freshness of the returned 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?

A single front-loaded sentence that lists the returned fields and closes with the scope qualifier. No padding, though the enumeration is dense enough that a reader must parse carefully.

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 output schema, the description carries the burden of describing returns, and it does so reasonably: heat score range, zone, price deltas, and the ten-indicator breakdown with value/heat/meaning. An agent knows what it will get back.

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?

Zero parameters, so there is nothing to document; the schema is trivially complete. Baseline 4 applies.

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 resource (Bitcoin Barometer snapshot) and enumerates its contents: heat score, zone, price with 24h/7d change, and ten indicators. It's clearly distinct from explain_indicator and get_history, though it never explicitly contrasts itself with 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?

'Descriptive only.' signals a constraint (no predictions/advice) but gives no when-to-use guidance or routing to siblings. An agent learns nothing about when to prefer this over get_history or explain_indicator.

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