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

With no annotations supplied, the description carries the full burden and does disclose real behavior: the call is refused when userName/roleName don't match the OIDs, and it degrades to a dry-run preview without the write gate. It stops short of describing idempotency (what happens if the user already holds the role) or any permission/rate constraints beyond the gate.

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 action is front-loaded, but the middle sentence is a dense run-on ('as list and get results give them') and the closing sentence about naming people, roles and requests by display names is confusing here, since every parameter in this tool requires OIDs — it reads like guidance for a different call.

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?

All four parameters are documented in the schema and an output schema exists, so the description need not explain return values. Gating, validation and naming semantics are covered; the main gap is what a successful assignment implies (idempotency, effect on existing assignments).

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 baseline is 3; the description earns above that by explaining that userName/roleName are midPoint unique-name attributes (a login, not a display name) and why the match check exists — it reads the right names back to the confirming operator. That rationale is not present in the 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?

The first sentence is a precise verb+resource statement ('Assign a role to a user'), which distinguishes it from get_role, list_roles and the mutating siblings. It never explicitly contrasts with unassign_role or request_role, but the verb itself carries that distinction.

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 gives preconditions (write gate required, otherwise dry-run preview) and a naming convention for the confirmation prompt, which implies when the tool is usable. It does not state when to prefer this over request_role (requesting a role for oneself) or unassign_role, so routing between the three role-mutating siblings is left to inference.

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

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

With no annotations supplied, the description carries the full load and does so well: it discloses the pre-write read and state/requester check, that midPoint enforces cancel authorization, the write-gate respect, the absence of a comment, and a post-write read-back to confirm closure. The name-mismatch refusal is a concrete failure mode an agent can plan around.

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 action and scope are front-loaded, but the prose is dense and several clauses are only tangentially useful to invocation, such as "Uses plain REST with no comment" and the closing general instruction about display names. The long OID/name-matching sentence is hard to parse in one pass.

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 three-parameter mutation with an output schema present, the description covers authorization, precondition checks, refusal conditions, write-gate behavior, and post-write verification. Nothing an agent needs in order to call this safely 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 100%, so the baseline is 3, but the description adds real meaning the schema lacks: userName and roleName are midPoint unique-name attributes (logins) rather than display names, they must correspond to the objects the OIDs point to, and a mismatch aborts the call. That explains why the confirmation parameters exist at all, though it does not clarify the empty-string case the schema mentions.

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 first sentence gives a specific verb and resource with scope: "Withdraw your own open approval request." That cleanly separates it from sibling mutators like decide_work_item, claim_work_item, and request_role. It never names an explicit alternative, so it stops short of a 5.

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?

Usage context is clear: it applies only to the caller's own open request, requires name/OID agreement, and is refused otherwise. There is no explicit when-not guidance or reference to a sibling tool for the case where the request is not yours, which keeps it below 5.

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

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

With no annotations, the description carries the full burden and delivers: it discloses a pre-write read of the case, the exclusivity semantics (the rest of the group can no longer claim it), the refusal conditions, that the claim executes under the caller's identity, and that the result reports whether midPoint now shows the item as yours. It also mentions the write gate, which is the permission model an agent needs to anticipate failures.

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 purpose and precondition are front-loaded, but the body is one dense run-on paragraph mixing claim semantics, refusal rules, identity, return behavior, and a global style rule. The trailing display-name instruction is both stylistically out of place and semantically conflicting, so it does not earn its place in this tool's definition.

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 4-required-parameter mutation with an output schema, the description covers preconditions, exclusivity, failure modes, and the fact that the response confirms ownership, which is enough for correct invocation. The only real defect is the contradictory name-format guidance, which could cause an agent to pass a display name and get refused.

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%, but the description still adds meaning: userName/roleName must be midPoint unique names (logins) of the objects the OIDs point to, and the call is refused on mismatch, which explains why they are required for a claim keyed by OIDs. The final sentence, however, tells the agent to use display names 'rather than OIDs', which sits in tension with the login-not-display-name rule stated two sentences earlier and muddies an otherwise clear confirmation-safety contract.

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 states a specific verb and resource ('Claim an open approval work item offered to a group you belong to') and immediately names the downstream sibling ('decide_work_item') and the undo path ('release_work_item'). An agent can distinguish this from list_work_items and decide_work_item 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?

It gives an explicit precondition ('offered: true in list_work_items'), names the alternatives for the next and reverse steps, and enumerates exactly when the call will be refused (closed, already held by someone including you, or not offered to you). This is when/when-not guidance with routing, not inference.

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

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

With no annotations, the description carries the full burden and does disclose the important behavioral trait: without the write gate the call degrades to a dry-run preview rather than failing. It does not cover duplicate-name handling, validation failures, or whether the write is reversible, so it stops short of a 5.

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?

Three short sentences with no filler, and the core action is front-loaded ahead of the gating caveat. The final sentence is only loosely relevant to this tool's schema, which costs it a perfect score.

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 explained, and all five inputs are schema-documented; the write-gate behavior is the one piece of non-schema context an agent needs and it is present. What is missing is failure-mode context such as duplicate login names, which matters for a create operation.

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%, so every one of the five parameters is already documented and the baseline is 3. The extra sentence about naming people, roles and requests by display name is generic write guidance and does not actually map onto this tool's parameters (name, fullName, givenName, familyName, emailAddress), so it adds little parameter-level meaning here.

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?

"Create a new midPoint user" gives a specific verb and resource, and creation is clearly distinct from the sibling read (get_user) and lifecycle tools (disable_user, enable_user, recompute_user). It does not explicitly name a sibling to route away from, which keeps it short of a 5.

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 supplies a key prerequisite (the write gate) and states the fallback behavior when the gate is closed (dry-run preview), which effectively tells the agent when the call will actually mutate state. It gives no explicit when-to-use-vs-alternative guidance, e.g. how this relates to request_role or assign_role when a user also needs roles.

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

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

