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

Annotations set readOnlyHint=false and idempotentHint=false. The description is consistent with these settings by disclosing the write side effect: every result is persisted with its source run, expression, value or condition state, timestamp, and evidence. It also discloses the downstream handoff through resolutionId for authorization, which is context the annotations do not provide. It does not discuss failure modes such as unresolved references or run-not-completed errors.

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 front-loaded: purpose first, then the either-or constraint, then the example, then the safety and lifecycle notes. Each sentence carries information, although the inline example is long and could be condensed. The 'resolution, not expression' clarification is slightly awkwardly worded but still earns its place as disambiguation.

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 high-complexity tool with nested unions and no output schema, the description covers the inputs well and tells what is persisted. However, it only partly describes the return payload: it mentions resolutionId and stored evidence but not the overall response shape, so an agent does not know exactly what a resolved value or condition state looks like on return.

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%, so the baseline is 3. The description still adds value by stating the either-or constraint on elementId and resolution, and by clarifying the envelope field name: 'The structured field is named resolution, not expression.' That directly prevents a likely invocation error for a deeply nested schema. The worked example for a latest-field comparison further illustrates the aggregate reducer and comparison shape, beyond what the schema strictly documents.

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 concrete verb and resource: deterministically resolve one semantic element or one structured expression against the full durable dataset of a completed analysis run. It also distinguishes this tool from sibling tools by mentioning that the elementId comes from inspect_analysis_artifact and that the run comes from run_data_analysis, so an agent can tell when to call this tool instead of those two.

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 a clear precondition: this tool only works after a completed analysis run. It also gives a rule for choosing the input: pass exactly one of elementId or resolution. It includes a 'never copy a displayed chart number into a trade payload' warning and tells the caller to use resolutionId for a later authorization action. It does not explicitly say when to choose inspect_analysis_artifact instead, so it falls short of naming alternatives, but it is strong usage guidance.

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