Create a document of any type

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

Annotations are all false, so the description must carry the behavioral burden. It adds valuable context: the created document is read back from Foundry, certain fields (ids, ownership, _stats, module flags) cannot be set, and permission behavior matches specialized tools. It does not explicitly state that it writes to the world, but that is implied. No contradiction with annotations.

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 dense but every sentence serves a purpose: purpose, data shape, permission/constraints, dryRun advice, tool routing, and exclusions. It is front-loaded with the 'Generic fallback' label and proceeds logically. No wasted words for the amount of information conveyed.

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 generic creation tool with no output schema, this description is fairly complete: it covers what it does, how to use it, constraints, and what it returns (read back from Foundry). It could add a note on error handling or how to discover valid document types, but the pointer to describe-document-type mitigates that. Overall, an agent can confidently invoke it.

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 100%, so parameters are documented, but the description adds important semantics: how data should be structured (nested objects, 'as describe-document-type shows'), what parentUuid is for (with examples), and the restriction on fields like ids and _stats. This goes beyond the schema's bare descriptions, making it more actionable.

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 states a specific action ('create one document') on a broad but well-defined resource ('any type in the world, or inside another document with parentUuid'). It clearly positions itself as a generic fallback, explicitly naming specialized siblings it should not replace. This distinguishes it from the many other creation tools like journal-create or create-scene.

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 explicit usage guidance: it says to prefer a list of specialized tools 'where they fit', and clarifies what is not handled here ('Chat messages are sent only with send-chat-message; settings, users and compendiums are not written here'). It also recommends using dryRun first, which is a specific precondition. This gives an agent clear decision criteria.

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