List decisions

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

With no annotations, the description carries the full burden and does so: it discloses pagination defaults (25, capped at 100), that out-of-range values are clamped rather than errored, that glob=None lists everything while an empty string matches nothing, and that matching is case-insensitive. It also warns that 'ref' is an opaque identifier and not a disk filename, preventing a likely misuse.

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?

Front-loaded with the resource and returned fields, then the ref caveat, then filtering, then paging. Every clause earns its place, though the single dense paragraph packs several distinct ideas (return shape, ref semantics, glob rules, paging) that could be marginally easier to scan as separate sentences.

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?

An output schema exists, so return values need not be enumerated, yet the description still names the key fields. Combined with complete filtering and paging semantics, nothing an agent needs to call this correctly is missing.

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 0%, so the description must define all three parameters, and it does: glob semantics (case-insensitive id match, default None vs empty string), and offset/max_results as paging controls with documented defaults and caps. This adds substantial meaning beyond the bare anyOf integer/string schema.

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 ('List') and resource ('decisions') plus the exact fields returned (ids, titles, statuses, refs) and the scoping ('in the configured decision base directory'). It also distinguishes itself from the by-id sibling ('for context before addressing one by id') and from get_dec for ref-based lookups, so an agent can separate it from the many list_*/get_* 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?

Gives a clear use context (get an overview before addressing a decision by id) and names the alternative for a specific case ('use it with the get_dec tool instead' for refs). It stops short of stating when NOT to use this tool or why to prefer it over other list_* siblings, but the primary routing decision is covered.

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