Get Portal Preview

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

The annotations comprehensively cover the behavioral profile: readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true. The description adds the return payload contract ({ previewUrl, token }) and the DRAFT constraint. However, it doesn't explain what previewUrl or token are used for, token lifespan, or any prerequisites (e.g., must portal be in draft state, what happens if published). Annotations do the heavy lifting here, so the description adds modest value beyond them.

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 a single, compact sentence that front-loads the return type and scoping constraint. Every element earns its place, and there's no filler or redundancy. Very concise and clean.

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 single-parameter read-only tool with comprehensive annotations, the description is adequate but minimal. It lacks context about what the preview actually provides (a rendered view? a link? what does token grant?), token expiration semantics, or behavior when the portal isn't in draft state. Given the draft-scoped purpose and one parameter, more context could help agents decide when previewing is appropriate versus listing or fetching a portal.

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% and there's only one parameter, portalRef. The description does not elaborate on what portalRef should be (ID format, how to obtain it). With zero schema coverage, the description carries the burden but says nothing about this sole parameter beyond its existence in the input schema. The description does not compensate for the coverage gap.

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 'Return { previewUrl, token } for previewing a DRAFT portal' uses a specific verb (return/preview) and a clear resource (portal), and crucially disambiguates from sibling tools like kilango_get_portal (which fetches portal data) and kilango_list_portals (which lists portals). The DRAFT scoping is a meaningful differentiator against get_portal. This clearly distinguishes it from its siblings.

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 implies this is for previewing draft portals, which establishes a general usage context but doesn't explicitly state when to choose this over alternatives. It doesn't name alternative tools (though the DRAFT constraint hints against using get_portal for preview purposes) or describe exclusions like 'does not preview published portals.' The guidance is implied rather than explicit.

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