set_saved

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

With no annotations, the description carries the full burden. It usefully discloses the downstream effect ('Only saved elements appear in results'), which is real behavioral context beyond the name. However, it does not say whether setting saved=false removes previously written results, whether the change persists across runs, or what permissions are needed for a mutation operation.

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, front-loaded with the action and followed by the consequence. No filler, though the phrasing 'saved (or not saved)' is slightly awkward given the parameter already carries the polarity.

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 4-parameter mutation tool with 0% schema description coverage, no annotations, and no output schema, the description is thin. It omits what model/config refer to, whether the operation is reversible, and how it interacts with existing result files, so an agent cannot call it confidently.

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 0%, so the description must compensate. It hints at the 'names' parameter ('named variables or parameters') and the boolean toggle ('saved (or not saved)'), which maps to the 'saved' parameter and its default. But 'model' and 'config' — two of the three required parameters — are never explained, leaving the highest-risk inputs undocumented in both schema and description.

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?

States a specific verb ('mark ... as saved') and resource ('named variables or parameters'), and clarifies the scope ('to the result files'). It does not explicitly distinguish itself from close siblings like set_values or set_run_settings, but the purpose is unambiguous.

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?

No explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The clause 'Only saved elements appear in results' implies the context in which this matters, which is more than nothing but still leaves the agent to infer when to reach for this versus set_values or set_run_settings.

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