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

Annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) already tell the agent this is a non-destructive local write. The description adds two genuinely useful behavioral facts beyond that — no slot limit and the sourceAiSetupId fallback to the active setup — but says nothing about validation, the legacy content vs context precedence, or what the response contains.

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?

Three short sentences, zero padding, with the core purpose front-loaded before the two clarifying facts. Nothing here is wasted.

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?

For an 18-parameter, nested-object creation tool with no output schema, the description is thin: it never signals that only 'name' is required, never warns that the followUp/attachment sub-objects are where most of the configuration lives, and gives no hint about what a successful create returns. The rich schema covers much of the gap, but the description does not pull its weight for a tool of this complexity.

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 high (78%), so the schema already carries most parameter meaning, which sets the baseline at 3. The description's sourceAiSetupId note merely restates the schema's own 'Omit to use active setup' text and adds no new syntax or constraint detail, so it does not earn a bump.

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?

States a specific verb and resource ('Create a new LinkedNav prompt template'), so the agent immediately knows this is the creation counterpart to get_prompt/update_prompt/delete_prompt. It does not explicitly distinguish itself from the adjacent create_ai_setup sibling, which is the main remaining ambiguity.

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 sentence 'If sourceAiSetupId is omitted, the active setup is used' gives useful default-behavior context, and 'no prompt slot limit' removes a possible hesitation. However, there is no explicit when-to-use guidance, no statement of prerequisites, and no routing advice versus alternatives like create_ai_setup or generate_message_templates.

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