save_definition

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

With no annotations, the description carries the responsibility for behavior. It usefully discloses that saving is versioned and previous versions are kept, and that the returned explanation is meant for telling the user what was saved in plain English. It does not cover permissions or the exact effect of overwrite, but what it does disclose is substantive.

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 three sentences with no filler, covering the core action, a key parameter, versioning, and user-facing output in a compact structure. It is front-loaded with the main purpose and remains readable.

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 has nine parameters and no annotations, and the output schema only covers the return shape. The description addresses only a small fraction of the parameter space, leaving most inputs ambiguous. An agent could handle the simplest save but would be under-equipped for complex definitions or overwrite semantics.

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%, so the description needs to compensate, but it only explains `copy_of`. The other eight parameters, including basis, entity, params, signal, aliases, overwrite, and description, remain unexplained. This leaves the agent guessing about most of the input semantics.

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 states a clear verb, 'save', and resource, 'definition', and specifies it saves the definition the user has chosen. It also distinguishes the copy_of sub-behavior with a concrete example. This clearly separates it from sibling tools like list_definitions or delete_definition.

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 implies usage when the user has chosen a definition to save, but provides no explicit when-to-use or when-to-avoid guidance. It does not mention alternatives such as propose_definition, nor does it clarify when to use copy_of versus a fresh save beyond one line.

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