create_document

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

No annotations exist, so the description fully handles transparency. It reveals the fallback order for folder enumeration (API key first, then JWT, then manual input) and the effect of skip_folder_prompt. While it does not discuss permissions or side effects, the behavioral details about folder handling are thorough.

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 a single, front-loaded paragraph of four sentences with no redundancy. Every sentence serves a distinct purpose: defining the action, explaining folder options, detailing the prompt behavior, and stating the skip alternative.

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 has no output schema, so the description should at least hint at what happens on success (e.g., 'returns the created document'). Lacking that, the agent must infer from sibling tools. Also, no authentication or permission context is provided. The description covers creation well but omits return value and prerequisites.

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%, giving a baseline of 3. The description adds significant meaning beyond the schema by explaining the interactive prompt logic and when skip_folder_prompt applies, which helps the agent decide how to use each parameter correctly.

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 starts with 'Create a new document in IT Glue for an organization,' clearly stating the verb (Create) and resource (document). It distinguishes from sibling tools like archive_document or search_documents by specifying the exact action. The additional detail about folder prompts further clarifies the scope.

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 clear context on when to use the tool and how to control folder selection—either by supplying document_folder_id, setting skip_folder_prompt=true, or letting the system prompt. It does not explicitly exclude alternatives or mention when not to use, but the guidance is sufficient for typical use cases.

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