create-contact-child-folder

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

The description discloses that the tool creates a subfolder (consistent with destructiveHint=true), provides the body structure, and explains how the returned id can be reused. It doesn't contradict annotations. It adds context beyond annotations, though it doesn't detail error scenarios. The tip is helpful for understanding the tool's effect.

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 plus a tip, all front-loaded with the core purpose. Every sentence adds value: the first states the action, the second clarifies flexibility, the tip provides actionable guidance. There is no redundancy or fluff.

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 complexity (4 parameters, nested body object, no output schema), the description covers the essential points: what it does, required inputs, how to get the parent id, and what to do with the result. It doesn't explain the full response structure, but the tip about the returned id is sufficient for most use cases. It misses mentioning error handling or validation, but overall it's complete enough.

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 description adds meaning beyond the input schema by specifying that the 'body' should contain 'displayName' and that 'contactFolderId' comes from a list operation. The schema itself has many fields, but the description focuses on the essential one. With 75% schema coverage, the description compensates well by clarifying required inputs.

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 a clear statement: 'Create a new contactFolder as a child of a specified folder.' It specifies the action (create), the resource (contactFolder), and the relationship (child of). It distinguishes from sibling tools like 'create-contact-folder' (which likely creates a root folder) and 'create-contact-in-folder' (which creates a contact).

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 a tip advising to use 'list-contact-folders to discover the parent id' and specifies the minimal body shape. It implies when to use: when you need a subfolder. It does not explicitly name alternatives or give a when-not-to-use, but the context of sibling tools like 'create-contact-folder' provides contrast.

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