alga_tickets_list

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact: results are paged ("one page at a time"). It does not disclose the default page size of 25, the 100-item cap, default sort order, or whether omitting all filters returns everything — details an agent needs to reason about result volume.

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 tight sentences with the core action and pagination constraint front-loaded and no filler. The filter list is dense but earns its place as the only parameter guidance available given the low schema coverage.

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 19-parameter, zero-required, no-output-schema list tool, the description covers the browsing/filtering intent and notes paging, which is the minimum an agent needs to call it safely. It leaves out default limits, sort behavior, the fields projection parameter, and any return-shape hint, which is a meaningful gap at this parameter count.

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 only 26% across 19 parameters, so the description must carry more weight than it does. It names several filter concepts (client, board, status, priority, assignee, open/closed, dates, external link) but never mentions the pagination, sorting, column-selection, or free-text search parameters, and its loose phrasing ("dates", "status") does not map cleanly onto entered_from/entered_to, closed_from/closed_to, status_id, or external_system.

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 gives a specific verb and resource ("List tickets") plus the pagination model ("one page at a time") and enumerates the filterable dimensions. It does not differentiate itself from the sibling alga_tickets_search or alga_tickets_get_by_external_link, so an agent must infer which ticket-read tool to pick.

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?

"Use to browse or filter by..." states the intended usage context, which is adequate for a list tool. However, no when-not conditions or alternatives are named, even though sibling tools like alga_tickets_search and alga_tickets_get exist and would be the natural competitors for a read-by-criteria task.

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