create_wiki_node

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

With no annotations, the description takes on the disclosure burden. It usefully reveals that UAT-first means the resource is owned by the user, but it does not mention that the operation also creates the underlying resource, nor any permissions or side effects beyond ownership.

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 compact and front-loaded with the core purpose, followed by a parameter note and ownership context. The phrase '[Official API]' is slightly redundant but does not waste much space.

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 essential purpose and ownership context, and the schema handles parameter details. But it gives no guidance on return values, shortcut behavior, or how this tool relates to alternative doc/sheet creation tools, leaving an agent to make some inferences.

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 covers 100% of parameters (all 6 with descriptions), so the baseline is 3. The description adds marginal value by restating obj_type's role, but does not provide additional detail on defaults or relationships beyond the schema.

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 clearly states the action ('Create a new Wiki node'), the target ('inside a space'), and adds the key parameter 'obj_type' that selects the underlying resource. This distinguishes it from sibling tools like update_wiki_node, delete_wiki_node, and list_wiki_nodes.

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 UAT-first note gives valuable context about ownership and when this tool is appropriate, and 'inside a space' narrows the context. However, it does not explicitly contrast with alternative creation tools like create_doc or explain when to use shortcut vs origin node types.

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