With no annotations, the description carries the full burden and does well: it discloses the pre-write validation read, the refusal conditions, that the decision executes as the authenticated user, that the result reports case, recorded outcome and acting identity, and that mismatched userName/roleName aborts the call. Gaps remain — the "write gate" is named but never explained, and it does not say whether an already-recorded decision can be reversed or re-submitted.

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 purpose before behavior, and nearly every sentence carries operational content. The trailing sentence about naming people, roles and requests by display names rather than OIDs sits awkwardly against the earlier instruction that userName/roleName must be midPoint names, which reads as mildly inconsistent and costs a point.

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 six-parameter mutation tool with an output schema, the definition covers preconditions, refusal behavior, execution identity, and return contents. An agent has everything needed to decide whether to call it and what arguments to supply, with the display-name/OID tension being the only minor ambiguity.

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 baseline is 3; the description earns above that by specifying that userName and roleName are the midPoint unique-name attribute (a login, not a display name) of the objects the OIDs reference, and that a mismatch causes refusal. That adds cross-parameter semantics the schema alone does not convey, though it does not clarify the accepted values of decision or comment conventions.

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 pair and resource: "Approve or reject an open approval work item assigned to the authenticated user, with an optional comment." The scope qualifiers (open, assigned to the authenticated user) plus the pointer to list_work_items and claim_work_item let an agent separate this from the sibling read and claim tools immediately.

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 an explicit precondition sequence: the tool reads the case as the user before writing, and it refuses work items that are not open or not in the approval inbox (routing to list_work_items). It also names a concrete exclusion case with its alternative — a group-offered item nobody has claimed must be claimed first via claim_work_item.

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

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

With no annotations at all, the description carries the full burden and does disclose non-obvious behavior: the call is refused if userName does not match the OID, and without the write gate it produces a dry-run preview instead of mutating. It does not describe side effects of disabling (e.g. loss of assignments or active sessions) or whether the change is reversible via enable_user.

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 action and its state transition are front-loaded in the first clause, followed by the confirmation-safety rationale. The closing sentence about naming people, roles and requests by display names is generic cross-tool boilerplate that is only loosely tied to this operation, mildly diluting focus.

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 two-parameter destructive tool with a 100%-covered schema and an output schema, the description covers the essentials an agent needs: what it does, the confirmation guard, and the gate/dry-run fallback. Only the post-disable effects and reversibility are left implicit.

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% and the schema already states that userName is the midPoint name and must match oid, so the description largely restates structured data. The 'their login, not the full name' clarification reinforces the schema but adds no new semantics beyond it, making baseline 3 appropriate.

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 plus the resulting state change ('Disable a midPoint user (activation → disabled)'), which cleanly separates it from get_user, create_user and enable_user in the sibling list.

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?

Explains the operational context well: the call requires the write gate and otherwise degrades to a dry-run preview, which tells the agent what to expect before invoking. It does not explicitly name alternatives (e.g. enable_user to reverse, get_user to look up the OID), so it stops short of full when/when-not routing.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses the write gate requirement, the dry-run fallback when the gate is absent, and the OID/userName mismatch refusal — all non-obvious traits. It omits whether the change is reversible or logged, and there is no note on return shape, though an output schema exists.

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 state transition, then the identity constraint, then the gate behavior — a sensible order. The clause 'so the person confirming it reads the right name' is a slightly indirect justification for the mismatch check and could be tightened.

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 two-parameter state-toggle tool with a full output schema, the description covers everything an agent needs: what changes, identity validation, authorization gate, and the dry-run fallback. Nothing essential is missing given the schema handles parameters and returns.

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 both parameters are already documented there, so the baseline is 3. The description largely restates the schema's userName definition (login, not full name; must match oid), adding only the consequence — that a mismatch refuses the call — rather than new per-parameter meaning.

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 plus the exact state transition: 'Enable a midPoint user (activation → enabled)'. That wording distinguishes it clearly from disable_user and from read siblings like get_user, without needing the 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?

Explains the operating conditions: the call is refused when userName does not match the OID, requires the write gate, and falls back to a dry-run preview otherwise. It never explicitly names disable_user as the inverse operation, but the enable/disable pairing is unambiguous from the verb.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It does disclose two non-obvious traits: the response embeds work items, and quoted text in the payload is authored by third parties and must be treated as data, never instructions. What it omits is the operation's mutability/permission profile ("Fetch" implies read-only but this is never stated) and any note on error behavior for invalid OIDs or missing cases.

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 purpose statement is front-loaded in one clean sentence with no waste. The safety and naming guidance is dense but earns its place as non-obvious behavioral instruction, though it reads as a boilerplate insertion and slightly buries the naming rule mid-paragraph.

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 explained, and the untrusted-text warning covers the main safety hazard of this payload. However, for a read tool with no annotations the description should state that the call is non-mutating and clarify its relationship to get_task, list_work_items, and decide_work_item, which are natural follow-ups an agent will need.

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?

There is a single parameter and schema description coverage is 100%, with the schema already documenting oid as "the midPoint object OID". The description reinforces that the OID identifies an approval case rather than an arbitrary object, which is a small but real clarification beyond the schema. Baseline 3 applies since the schema does the heavy lifting.

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?

"Fetch an approval case by OID, including its work items" gives a specific verb, resource, and lookup key, plus the notable scope detail that work items are bundled in. It stops short of differentiating from siblings such as get_task or list_work_items, which also surface work-item data, so an agent cannot fully rule those out from the description alone.

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?

Usage is implied rather than stated: the agent can infer this is the single-case lookup keyed by OID, contrasted implicitly with the list_* siblings. There is no explicit when-to-use/when-not guidance, no mention of what to do when the OID is unknown, and no routing to get_task or list_work_items for related needs. The only explicit directive concerns output formatting (use display names), not tool selection.

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

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

With no annotations, the description carries the full burden and does well: it establishes the operation is a read of the caller's own record, discloses that no elevated permissions are required, and warns that output contains untrusted text authored by others that must not be followed as instructions. It stops short of pagination, ordering, or size expectations, which is the main remaining gap.

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 purpose and returned fields are front-loaded in the first sentence, which is the right structure. The prompt-injection warning is long and reads as shared boilerplate, and the final sentence about display names is tangential to a read-only tool, so a small amount of text does not earn a 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-parameter read tool with a full output schema, everything an agent needs is present: what is returned, that the scope is the caller's own user, that no extra permission context is required, and how to safely interpret untrusted strings in the results. Return-format detail is legitimately delegated to the output schema.

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?

