spidra_save_preset

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely non-obvious behavior: cookies are never stored, config must be the exact request body that target tool accepts, and updates are partial (only the fields passed change). It does not say whether the update is idempotent or what errors arise from a bad config.

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?

A one-line purpose statement followed by three tight bullets, one per mode. Every sentence carries information an agent needs, and the create-vs-update distinction is front-loaded.

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 an 8-parameter tool with nested objects and no output schema, the description covers the input modes well but says nothing about what comes back — notably whether a presetId is returned on creation, which the agent needs in order to later update or run the preset. That omission leaves a real gap in a create/update tool.

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 88%, so the schema already documents most fields; the description still adds cross-field semantics that per-property descriptions cannot express — which fields pair with which kind, and that presetId switches the call from create to partial update. This is meaningful value beyond the schema, though it doesn't cover the optional description field or validation rules on name.

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 opening sentence states a specific verb and resource — save (or change) a preset — and frames the value proposition ("so it can run again with one call"), which distinguishes it from siblings like spidra_run_preset, spidra_list_presets and spidra_delete_preset. The two-mode structure (create vs. change) is made explicit immediately.

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?

It clearly specifies when to use each shape: template presets need kind/template/inputs, tool presets need kind/tool/config, and updating requires presetId plus only the changed fields. It also cross-references spidra_create_monitor for the monitoring use case, though it gives no exclusions or prerequisites (e.g., whether a preset must already exist, or which kind to prefer).

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