export-actor

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

No annotations are provided, so the description carries the full transparency burden, and it does so well. It discloses the local file-write side effect, full-fidelity document contents, the exportSource envelope, round-trip compatibility with Import Data, token-instance capture, and the overwrite refusal unless overwrite:true is set. These are the key behavioral traits an agent needs to invoke it safely.

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 action and uses three information-dense sentences with no filler. Each clause adds necessary context: fidelity, round-tripping, token support, and overwrite behavior. The structure makes the tool's purpose immediately clear.

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 complex export operation with no annotations and no output schema, the description covers the purpose, the backup/restore use case, the full-fidelity format, the token-instance option, and the overwrite guard. The schema covers all three parameters, so an agent has everything needed to invoke the tool correctly.

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 100%, so the schema already documents identifier, localPath, and overwrite completely. The prose reinforces identifier's token-instance meaning and the local-file nature of localPath, but it does not add material parameter-level semantics beyond the schema. The added value is mostly about output fidelity, not parameter meaning.

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 names a specific verb and resource: Write ONE actor to a LOCAL file as a full-fidelity native Foundry JSON export. It also distinguishes itself from get-actor by calling that path a lossy summary view, so an agent can confidently tell this export tool apart from sibling read/update tools.

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 explicitly positions this tool as THE character backup/restore path and references get-actor as the lossy alternative, giving a clear when-to-use signal. It also documents the special placed-token-id case for capturing unlinked token instances. This is explicit routing guidance rather than an implied usage.

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