Save Document

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

Beyond the destructiveHint annotation, the description discloses a non-obvious side effect: it hides producer-input objects before saving, explains the resulting failure mode if this is not done, and tells the caller how to preserve explicit visibility overrides. This is exactly the kind of behavioral context an agent needs.

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 front-loads the core purpose in one clear sentence, then adds a focused paragraph about the one non-obvious parameter. Every sentence provides useful information, with no filler or redundancy.

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 two-parameter save tool with destructive annotations and no output schema, the description covers purpose, parameter semantics, side effects, and a conditional usage scenario. An agent has enough information to invoke the tool correctly and understand the consequences.

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 carries the full burden. It thoroughly explains visibility_hygiene's default, effect, rationale, and how to opt out, and it clarifies that path refers to a .FCStd file path. This goes well beyond the bare schema titles.

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 first sentence, 'Save the active document to the given .FCStd path,' names a specific verb and resource with the exact file format. This clearly distinguishes save_document from siblings such as open_document, close_document, and transaction_commit.

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: call this to persist the active document to a .FCStd file path. It does not explicitly name alternatives or exclusion conditions, but the action is sufficiently distinct among the sibling tools that an agent can infer when it is appropriate.

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