sd_save_package

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable context that the save overwrites in place and is restricted to already-saved packages, clarifying the exact mutating behavior beyond the raw hints. No additional side effects are mentioned, but the in-place nuance is useful.

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 a single sentence that front-loads the core action ('Save one already-saved open package in place') and adds a critical exclusion in a second clause. Zero waste, every word earns its place.

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 an output schema and simple parameters, so the description need not explain return values. However, it omits the purpose of the required confirm parameter, which is crucial for a destructive operation. The description tells what the tool does but not what the confirm boolean is for, leaving a gap for correct invocation.

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%, meaning the description must compensate for parameter meaning, but it does not. The schema defines package and confirm, but the description gives no hint about what confirm means (likely a safety acknowledgment) or how package should reference an already-saved open package. This is a major gap.

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 clearly states the tool saves an already-saved open package in place, using a specific verb and resource. The explicit 'never performs Save As' directly distinguishes it from the sibling sd_save_package_as tool, making the purpose 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?

The description provides clear context: use for existing open packages that already have a save location. 'Never performs Save As' is an explicit when-not condition, implying alternatives exist for save-as scenarios. It could have named the alternative tool explicitly, but the guidance is sufficient.

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