create_document

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 non-obvious interactive behavior (folder prompting), the API-key/JWT fallback order, and the accepted prompt inputs (URLs or numeric folder IDs). This is genuinely informative and goes far beyond a trivial 'create a document' statement.

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?

Although the description is longer than typical, every sentence earns its place by explaining a distinct behavioral aspect. The main purpose is front-loaded, and the remaining details are logically ordered from prompt behavior to enumeration fallback to the skip option.

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?

Given the tool's complexity and lack of output schema, the description thoroughly covers the most import invocation risks: folder selection, prompt fallback, and the skip flag. It doesn't explicitly state the return format or required auth scopes, but the API key/JWT fallback is already described, and these omissions don't significantly hinder correct use.

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?

The schema already documents all five parameters with 100% coverage, setting a baseline of 3. The description adds meaningful semantics for document_folder_id and skip_folder_prompt by explaining their interaction and the root-creation behavior, which exceeds the baseline.

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 uses a specific verb and resource: 'Create a new document in IT Glue for an organization.' This clearly distinguishes it from sibling tools like create_document_section or archive_document, and the organization scope is explicit.

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 gives clear contextual guidance on when the folder prompt appears and when to use skip_folder_prompt=true. It doesn't explicitly name alternative tools for when-not conditions, but the first sentence clearly establishes the create-document use case relative to siblings.

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