The tool takes zero parameters, so there is no parameter meaning to add and baseline 4 applies. The description correctly implies there is nothing to supply, since it scopes everything to the authenticated caller.

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 the authenticated user's own access') and then enumerates the two things returned: direct assignments with dates and provenance, and effective role membership flagged direct or inherited. The self-scoping ('reads the caller's own user') implicitly separates it from get_user_assignments/get_user, but it never names those siblings, so an agent must infer the boundary.

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?

It conveys the operating context ('needs nothing beyond what midPoint's self-service pages need') and offers handling guidance for the output (treat quoted text as data; refer to people/roles/requests by display names when writing). It never states when to pick this over get_user_assignments, get_user, or list_expiring_access, so tool selection remains implied rather than directed.

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

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

With no annotations, the description carries the full behavioral burden. "Fetch" implies a read, but nothing confirms read-only semantics, says what happens when the OID does not exist, or notes permission requirements; "including connection status where reported" hints at return content but is hedged and largely redundant with the output schema.

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 first sentence is tight and front-loaded. The second sentence is unrelated to fetching a resource and reads as a stray cross-cutting convention, consuming space without serving this tool's definition.

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 explained, and the tool is a simple single-parameter lookup. Still missing is any note on failure behavior for an unknown OID and confirmation of read-only semantics, while the display-name sentence adds noise rather than 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 coverage is 100% for the single required parameter, and the schema already documents oid as "the midPoint object OID". The description adds no format, validation, or lookup-example detail beyond that, so the 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?

"Fetch a single midPoint resource by OID" states a specific verb, resource and cardinality, which cleanly separates it from list_resources and the generic search_objects. It stops short of naming those siblings explicitly, but the singular-by-OID framing makes the distinction inferable.

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 guidance on when to call this instead of list_resources, search_objects, or test_resource. The only usage advice present ("When you write to a person, name people, roles and requests by their display names rather than OIDs") concerns a different operation entirely and does not help select this tool.

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

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

No annotations are provided, so the description carries the full burden, and it does signal a read-only single-object fetch. It says nothing about behavior on a missing/invalid OID, permission requirements, or whether the returned role includes assignments/entitlements, leaving real gaps for an unannotated tool.

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 with the core action front-loaded and no padding. The second sentence is compact but only loosely related to this tool, so it slightly dilutes focus rather than earning its place fully.

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 a single required parameter and an output schema present, the description needn't explain return values, and the shape is adequately conveyed. However, for an unannotated tool it omits not-found/error behavior and the scope of the fetched role, leaving it only minimally viable.

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% (the oid parameter is documented as "the midPoint object OID"), so the baseline is 3. The description repeats "by OID" without adding format details or where OIDs are obtained; the display-name remark hints at an OID-vs-name distinction but does not clarify the parameter itself.

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 first sentence gives a specific verb and resource ("Fetch a single midPoint role by OID"), which implicitly separates it from list-oriented siblings such as list_roles and list_requestable_roles. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated.

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?

Usage is only implied: the agent must infer it should call this when it already holds a role OID and wants one record rather than a list. The second sentence talks about how to refer to people/roles/requests when writing to a person, which is tangential to selecting get_role and offers no explicit when-not or alternative.

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

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

With no annotations, the description carries the full load and mostly succeeds: it discloses the exact result payload (last-run operation status and message, per-outcome item counts, last failure) and adds a prompt-injection warning about untrusted quote text, which is real behavioral context an agent cannot infer from the schema. It never states read-only-ness explicitly, leaving that to inference from "fetch".

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 sentence is dense and front-loaded with the useful payload. However, the closing instruction about naming people, roles and requests by display name "when you write to a person" is irrelevant to a read-only fetch tool and reads as boilerplate bleed that dilutes the description.

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 one-parameter read tool with an output schema, the description is nearly complete: it explains what facets of the task come back and warns about untrusted content. The only gap is that read-only behavior is never stated outright, and the trailing display-name advice adds no value here.

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% and the single parameter is fully documented as "the midPoint object OID". The description's "by OID" adds no format, syntax, or constraint detail beyond the schema, 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?

"Fetch one midPoint server task by OID" gives a specific verb, resource and cardinality, which cleanly separates it from the sibling list_tasks. It then enumerates exactly what the agent gets back (state, owner, kind, last run result, processed items by outcome, last failed item).

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 single-vs-list distinction against list_tasks is implied by "one ... task by OID", and the sibling names make the alternative guessable. But there is no explicit statement of when to prefer this over list_tasks, or of how to obtain a task OID in the first place.

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

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

No annotations are supplied, so the description carries the full disclosure burden; 'Fetch' implies a read with no side effects, but permissions, behavior on missing/invalid OID, and error responses are unstated. Because an output schema exists, return-structure details needn't be in the description, which keeps this at an adequate rather than deficient level.

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, with the core purpose front-loaded and the caveat second. The trailing sentence is somewhat tangential to this tool's invocation but is short and adds identifier convention context rather than padding.

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 one-parameter lookup with an output schema and no annotations, the description covers purpose and roughly what is returned. It omits how an agent obtains a valid OID in the first place (e.g., via search_users) and any behavior on not-found OIDs, which are the main remaining gaps.

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?

There is a single required parameter with 100% schema description coverage ('the midPoint object OID'), so the schema already does the work and baseline 3 applies. The description adds only that lookup is by OID and that OIDs are not the preferred identifier when writing elsewhere, which is marginal added meaning.

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 ('Fetch a single midPoint user by OID') plus the scope of returned data (identity attributes and status), which separates it from list-oriented siblings like list_my_teammates. It does not explicitly name search_users as the alternative, so the differentiation from sibling retrieval tools is only implied.

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 second sentence gives a convention about naming people by display names when writing, but that is guidance about other tools rather than about when to call this one. There is no statement of prerequisites, no 'use search_users if you only have a name', and no exclusions, leaving the agent to infer usage from the name.

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

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

With no annotations at all, the description carries the full behavioral burden. It does disclose useful result semantics (each entry flagged direct or inherited, with requester/approver provenance) and two operational conventions: untrusted quoted text must be treated as data, and people/roles/requests should be referenced by display name rather than OID. It does not cover error behavior for an unknown or unauthorized OID, nor result size or cost.

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 purpose is correctly front-loaded in the first clause, but the remainder is two long generic paragraphs (injection handling and display-name style) that are largely tool-agnostic boilerplate and are buried inside the opening sentence's parentheticals. The structure is awkward: safety guidance trails off mid-sentence after an em dash rather than being separated or shortened.

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 single-parameter read tool with an output schema, the description need not explain return shape, and it still adds the direct/inherited flag and provenance semantics an agent would otherwise have to infer from the payload. What is missing is minor: behavior on invalid OIDs and whether results are bounded or paginated.

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?

Only one parameter exists and schema description coverage is 100%, so the baseline is 3. The description adds no meaning to 'oid' itself; the display-name-versus-OID sentence concerns how to present output when writing to a person, not how to supply the parameter, so it does not compensate further.

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?

Uses a specific verb ('List') with a precisely scoped resource: a user's direct assignments plus effective role membership, annotated as direct vs inherited, together with provenance (who requested and approved). That is well beyond restating the name. It does not explicitly distinguish itself from near-siblings such as get_my_access or list_expiring_access, so it stops short of a 5.

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 statement of when to use this tool versus alternatives — notably get_my_access (own access) or list_expiring_access — and no mention of prerequisites such as needing permission to inspect another user's assignments. Usage is only implied by the phrase 'a user's ... assignments'.

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

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

With no annotations, the description carries the full burden and does well: it discloses the authorization model (each person is read as the caller, so midPoint's visibility rules decide what is returned) and the fallback behavior for hidden people (listed by OID). Ordering is also stated. Pagination, limits, and error behavior are not covered, keeping it below a 5.

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 sentence is front-loaded and information-dense, but the closing sentence about naming people, roles, and requests by display name is guidance for write tools, not for this read-only listing, so it does not earn its place here. The single run-on sentence with embedded clauses also makes the key facts harder to scan.

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 re-explained, and the description covers scope, ordering, and visibility semantics well. What remains unaddressed is result volume behavior — pagination or truncation — which matters for a listing that spans the caller plus every report they manage.

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%, including the days default/max and includeSelf's meaning, so the schema does the heavy lifting. The description adds only indirect context — that the listing is for the caller and their reports — without clarifying units, boundaries, or how includeSelf interacts with the visibility model. Baseline 3 is appropriate.

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 — assignments ending within N days — plus the exact scope (caller plus direct reports, defined as the org members returned by list_my_team) and sort order (soonest first). The result shape it promises (whose access, which role, when it ends) makes it immediately distinguishable from siblings like get_my_access or get_user_assignments, which cover different scopes.

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 expiring-access framing implies when to reach for it, and the parenthetical ties the team scope back to list_my_team, which is useful routing. But there is no explicit when-not guidance and no statement of which sibling to prefer for non-expiring or all-time assignment listings (get_user_assignments, get_my_access). Usage is inferred rather than stated.

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

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

With no annotations, the description carries the safety burden, and it does disclose a meaningful constraint: results are scoped to orgs the authenticated user belongs to, so it cannot be used to look up arbitrary reporting lines. It says nothing about permissions needed, ordering, or what happens with zero managers, and the limit/pagination behavior is left entirely to the schema.

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 purpose is front-loaded in a single tight clause with the key scoping detail immediately after. The trailing display-name convention sentence is relevant to consuming the output but reads as global style advice rather than tool-specific information, so it is slightly off-purpose.

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 read-only listing tool with one optional parameter and an output schema, the description covers what it returns, whose perspective it uses, and how to reference the resulting people. Nothing essential is missing, though a note on ordering or empty results would round it out.

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?

There is a single optional parameter and schema description coverage is 100% ('maximum results, default 20, max 100'), so the schema already fully documents it. The description adds no extra meaning about the limit, which is acceptable given the baseline for fully covered schemas.

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 plus resource ('List who the authenticated user reports to') and further narrows the semantics to 'the managers of the orgs they are a member of', which separates it in spirit from list_my_team/list_my_teammates. It stops short of naming those siblings explicitly, so the differentiation is inferable rather than stated.

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?

Usage is implied by the scope statement (the authenticated user's own reporting line), but there is no explicit when-to-use/when-not guidance and no mention of the obvious alternatives like list_my_team or get_user. The second sentence is guidance, but about naming conventions when writing rather than about selecting this tool.

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

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

With no annotations at all, the description carries the full burden and does add real behavioral context: it warns that the result names the identity the request answered for and that in personal mode this may be the server's configured account rather than the caller. That is a genuinely useful, non-obvious disclosure for a read tool; it stops short of describing pagination or ordering behavior, but limit is covered by the schema.

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 purpose is front-loaded in the first sentence, and the identity caveat follows logically. The closing sentence about display names versus OIDs is a formatting directive rather than a property of this tool, so it is slightly off-target, but it is short and does not obscure the main point.

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 no explanation, and the description covers the main semantic trap: whose requests are actually being returned. What is missing is positional guidance relative to sibling list and case tools, which leaves a gap for an agent choosing between them.

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%, and the single limit parameter is fully documented in the schema with default and maximum. The description adds nothing about what limit counts or how results are ordered, so the schema does the work and the baseline of 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?

The description gives a specific verb and resource scoped to the caller ("approval cases the authenticated user initiated"), which distinguishes it from generic case or work-item tools. It does not explicitly name the nearest sibling (list_request_targets) or state how the two differ, so the differentiation is left implicit.

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 when-to-use or when-not-to-use guidance and no mention of alternatives such as list_request_targets, get_case, or list_work_items. The agent must infer from the name alone when this list is the right entry point versus those siblings.

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

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

With no annotations, the description must carry the behavioral load. It does disclose two useful traits: the result is empty if the user manages no orgs, and the response names the identity it answered for; 'List' also implies a read-only operation. It omits permission/precondition behavior and pagination semantics beyond the limit parameter.

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 scope statement is front-loaded in the first sentence and the follow-on tool routing is compact. The final sentence about naming people, roles and requests by display names is cross-cutting write-side advice that sits awkwardly on a read tool and slightly dilutes focus.

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 structure need not be explained, and the description still flags the key semantic (which identity the answer is for) plus the empty case. For a single-parameter list tool this is nearly sufficient; only the relationship to the similarly named teammates/managers tools is left unclear.

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?

Only one parameter exists and the schema documents it fully (default 20, max 100), so the baseline of 3 applies. The description adds no meaning about the limit, such as behavior when more reports exist than the limit allows.

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 plus a precise scope definition: direct reports as the members of orgs the authenticated user manages, with the empty-result edge case spelled out. What keeps it from a 5 is that the near-identical sibling list_my_teammates (and list_my_managers) is never mentioned, so an agent must still infer how 'my team' differs from 'my teammates'.

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 concrete downstream routing: use the returned OIDs with get_user_assignments to review access, or request_role to request access for a report. That is clear when-to-use guidance tied to named tools, but there is no when-not guidance or prerequisite (e.g., what the caller must be to have reports).

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

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

With no annotations, the description carries the full burden and delivers non-obvious behavior: the caller is excluded from results, and 'my team' is resolved from a deployment setting (team.orgOids / team.orgNames) rather than all orgs. It stops short of describing pagination or ordering, and the closing sentence about OIDs vs display names is guidance aimed at write tools rather than disclosure about this one.

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 scoping statement is correctly front-loaded, but the middle clause about users in several orgs is a convoluted parenthetical, and the final sentence about naming people/roles by display name is off-topic for a read-only list tool and cannot be acted on 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?

An output schema exists, so return values need not be explained, and the single parameter is fully documented in the schema. The genuine gap is sibling disambiguation against `list_my_team`, which shares almost the same name and is not mentioned anywhere in the description.

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?

Only one optional parameter (`limit`) exists and schema coverage is 100%, with default and maximum already documented in the schema. The description adds no further meaning about the limit or result ordering, so the baseline of 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?

The first clause gives a specific verb and resource and defines scope precisely: peers, i.e. other members of the caller's orgs, with the caller excluded. What's missing is any differentiation from the sibling tool `list_my_team`, whose name is nearly identical — an agent cannot tell the two apart from this text alone.

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?

Usage is implied rather than stated: the description explains the deployment-level org scoping caveat but never says when to prefer this over `list_my_team` or `search_users`. The config-file reference is a caveat about result scope, not a when-to-use rule.

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

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

With no annotations supplied, the description carries the full behavioral burden and does so thoroughly: per-source independence, a refused source degrading to a 'refused' section rather than failing the call, caller-scoped permissions, a hard cap of 20 systems searched, truncation of per-object operation history, and the script-access prerequisite for the audit source. It also flags that quoted text from other people is untrusted data, which is important injection-defense context for an agent that will summarize the output.

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 purpose is correctly front-loaded and nearly every clause carries real information, but the body is a single dense run-on of semicolon-separated clauses mixing source enumeration, permission semantics, and prompt-injection policy. Splitting the source list from the operational caveats would make it far more scannable without losing content.

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 no explanation, and the description still covers everything an agent needs to call this correctly and interpret a partial or refused result. Permissions, caps, degradation behavior, and the untrusted-output caveat are all present, leaving no material gap for a multi-source diagnostic tool.

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%, so hours and limit are already fully documented in the schema including defaults and maxima. The description only echoes the window concept ("last hours") and never explains how limit maps across the five sections, so it adds little beyond structured fields — the baseline of 3 is appropriate.

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 opens with a concrete question it answers and then enumerates the five distinct sources it aggregates (failed tasks, failed account/entitlement operations, dead/pending accounts, down systems, failed audit records). That level of specificity separates it cleanly from siblings like search_audit, list_tasks, or get_resource, which each cover only one slice.

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?

Usage is clearly implied by the framing question ("what failed in the last hours?") and the window parameter, so an agent knows this is the triage entry point. It also warns that older failures may already be gone from midPoint's operation records, hinting at search_audit for deeper history, but it never states that alternative explicitly or says when not to use this tool.

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

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 it does disclose real behavior: results derive from midPoint request rules (#assign authorizations read by the server account), each role reports allowed relations (default member), date/field permissions, and allowing rules. It also documents a fallback mode when rules cannot be read (flagged-requestable roles, preview.basis indicates which) and that midPoint still decides on submit. However, it does not state permissions required for the caller, latency/caching behavior, or what an empty result means (no rules vs. nothing requestable).

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 dense with useful detail, but the closing block about untrusted quoted text and naming by display names is generic boilerplate not tied to this read-only listing tool, and the rules/fallback explanation is packed into one long sentence. It is informative but heavier than needed for a three-parameter list tool.

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 shape need not be explained; the description instead covers the parts an agent cannot infer — data provenance, the fallback basis flag, exclusion of held roles, and the follow-up workflow. For a read-only listing tool with full schema coverage, nothing essential 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 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: forUser is framed as a cross-reference to list_request_targets and the returned set is defined relative to what that user does not already hold. The limit and query parameters are left entirely to the schema, which is acceptable at full coverage.

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 roles the caller may request) and immediately scopes it: for themselves or for another user via forUser. It also distinguishes itself from the two nearest siblings by naming them — list_request_targets answers 'for whom' and request_role is the follow-up action.

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?

Explicit routing: use this tool to see what is requestable, use list_request_targets to pick the person, use request_role to submit, then list_my_requests / list_work_items to track approval. It also states a meaningful exclusion — roles the person already holds are left out — which prevents misinterpretation of results.

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

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

With no annotations, the description carries the full behavioral burden and does so: it discloses the authorization model behind the results, the degraded behavior when rules cannot be read (only the caller is listed), and that the result is not authoritative for the actual submit decision. It also hints at the return content (each person with the rules that allow it).

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 core definition, then the chaining guidance, then caveats, which is the right order. It is dense but earns most of its sentences; the closing display-name instruction is somewhat tangential to listing but still useful guidance for the workflow it enables.

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 shape need not be explained, and the description still covers authorization semantics, fallback behavior, and follow-up usage. For a two-parameter, annotation-free list tool, nothing an agent needs to call it 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 100% and both parameters (limit, query) are fully documented in the schema, so the baseline of 3 applies. The description adds no detail about limit or query behavior; its identity-format note about display names versus OIDs concerns writes elsewhere rather than this tool's inputs.

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 people the caller may request roles for") plus the mechanism (midPoint request rules / #assign authorizations). It is clearly distinguishable from siblings like list_requestable_roles and list_my_teammates because it describes whose identities are returned and why.

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 explicit downstream usage: pass a returned person as forUser to list_requestable_roles and as userOid to request_role, which establishes a clear workflow. It also warns that midPoint still decides on submit, so the list is advisory. It does not say when to prefer this over siblings like whoami or list_my_team, so no explicit exclusions.

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

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

No annotations are provided, so the description must carry the behavioral burden. It clarifies that resources are connected systems but does not describe pagination, default result size, or safety characteristics; the limit parameter's behavior is only in the schema.

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 purpose is front-loaded in a compact first sentence. However, the second sentence is tangential to a listing tool and does not clearly earn its place in this definition.

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?

This is a simple tool with one optional parameter and an output schema, so return values need not be explained. Still, the description lacks usage guidance relative to sibling tools and the second sentence is confusing rather than completing the operational picture.

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%, including the limit default and maximum, so the baseline is 3. The description adds no further meaning about how limit affects listing behavior.

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 uses a specific verb and resource: 'List midPoint resources (connected systems)'. This clearly distinguishes it from singular retrieval siblings such as get_resource, though it does not explicitly name or differentiate against test_resource or search_objects.

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 guidance on when to use this tool versus get_resource, test_resource, or search_objects. The second sentence concerns naming conventions when writing to a person, which is unrelated to selecting this listing tool.

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

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.

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.

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

With no annotations, the description carries the full burden and does substantial work: it states that offered items are only visible to people allowed to read them, warns that the result names whose inbox it is (the server's configured account, not necessarily the caller), and flags that bracketed lines are untrusted third-party text to be treated as data. It never explicitly says the call is read-only or whether results are ordered, which keeps it from a 5.

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?

Purpose and scope are front-loaded in the first clause, and the claim/release workflow follows logically. It is dense with parentheticals, and the closing sentence about using display names when writing to people is a general convention rather than something specific to listing, but overall the text earns its place.

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 single-parameter list tool with an output schema, the description covers the important unknowns: what composition of items is returned, group-offer visibility, whose inbox it is, and safe handling of untrusted embedded text. Only ordering/pagination behavior beyond the limit parameter is left unaddressed.

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?

There is a single parameter (limit) with 100% schema description coverage, so the schema already supplies default and maximum. The description adds no additional meaning about how limit interacts with the inbox listing (e.g., ordering or whether limit truncates silently), so the 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?

Names a specific verb and resource ("List ... approval inbox: open work items") and defines the exact scope: items assigned to the caller plus unclaimed group-offered items. This is clearly distinct from siblings like list_tasks or list_my_requests, and an agent can tell which set of objects comes back without opening the 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 onward: an offered item "must be claimed (claim_work_item) before it can be approved or rejected" and a claimed item "can be given back (release_work_item)", which tells the agent how this tool fits the claim/decide/release workflow. It stops short of stating when to prefer this over list_tasks for a non-inbox view, so it is strong but not exhaustive.

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

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

With no annotations, the description carries the full burden; it does disclose that the call is a GET against /ws/rest/self, which implies a safe read and reveals the auth surface (the response reflects the caller's authenticated identity). It does not state whether it requires authentication to succeed, what happens when midPoint is unreachable, or whether it has side effects — meaningful gaps for a health-check tool with zero annotation coverage.

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 operational sentence is front-loaded and efficient, and the endpoint reference is a useful concrete anchor. The trailing sentence about display names versus OIDs is unearned for this tool — it is irrelevant to a parameterless ping and dilutes focus, though the overall length remains short.

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-value explanation is not required, and with zero parameters the surface is simple. The definition is nonetheless incomplete in a way that matters: the sibling whoami is an apparent duplicate and nothing here tells the agent which to prefer, and the misplaced write-guidance sentence suggests boilerplate rather than deliberate scoping.

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?

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description adds nothing that could conflict with the empty 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 concrete verb+resource: check connectivity to midPoint and report the authenticated identity, reinforced by naming the underlying endpoint GET /ws/rest/self. It does not, however, distinguish itself from the sibling whoami tool, which on its face appears to return the same identity information, leaving the agent to guess which to call.

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 guidance on when to use this versus whoami, which is the obvious alternative for identity lookup. The second sentence ('When you write to a person, name people, roles and requests by their display names rather than OIDs') is usage guidance for write tools like create_user or assign_role, not for a zero-parameter connectivity check, so it provides no applicable routing help here.

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

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

With no annotations at all, the description carries the full burden and does a fair job: it discloses the write-gate requirement, the dry-run fallback, and a validation rule (the call is refused when userName doesn't match the OID). It doesn't say what state is affected or what a recompute can change downstream, so it's solid but not exhaustive.

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?

Purpose and effect are front-loaded in the first clause, followed by parameter clarification and then constraints. The trailing sentence about naming people by display names is house-style guidance rather than tool-specific instruction, but it is short and does not bury the main point.

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 two-parameter mutation tool with an output schema, the description covers gating, dry-run behavior, and identity validation, which is the operationally important surface. Return values need no explanation given the output schema exists.

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% and the schema already states 'must match oid' and 'login, not the full name', so the description largely restates the schema rather than adding new meaning. Baseline 3 applies when the schema does the heavy lifting.

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 ('Recompute (reconcile) a user') plus the concrete effect: midPoint re-evaluates policies and propagates changes. That separates it from pure state toggles like enable_user/disable_user, though it never names a sibling by way of contrast.

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 real invocation context: it needs the write gate, and without it the call degrades to a dry-run preview, which also implies a confirmation step ('the person confirming it'). It stops short of explicit when-not-to-use guidance or routing to an alternative tool.

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

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

With no annotations, the description carries the full burden and does real work: it discloses a pre-flight read performed as the caller, the four refusal conditions, that the release executes under the caller's identity, and that a write gate applies. The remaining gap is that 'the write gate' is unexplained jargon and the effect on the item's state after release is only implied.

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?

Purpose is front-loaded in the opening sentence, followed by preconditions, then parameter semantics — a sensible order. The closing sentence about naming people, roles and requests by display name is a general output-style rule that sits awkwardly at the end of a write tool's description and is the weakest use of space.

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 four-required-parameter mutation with no annotations and an output schema present, the description covers the risk surface that matters: identity of execution, refusal conditions, and cross-field validation. It does not spell out what the tool returns or whether the released item becomes immediately claimable by others, but the output schema absorbs part of that load.

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 baseline is 3, but the description adds meaning the schema does not: userName and roleName must be the midPoint unique-name attribute matching the OIDs, and the call is refused when they disagree — an integrity check an agent would otherwise not expect. It also warns against passing display names, which the schema does not mention.

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 concrete verb and resource: give back a claimed approval work item to the group it was offered to, undecided. It implicitly distinguishes itself from the claim direction, but never names the siblings claim_work_item or decide_work_item, so an agent must infer those routes rather than being routed to them.

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 precondition (claimed: true, per list_work_items) plus an explicit exclusion list — closed, not claimed, held by someone else, or assigned directly rather than offered to a group. It stops short of naming which sibling to use instead in each of those cases, but the when/when-not picture is unambiguous.

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

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

With no annotations supplied, the description carries the full burden and does so: it discloses that the outcome is policy-dependent (approval case vs immediate execution), that non-requestable roles are refused to avoid accidental grants, that the requester is always the authenticated user, that name/OID mismatches cause refusal, and that a write gate applies. That is exactly the behavioral context an agent needs for a mutation tool.

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 core action and the policy caveat before any caveats about naming. The middle clause ("so by default this refuses roles ... because for those it would grant rather than request") is dense and takes a second read, and the trailing display-name sentence reads as a general convention rather than tool-specific instruction, costing a point.

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 an 8-parameter mutation tool with a nested fields object and no annotations, the description covers the decisive unknowns: policy-driven async approval versus immediate execution, the requestable-role restriction, identity of the requester, and the name-matching contract. An output schema exists, so return values need not be described.

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 baseline is 3, but the description adds genuine meaning beyond the schema: it explains that roleName/userName are midPoint unique names rather than display names, must match their OIDs, and that the call is refused on mismatch so the confirming human reads the right names. The display-name-over-OID convention for writes is also extra guidance not present in the 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 and resource ("Request a role for yourself or a report") and immediately explains the underlying mechanics ("Submits an assignment-add delta; midPoint policy decides whether that opens an approval case or executes immediately"). It explicitly contrasts itself with the sibling assign_role, so an agent can separate the two without reading either 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?

Gives an explicit when-not: by default it refuses roles the catalog does not flag requestable, with a named alternative for the deliberate-grant path (assign_role) and a pointer to list_requestable_roles for discovering valid targets. It also names the preconditions (write gate, authenticated user as requester) an agent must satisfy before calling.

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

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

With no annotations supplied, the description carries the full burden and does so: it discloses the suspended-only precondition and refusal behavior, the write-gate requirement with dry-run fallback, the taskName/taskOid cross-validation refusal, and that the result reports executionState read back after the call. That is exactly the mutation, authorization, and post-condition context an agent needs.

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 tool-specific content is front-loaded and efficient: purpose, refusal condition, parameter intent, auth behavior, and return value each get a clause with no padding. The trailing block about untrusted quote text and display names is generic policy boilerplate not specific to this tool, which slightly dilutes the definition.

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 two-parameter mutation with no annotations, the description covers preconditions, authorization/dry-run behavior, parameter coupling, and the post-call state readout; an output schema exists so detailed return shape is unnecessary. Nothing an agent needs in order 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 100% and the taskName property description already states 'as list_tasks and get_task give it; must match taskOid', so most of the description's parameter text is duplicative. It adds only the rationale that the name is what the confirming person reads, which is a modest value-add beyond the 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 and resource ('Resume a suspended midPoint server task') and extends scope precisely to 'a closed recurring one', with the outcome ('so it runs or is scheduled again'). This clearly separates it from siblings like suspend_task and run_task without needing their schemas.

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 an explicit precondition and exclusion: 'A task that is not suspended is refused.' It also tells the agent what happens without the write gate (dry-run preview). It stops short of naming the sibling tools (suspend_task, run_task) as the alternatives, but the when-to-use condition is unambiguous.

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

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

With no annotations supplied, the description carries the full burden and does so well: it discloses the refusal conditions (suspended task, name/OID mismatch), the write-gate/dry-run behavior, and the side effect on recurring schedules. It stops short of describing idempotency or whether the run can be undone, which keeps it from a 5.

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 tool-specific sentences are dense and front-loaded with no waste, but roughly a third of the text is a generic untrusted-quote warning plus a display-name formatting rule that applies to the whole server, not this tool. That boilerplate dilutes the signal an agent needs at selection time.

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 explained, and the description still adds that the result reports executionState read back after the call. Combined with refusal conditions, gating, and naming rules, nothing needed to invoke 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 100%, so the baseline is 3, but the description adds real value: it identifies taskName as the unique name attribute 'as list_tasks and get_task give it', explains the cross-check against taskOid, and gives the reason (the confirming person reads the right name). That meaning is not derivable from the schema alone.

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 ('Run a midPoint server task now') and immediately pins down the scope: runnable or closed tasks, with recurring tasks continuing on schedule. It distinguishes itself from the sibling resume_task by naming it as the correct tool for suspended tasks.

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 covers when to use (runnable or closed task, start immediately) and when not to (suspended task is refused, use resume_task instead). It also states the preconditions — the write gate and the dry-run fallback — so the agent knows the outcome before calling.

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

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

With no annotations, the description carries the full load and does it well: it discloses the script-execution authorization requirement and the impersonation failure mode, which an agent cannot infer from the schema. It leaves out result volume/pagination behavior beyond the limit parameter, so it is short of exhaustive.

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 and dense, with purpose and constraints in a single opening clause. The trailing 'When you write to a person...' sentence reads as if lifted from a mutation tool and adds ambiguity rather than clarity, so not every sentence earns its place.

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?

Eight optional parameters and an output schema mean the description only needs to cover intent and operational constraints, which it largely does. The one gap is the unclear closing instruction, which could cause an agent to misuse or misapply it on a purely read operation.

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 defaults (30 days, limit 20/100) and RFC3339 formats are already documented; the description only restates the filter families. The closing sentence about naming people, roles and requests by display names is oddly phrased for a read tool and does not clearly map to any of the eight filter parameters.

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 ('Query the midPoint audit trail') and enumerates the subject matter (who changed what and when, logins, approvals) plus the filter axes. It is clearly distinguishable from the CRUD/read siblings, though it never contrasts itself with search_objects, the nearest overlapping read tool.

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 strong when-not condition: no REST audit endpoint exists in 4.10, so it needs script-execution authorization and fails under resource-server (OIDC) impersonation. It does not name an alternative tool to use when that constraint bites, or say when to prefer search_objects instead.

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

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

No annotations are supplied, so the description bears the full burden. It discloses the query-language mechanism and that the tool is an exploratory/reporting primitive, but never states plainly that it is read-only and non-mutating, nor does it warn about filter-syntax failure modes; the display-name-vs-OID remark is a cross-cutting convention rather than a behavioral trait of this call. The presence of an output schema relieves it of describing return values, which keeps this at 3 rather than lower.

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, front-loaded with the verb and scope, with no filler. The second sentence is the weak point: it addresses writing to people and requests, which belongs on a mutation tool's description and is not earned by this tool's surface area.

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 an output schema, full parameter documentation and only three inputs, the description is close to sufficient for correct invocation. What is missing is the routing information an agent actually needs: how this differs from search_users and the list_* siblings, and any notion of result volume or paging behavior beyond the limit parameter.

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%, so the schema already documents type, limit (default 20, max 100) and filter with a worked example. The description adds no parameter-level meaning beyond labeling the filter as "midPoint query-language"; the example report types hint at filter shapes but supply no syntax. 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?

States a specific verb and resource ("filtered search across midPoint object types") and enumerates the six supported types, which maps directly to the type parameter. It does not distinguish itself from the near-identical sibling search_users, nor from list_roles/list_resources, so an agent cannot fully resolve which search path to take from the text alone.

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?

Concrete use-case framing is given ("ad-hoc reports (orphaned accounts, unused roles, disabled users with access)"), which implies when to reach for it. However there are no exclusions or alternatives named — nothing says when to prefer search_users or get_user instead — and the closing sentence about "when you write to a person" is guidance for a different operation, not this one, which muddies rather than sharpens usage.

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

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

With no annotations, the description must carry the behavioral load. It discloses that query is a substring match across name/full name/email and that oid mode returns just one user, but says nothing about result ordering, case sensitivity, permissions, or pagination beyond the schema-stated limit.

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 core capability in a single well-formed sentence. The second sentence is compact but reads as a global hint unrelated to searching, which slightly dilutes focus without bloating the description.

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?

Output schema presumably covers return values and the tool is a non-destructive read, so the safety/return burden is low. What remains thin is routing against overlapping siblings (get_user, search_objects) and any search-behavior nuances such as matching rules.

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 all three parameters are already documented. The description restates the query breadth (name, full name, email) and reinforces that oid returns a single result, adding modest emphasis but no new syntax or format detail beyond the 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 and resource ("Find midPoint users") and distinguishes the two lookup modes: free-text query vs exact OID. It does not name or differentiate itself from sibling get_user, which also retrieves a single user by identifier, so boundaries with siblings remain implicit.

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 mode-level guidance (query for free-text, oid for exact, omit to list) but never says when to prefer this over get_user or the various list_* siblings. The closing advice about naming people by display names when writing is workflow guidance for other tools rather than a rule for invoking this one.

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

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 the up-to-2-second completion wait, the scheduled-task behavior, the refusal when taskName does not match taskOid, the write-gate/dry-run preview path, and that executionState is read back after the call. That is unusually specific mutation semantics.

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 operational content is front-loaded and dense, with the effect, naming convention, gate, and return value in order. It is slightly diluted by trailing generic boilerplate about untrusted quote text and display names, which is not specific to suspending a task.

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 two-parameter mutation tool with a declared output schema, everything an agent needs is present: semantics of both parameters, preconditions, failure mode, and timing behavior. The existing output schema covers return values, and the description still notes what is reported, so nothing material 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 100%, so the baseline is 3, and the description adds real meaning beyond it by explaining that taskName is the midPoint unique name as given by list_tasks/get_task and that a mismatch with taskOid causes refusal. The confirmation-safety rationale for the redundant name parameter is the kind of insight the schema alone does not convey.

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 ('Suspend a midPoint server task') and immediately scopes what suspension means for both running and scheduled tasks, which cleanly separates it from resume_task and run_task. The contrast with the sibling that reverses this operation is explicit.

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 clear conditions: a running task stops after its current item, a scheduled one stops being scheduled, and the effect lasts 'until resume_task'. It also states the write-gate prerequisite and dry-run fallback. It does not say when NOT to suspend (e.g., when cancel or run_task is the right choice), so it stops short of full when/when-not guidance.

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

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

With no annotations supplied, the description carries the full burden and does so well: it discloses that midPoint contacts the target system, stores the outcome on the resource (availability and possibly a refreshed schema), and that this side effect drives provisioning. It also states the write-gating behavior and the dry-run fallback, plus the mismatch-refusal rule — precisely the operational facts an agent needs before calling.

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 purpose and side-effect disclosure are front-loaded, which is good, but the sentence is long and parenthetical-heavy. The trailing paragraph about '[untrusted quote text...]' and naming people by display name is generic boilerplate unrelated to testing a resource connection and dilutes the tool-specific content.

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 described, and the description still notes it reports overall status plus each failed check's message. Side effects, gating, dry-run behavior, and parameter cross-validation are all covered, leaving nothing an agent needs missing before invoking it.

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%, and the schema already documents both parameters, including that resourceName 'must match resourceOid'. The description restates that provenance (list_resources/get_resource) and adds the rationale about the confirming person reading the right name, but contributes little semantic detail beyond the schema. Baseline 3 is appropriate.

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 opens with a specific verb and resource ('Test a midPoint resource's connection') and immediately enumerates what is tested: connector initialization, target-system connection, capabilities and schema. It also names the midPoint UI equivalent ('Test connection') and is clearly distinguishable from the read-only siblings get_resource and list_resources, which only fetch configuration.

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?

Usage context is strong: it explains the prerequisite that resourceName must match resourceOid (and that mismatch causes refusal) and that the call is gated like a write, returning a dry-run preview when writes are disabled. It also points to list_resources and get_resource as the source of the name. What it lacks is an explicit exclusion statement such as when a plain get_resource read is sufficient instead.

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