create_article

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

Annotations already indicate this is a mutable, non-idempotent write operation that creates a new resource. The description adds minimal behavior context, such as the ability to nest via parent_article_id, but it does not disclose what happens after creation, whether a parent article must exist, or whether the instance parameter is required in multi-instance setups. It does not contradict the 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 reasonably concise and uses a clear Args list format that is easy to scan. The main purpose is stated up front, and each parameter gets a separate line. It could be slightly tighter by omitting obvious terms like 'Article title', but overall it is effective and readable.

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 there is an output schema and no nested objects, the agent can infer the return type. However, the description lacks important contextual details for a creation tool: it does not explain whether parent_article_id must reference an existing article, whether 'instance' is needed for multi-tenant setups, or how errors (e.g., duplicate summary, invalid project) manifest. It is adequate, but not comprehensive.

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 does explain the meaning of all five parameters: project, summary, content, parent_article_id, and instance. However, it adds little beyond the schema; no examples, formatting rules, or constraints are given for values like project short name or markdown content.

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, resource, and essential fields: 'Create a new Knowledge Base article' establishes what the tool does. It is distinguishable from siblings like create_issue and update_article because it explicitly targets Knowledge Base articles, but it does not explicitly contrast with update_article or search_articles, so it lacks strong sibling differentiation.

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 identifies the article context and lists required fields, implying creation of a Knowledge Base article. It does not explicitly state when to use this tool versus update_article or delete_article, nor does it mention prerequisites like needing an existing project or parent article, so usage guidance is only implicit.

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