List roles

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

With no annotations, the description must carry the behavioral burden; "List" implies a read-only, non-destructive call, but nothing states that explicitly. It does not mention the pagination/limit behavior or the default 20 / max 100 ceiling, which matters for a listing tool. The existence of an output schema relieves it of describing the return shape.

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 short sentences, both load-bearing: the first states the operation and returned fields, the second carries a non-obvious usage convention. No filler or restatement of the title.

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 simple one-parameter list tool with a full schema and an output schema, this is close to adequate. The gaps are the lack of sibling disambiguation (get_role vs list_requestable_roles) and no note on whether results are paged or complete.

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 100% and the single limit parameter is fully documented in the schema with its default and maximum. The description adds nothing about ordering, filtering, or how limit interacts with a large role population, so baseline 3 applies.

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?

"List midPoint roles" gives a specific verb and resource and previews the returned fields (name, display name, description). It does not, however, distinguish itself from siblings like get_role, list_requestable_roles, or search_objects, which overlap in subject matter.

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?

There is no explicit statement of when to call this rather than get_role (single role) or list_requestable_roles (only what is requestable). The second sentence is guidance about how to use the results when writing to a person, which is useful context but not a usage-routing rule for this tool itself.

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