wells_vs_model

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

Annotations only declare that this is not read-only, not idempotent, and not destructive; the description adds the operationally important behavior: which sample classes are excluded (null/out-of-survey/out-of-grid), that boundary policy governs shared-face samples, and that results are cross-checked by independent point-containment and RMSE validations. It does not say whether the call returns results synchronously or enqueues a job (despite an idempotency_key parameter), which is a meaningful behavioral gap for a compute operation. No contradiction with 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?

Six short sentences, front-loaded with the core comparison, then confirmations, outputs, exclusions, validation, and non-goals. No sentence repeats the tool name or restates schema text; each adds a distinct decision-relevant fact.

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?

Report contents (per-well/region error statistics, sample CSV with IJK) and exclusion semantics are well covered for a tool with no output schema. However, for a heavy nested-request compute call the description never states the return shape at the level of run semantics — whether it blocks for results or returns a job handle, and how idempotency_key behaves — leaving the agent to guess what comes 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?

Schema coverage is 100%, so the baseline is 3; the description earns an increment by explaining the intent behind the confirmation-gated inputs (curve units, max survey gap, boundary policy) and tying them to the required user sign-off. It doesn't touch execution policy, sampling stride, or idempotency key, so it doesn't fully annotate the request envelope.

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 states a specific verb (compare) plus both resources (immutable model PORO/NTG vs. mapped original LAS curves along XYZ/MD surveys), which no sibling tool description implies. The closing sentence explicitly bounds the operation ("point comparison, not automatic log upscaling or calibration"), so an agent can distinguish it from model_diff, model_qc, or property-assignment tools without opening the 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?

States the preconditions for correct invocation: user must confirm curve units, maximum survey gap, and shared-boundary policy before calling. The negative scope statement ("not automatic log upscaling or calibration") tells the agent when this tool is the wrong choice. It stops short of naming an alternative sibling tool for the upscaling/calibration case, so a 4 rather than 5.

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