load_map

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavior: the header is validated before PyMOL is touched, so malformed files fail without leaving a half-loaded object, and the load is confirmed rather than assumed. It also explains the deliberate provenance default and the reasoning (isosurfaces render identically regardless of origin), which prevents an agent from making a false claim about data provenance.

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 core action is front-loaded in the first sentence, followed by the atomicity guarantee and then the provenance rationale. The third paragraph is longer than strictly needed — the 'somebody observed a generated volume' illustration is persuasive prose rather than operational detail — but every paragraph carries distinct information, so nothing is filler.

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?

The tool is simple (three parameters, one required), an output schema exists to describe the geometry report, and annotations cover the safety profile. The description fills the remaining gaps — failure atomicity, confirmation of load, and provenance policy — leaving nothing an agent needs in order to call it correctly or 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 100%, so the baseline is 3, but the description adds real meaning: it explains why provenance defaults to 'unknown' rather than being inferred, and that the returned report surfaces MRC labels and filename tokens the caller can use to set it. That is rationale and workflow beyond the schema's flat description, though it does not cover the 'name' parameter's sanitisation behavior in more depth than the schema already does.

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 and resource ('Load a volume into PyMOL') plus two side effects (records provenance, reports geometry). Combined with the schema's 'MRC/CCP4 volume' path description, an agent can distinguish this from load_structure, load_session, and load_ensemble 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?

The description establishes a clear workflow context: the header is parsed and the report shows what the file says about itself so the caller can declare provenance. It gives actionable guidance on the non-obvious parameter ('never guessed', default unknown). It stops short of naming alternatives or exclusion conditions, so it lands at clear-context-without-routing rather than a 5.

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