create_document_from_seed

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

With no annotations, the description carries the full transparency burden. It discloses key behaviors: preserving unknown XML, deriving validation from a verified provenance sidecar, falling back to 'synthetic_parser_only' without one, and requiring the target's current SHA to overwrite. This goes beyond the name and input schema, though it omits details about reversibility or permissions.

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 three sentences that front-load the purpose in the first sentence, then add essential caveats about validation, seed preference, and overwrite requirements. Every sentence earns its place, with no wasted words.

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 description covers the core purpose and important caveats (unknown XML preservation, validation dependency, overwrite SHA requirement), which is good for a tool with this complexity. However, it leaves the mapping of concepts like 'provenance sidecar' and 'current SHA' to specific parameters unclear, and the absence of explicit when-to-use guidance relative to sibling creation tools is a gap. The output schema presumably covers return values, so that is not a deficiency.

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 must compensate. It references a 'provenance sidecar' and 'current SHA' without mapping them to expected_seed_sha256 and expected_sha256. It also does not explicitly explain seed_path or target_path. The description's jargon adds ambiguity rather than clarifying the five parameters.

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 opens with a specific verb+resource: 'Copy a valid DipTrace-shaped XML seed while preserving unknown XML.' This clearly states the tool's function and distinguishes it from sibling creation tools like create_schematic_document or create_pcb_document, which likely create new documents rather than copy a seed.

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 a clear preference: 'Prefer a real export seed when DipTrace compatibility matters,' which guides when to use this tool vs synthetic alternatives. It also warns that replacing an existing target requires its current SHA, giving a precondition. It does not name specific sibling alternatives, but the context is clear enough.

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