List Portals

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it's 'Paged with cursor,' which is useful behavioral context not in annotations. However, it doesn't mention pagination limits, default page size, or ordering/return format — with readOnly already covered, a 3 is appropriate.

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?

Two sentences, zero wasted words. Every element earns its place: scope ('workspace'), filter list, pagination mention. Front-loaded with the primary purpose first.

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?

With readOnly/idempotent annotations covering safety and cursor pagination mentioned, the description is reasonably complete for a filtered-list tool with 5 optional params. The parameter semantics are thin but the schema (with status enum) provides some grounding. No output schema exists, so return format isn't required, though a brief note on what fields are returned would improve completeness.

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 names all 5 parameters (kind, status, brandId, q, and cursor implied by 'Paged with cursor'), but only by listing them without meaning. The status enum in the schema covers that parameter's values, but kind/brandId/q values are not explained. The description adds nominal value by enumerating filter names but doesn't explain semantics.

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 'List portals in the workspace' — a specific verb+resource. The optional filters (kind, status, brandId, q) help distinguish this from sibling tools like kilango_get_portal (single retrieval) and kilango_list_pages (different resource). It doesn't explicitly differentiate from siblings, but the resource scope and filter list are clear.

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 when to use it — listing portals with filters vs retrieving a single portal. However, it doesn't explicitly state when NOT to use this in favor of, say, kilango_search_operations or kilango_list_portal_apps. The context of listing vs single-get is implied through the sibling names rather than stated explicitly.

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