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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the safety profile is covered. The description adds the useful fact that this is an internal UI-driven callback rather than an agent-facing mutation. It says nothing about what is persisted, whether concurrent edits conflict, or what happens when idempotentHint=false is combined with a specHash field.

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?

Two short sentences, no filler, and the most important constraint (do not call directly) is stated up front. Nothing to trim.

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 mutation tool with a nested free-form object, zero parameter documentation, and no output schema, the definition is thin. The internal-callback framing and the pointer to mutate cover the selection problem well, but an agent that did need to understand the call would have nothing on mutations or specHash to go on.

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 description coverage is 0% and all three parameters (id, specHash, mutations) are undocumented in both schema and description. The free-form nested mutations object with additionalProperties=true is entirely opaque, and specHash looks like an optimistic-concurrency token that is never explained. The description must compensate here and does nothing.

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?

Says it is invoked by the Valem card when a user edits a stored model, which gives a rough verb+resource. But 'edit' is never defined: it doesn't say whether it patches the model spec, records an audit entry, or something else, and 'stored model' isn't tied to any of the model-related siblings. An agent can't tell what actually changes.

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?

'Not for direct use: call mutate instead' is an explicit exclusion plus a named alternative, which is exactly what routing guidance looks like. It lacks a positive statement of the conditions under which the tool is legitimately invoked, but since agents are told not to call it, that gap costs little.

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