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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavioral context: no full row dumps, displaySavedChart performs no broker read or runtime execution, original data timestamps are retained and prices are not refreshed, and includeProgram surfaces revision linkage. These are non-obvious operational traits (cost, staleness) that annotations do not encode.

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?

Purpose is front-loaded in sentence one and each subsequent sentence carries actionable content (staleness, no-refresh, per-flag routing, generic-name caveat). Slightly overlong: the reuse/refetch sentence ('Reuse full calculation history for the same source and period...') is operational policy that sits away from the tool's core job and could be tighter.

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?

No output schema and only three parameters, so the description must carry the burden, and it does: it explains what comes back (schemas, IDs, derivations rather than rows), the freshness guarantees, and the two opt-in behaviors. An agent has everything needed to call it correctly and interpret the result.

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%; the two booleans are documented in the schema, and the description adds the intent behind each (includeProgram = exact saved code for an edit; displaySavedChart = reopen unchanged chart). analysisRunId is undocumented in the schema but its meaning is implied by 'one completed analysis run in the current conversation'. Value is added over the schema, though the run-id scoping (current conversation only) could be stated more explicitly.

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 first sentence names a precise verb (Read) and enumerates the exact resources returned: durable datasets, stable semantic element IDs, and view bindings from one completed analysis run. It also bounds the scope against neighboring read tools ('schemas, stable IDs, and derivations, not full row dumps') and points at internal_data.get for row access, so an agent can distinguish it from query_data or resolve_analysis_reference without opening any schema.

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?

Gives an explicit precondition ('Use this before resolving any chart-derived value or condition') plus per-flag routing: includeProgram=true for a follow-up chart edit, displaySavedChart=true to reopen without a new program. It also states when not to rely on it ('does not infer behavior from indicator names, labels, or user wording'). It stops short of naming the sibling tool (e.g. resolve_analysis_reference or query_data) that handles the fallback case, so alternatives remain implicit.

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