List tasks

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

No annotations are supplied, so the description carries the full burden and does substantial work: it discloses ACL-based result scoping, and it discloses ordering behavior ("With finishedSince the most recently finished come first, otherwise they come by name") that is nowhere else available. It leaves default/max result counts to the schema and does not describe the payload, which the output schema already covers.

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 core is front-loaded and efficient: what is listed, what scoping applies, what ordering applies, and where to go for details. However, the trailing sentence about naming people, roles and requests by display name when writing to a person has nothing to do with a read-only task listing and does not earn its place here.

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 zero-required-parameter list tool with a 100%-documented schema and an output schema, the description covers scope, ordering and the handoff to get_task, which is what an agent needs to call it correctly. Only the misplaced write-guidance sentence and the absence of any result-volume hint keep it from being 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 coverage is 100%, so the schema already documents all five filters including accepted status values and the RFC 3339 / duration forms of finishedSince. The description's added value is limited to the side effect that finishedSince changes sort order rather than merely filtering, which is genuine but small; the rest restates the schema's filter list.

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 and resource ("List the midPoint server tasks") and enumerates the task families returned (reconciliations, live syncs, recomputes, scanners). It also names the filter dimensions, so an agent can distinguish this list tool from sibling get_task and from generic search_objects without opening any schema.

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?

Explicitly routes the agent: "Use get_task for a task's result message and failed items," which defines the boundary with the main alternative. It also explains the visibility model (end users see only their own tasks), which is a usage precondition. It does not cover alternatives like list_recent_errors or search_objects, so it stops short of full when/when-not coverage.

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