frappe_create_document

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully reveals that credential/password fields are stripped automatically and that some fields are refused outright, which is valuable. However, it does not mention permissions, side effects, idempotency, or what constitutes a refusal, leaving several behavioral questions unanswered.

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 two sentences long, front-loaded with the core action, and every sentence earns its place. The credential-stripping caveat and the pointer to frappe_update_document add useful information without 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?

The tool is relatively simple with two parameters and no output schema, and the description covers the central create behavior plus an important data-handling caveat. Still, it does not describe the return value, error behavior, or prerequisites, and delegates some needed context to frappe_update_document without explaining what the agent should do with that information.

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 adds meaningful semantics around the values parameter by warning that credential/password fields are stripped and some fields are refused. However, it does not explain the structure of values or the meaning/format of doctype beyond what the name implies.

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 clear verb and resource: "Create a document." This distinguishes it from sibling operations like update, delete, or submit, but it does not explicitly clarify that it operates against a Frappe doctype using a values object, so it is slightly more generic than the strongest examples.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The pointer "see frappe_update_document" hints at related behavior around refused fields, but it does not explain when an agent should choose this tool over frappe_update_document, frappe_run_method, or other document-related siblings.

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