Create Portal

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

Annotations declare readOnlyHint=false (mutation expected) and destructiveHint=false, which the description aligns with. The description adds valuable behavioral detail beyond annotations: seedHomePage behavior, the DRAFT status with preview token, and the non-editable slug constraint. It doesn't contradict 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 concise and front-loaded, with the core action stated first. The behavioral caveats (slug not editable, DRAFT status) are placed efficiently in the second part. No wasted words, though it could benefit from slightly more structure.

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 a 7-parameter mutation tool with no output schema and 14% schema coverage, the description is moderately helpful. It covers the key creation semantics (DRAFT, preview token, seedHomePage behavior, slug immutability) but omits details about return values, what happens on error, or whether dryRun impacts behavior meaningfully. It explains the most important parameters but leaves several undocumented.

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 very low at 14%, so the description should compensate. The description does explain what seedHomePage does (creates an 'overblik' page + navigation entry), which adds value. However, the description doesn't explain the kind parameter (references vocabulary tool which is reasonable), name, brandId, or defaultPersonaId, leaving the agent dependent on schema for these.

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 verb (create) and resource (portal in a brand), matching the tool name. It distinguishes from siblings by focusing on creation semantics. However, it doesn't explicitly contrast with update_portal or related tools, though the purpose is evident.

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 communicates key creation context: it starts as DRAFT with a preview token, and slug is not editable after creation. This provides practical guidance about the irreversible nature of slug, though it doesn't explicitly state when-not-to-use or name alternative tools.

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