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

No annotations are provided, so the description carries the burden and does well by disclosing the all-or-nothing failure semantics, which is a non-obvious transactional behavior. It also states the cardinality limit (1–1000), though it omits permission/auth requirements and return behavior.

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 dense sentences, front-loaded with the action and scope, then constraints, then transactional behavior. No filler.

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 mutation tool with no annotations and no output schema, the description covers prerequisites, limits, and failure semantics well enough to call it correctly. Missing auth/permission context, but that is a minor gap given the otherwise strong disclosure.

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 three parameters. The description adds meaning beyond the schema by specifying the array size bounds and the all-or-nothing behavior tied to user ID validity, which the schema 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 ('Add 1–1000 users to a group') with a clear scope limit. Distinguishes itself from siblings like list_group_users or delete_group_users by naming the mutating operation precisely.

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 says when to use it ('Requires the group to exist') and routes the agent to prerequisites ('use list_groups or create_group first'). This directly resolves the ambiguity an agent would face among the many group-related 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?

No annotations are provided, so the description carries the full disclosure burden. It does usefully explain that the binding link is delivered via the chosen method (sent to the user or returned directly), but omits permission/auth requirements, what happens if the user already has a credential, and any idempotency or failure behavior.

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 tightly written sentences with the core action front-loaded and the lookup hint placed last. Nothing is wasted, though it is brief enough that a little more detail would not have hurt.

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 mutation tool with no annotations and no output schema, the description covers the basic flow but leaves notable gaps: response shape (since no output schema exists, it should ideally describe what the caller receives), the 15-minute short-code expiry surfaced in the schema, and required authority to create a binding for another user.

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 user_id, delivery_method, and ttl_seconds are already well documented. The description only restates that user_id and delivery method must be specified, adding no format or constraint 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 ('Create a credential binding job') and adds the outcome ('provision a new passkey for a user'), which cleanly separates it from the read-only get_binding_job sibling. It stops short of explicitly differentiating from other creation tools, but the purpose is unambiguous.

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?

Provides ordering guidance ('Use list_users to find the user_id first') and notes the delivery method determines how the link reaches the user. However, it offers no when-not conditions, prerequisites (permissions/issuer identity), or guidance on choosing between delivery paths beyond noting they exist.

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, so the description carries full burden. It discloses the return value (new group with auto-generated id) and the post-creation state (starts empty), which are important behavioral details. It doesn't mention permissions, uniqueness constraints beyond the schema, or idempotency, but it covers the key traits 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?

Three short sentences front-loaded with the action, requirement, and return value, with zero waste. Each sentence earns its place by adding a distinct fact.

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 creation tool with no annotations and no output schema, the description covers the required input, optional fields, return value, and the follow-up tool. It could mention tenant scoping or permissions, but it is largely complete for correct invocation.

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 both the name and description fields, including that both are required. The description mentions display_name and optional description, which is slightly inconsistent with the schema (both are required), but adds no syntax or format details beyond what the schema provides. Baseline 3 is correct when 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 (Create) and resource (group), and distinguishes itself from siblings by naming add_group_users as the follow-up for membership. An agent can tell this apart from scim_create_group and create_user 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 states the requirement (display_name) and the next step (use add_group_users to add members), plus notes the group starts empty. It doesn't contrast with scim_create_group or explain when to prefer one over the other, but the primary usage context is clear.

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; it usefully discloses a uniqueness constraint on email/username and the resulting 409 conflict, plus that the created user is returned with an auto-generated id. It does not state required permissions/scopes, whether external_id is mandatory, or any side effects on groups/bindings.

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, front-loaded with the purpose, then requirements, then the uniqueness/return behavior. Very little waste, though the field-name mismatch costs a bit of precision.

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 nested-object create with no output schema and no annotations, the description covers the return shape and one key failure mode but leaves authorization requirements, optionality of external_id, and the tenant/org scoping unaddressed. Adequate, not 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%, so the baseline is 3. The description adds a genuine constraint (uniqueness + 409) not present in the schema, but its field naming ("user_name", "email") diverges from the schema's "username"/"email_address" and it omits external_id entirely, slightly muddying the mapping.

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+resource ("Create a new user") and immediately names the identifying fields. Despite many sibling tools, the intent is unambiguous and distinguishable from get_user/list_users/update_user.

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 the sibling alternatives such as scim_create_user or create_binding_job, nor any precondition or context for choosing the direct API path over the SCIM path. Usage must be inferred entirely 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?

Annotations already declare destructiveHint=true, but the description adds substantial value: the specific 409 failure behavior, the emptiness precondition, and the irreversibility ('cannot be undone'). It does not describe auth/permission requirements or response shape, but the key destructive and failure characteristics are disclosed.

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, front-loaded with the core action, then the precondition, then the mitigation and the irreversibility warning. Every sentence earns its place with zero waste.

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?

Given 1 param, no output schema, and destructiveHint already set, the description covers the critical preconditions and consequences an agent needs. It could mention permission requirements, but for a single-param delete this is close to 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 group_id param is documented in the schema. The description adds no syntax or format detail beyond what the schema provides; 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+resource ('Permanently delete a group') and clearly distinguishes itself from delete_group_users, which it names as the prerequisite step. An agent can tell this apart from scim_delete_group or delete_group_users without opening a 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 states the precondition (group must have NO members or fails with 409) and names the alternative tool (delete_group_users) to run first. The 'when-not' is fully spelled out via the failure mode.

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 it does disclose a genuinely non-obvious trait: all-or-nothing atomicity, where one invalid user ID fails the whole batch. It still omits permission requirements and what the caller gets back, but the atomicity disclosure is substantive.

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, front-loaded sentences with zero padding; the scope, input shape, and failure semantics each earn their 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 mutation tool with no annotations and no output schema, the description covers scale limits and failure behavior, which are the key operational facts. Missing authorization/permission guidance and post-delete state leaves a small gap.

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 a real constraint not present in the schema: the 1-1000 element bound on the user_ids array. It does not resolve the 'id' vs 'group_id' ambiguity in the schema, which is a residual gap.

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 ('Remove ... users from a group'), plus a batch scope (1-1000). It is cleanly distinguishable from the sibling add_group_users and from single-user removal tools.

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 operation itself (removing memberships from a group), but there is no explicit when-to-use guidance, no mention of prerequisites such as group existence or required scopes, and no routing to alternatives.

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?

Annotations declare destructiveHint=true, and the description goes well beyond that by spelling out the consequences: the passkey is permanently removed, the user can no longer authenticate with it, and the action is irreversible. That is exactly the behavioral context an agent needs before invoking a destructive 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?

Three short sentences, front-loaded with the action and its scope, followed by consequences and the id-sourcing hint. No filler and nothing repeated from structured fields.

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 deletion tool with no output schema, the description covers action, permanence, consequence, and id discovery. Nothing further is needed to call it correctly and safely.

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 there is only a single parameter, so the schema already documents passkey_id fully. The description adds the practical hint that ids come from list_passkeys, which is marginally useful but not new semantic detail about 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?

States a specific verb and resource ('Permanently delete a passkey'), scoped by an explicit identifier. It distinguishes itself from the many sibling tools by naming the passkey domain and the counterpart list_passkeys 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 clear usage context and explicitly routes the agent to list_passkeys to obtain the required id. It does not state when deletion is inappropriate or warn about prior confirmation, but the destructive framing implies caution.

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?

Annotations only declare destructiveHint=true; the description adds real behavioral context beyond that by disclosing the irreversible nature and the side effect of removing all group memberships. It still omits auth/permission requirements and any error or not-found behavior, which keeps it 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 terse sentences, permanence and irreversibility front-loaded, with the side effect trailing. Every clause carries information and none is wasted.

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 mutation tool with no output schema, the description covers intent, irreversibility, and the membership side effect. The only gap is usage routing against the many sibling delete/user tools, which for a simple destructive call is a minor omission.

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 user_id parameter, so the schema already documents it fully. The description adds no identifier-format or scoping 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?

States a specific verb and resource ('Permanently delete a user') with a permanence qualifier. It does not, however, distinguish itself from the sibling scim_delete_user, leaving the agent to guess which delete applies to a given ID scheme.

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 indication of when to use this tool versus scim_delete_user or delete_group_users, and no prerequisites (permissions, target state) are stated. The destructive intent is implied by the text but no routing guidance is offered.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower; the description still adds real value by enumerating the observable states (link sent, completed, expired, failed). It does not say whether the states are terminal, how quickly they change, or whether polling is expected, which keeps it 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?

Two sentences, zero filler, with the action and lookup key front-loaded before the state enumeration. Every clause 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?

No output schema exists, and the description partially compensates by listing the possible states the job can be in. For a read-only, single-parameter tool with safety already declared by annotations, this is nearly sufficient, though a note on whether terminal states are sticky would make it 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% with a single required parameter, so the schema already documents binding_job_id. The description only restates that the lookup is by that id and adds no format, source, or validity detail beyond the schema, which is the expected baseline 3.

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 ('Retrieve the status of a credential binding job') plus the lookup key, so the agent knows exactly what it does. It is clearly the read counterpart to the sibling create_binding_job, but it never names or contrasts with that sibling explicitly, so it falls short of full sibling differentiation.

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 tool takes a binding_job_id and returns its state, so an agent can infer this is a status-polling call after create_binding_job. There is no explicit when-to-use, when-not-to-use, or named alternative, leaving the routing 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 readOnlyHint=true already declaring a safe read operation, the description adds that it returns a group object with specific fields (display_name, description, timestamps). This is useful but modest additional context; it doesn't cover error handling or rate limits.

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 sentences, each earning its place: purpose, return content, and usage pointer. Front-loaded with the core action.

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 single-retrieval tool with annotations and full schema coverage, the description covers purpose, return fields, and usage routing. It could mention error cases or id format, but is largely 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 group_id parameter is fully documented in the schema. The description reinforces that group_id is the identifier but adds no new syntax or format details. 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 uses a specific verb and resource: 'Retrieve a specific group by group_id.' It clearly distinguishes itself from list_groups and other group-related tools by focusing on single-retrieval by ID.

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 explicitly names list_groups as the way to discover group_ids, which provides clear when-to-use context. However, it doesn't mention exclusions or other alternatives like scim_get_group.

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?

readOnlyHint=true already establishes a safe read, so the bar is lower. The description usefully adds that this is a fixed, static server-capability endpoint and names what the payload reports, but says nothing about caching, rate limits, or whether the max-results value can vary by tenant.

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, capability detail front-loaded, no filler. Every clause 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?

There is no output schema, and the description compensates by enumerating the capability categories (authentication, filtering, patch support, max results = 1000), which is enough for an agent to know what it will receive from a parameterless read.

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?

Zero parameters, so there is nothing for the description to disambiguate; the schema is trivially complete. Baseline 4 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 (Get) and resource (SCIM service provider configuration) plus the concrete payload contents: authentication, filtering, patch support, max results. No sibling exposes server capability config, so it is unambiguous.

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 implies when to use it — a fixed server-capability endpoint that takes no parameters — but never states when to call it versus other SCIM discovery tools like list_resource_types or list_schemas, and gives no scenario guidance. Usage is inferable rather than explicit.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the concrete return payload (email, username, display_name, status, timestamps), which is genuinely useful since there is no output schema, but it omits behavior on missing/nonexistent user_ids (error vs empty).

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, each contributing: purpose, return shape, and the discovery path. Front-loaded with the action. No filler, though the return-field list is slightly encyclopedic.

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 single-parameter read with no output schema, the description covers purpose, parameter meaning, return contents, and how to find valid ids. It is close to complete, with only error behavior for an unknown id left unspecified.

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 and schema coverage is 100%, so the schema already documents user_id fully. The description does not add format, source, or validity constraints beyond the schema, making the 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+resource ('Retrieve a specific user by user_id'), so the action is unambiguous. It differentiates from the list-style siblings by naming list_users as the discovery alternative, though the SCIM counterparts (scim_get_user, scim_list_users) are not addressed.

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 context for using this tool (look up one user by id) and explicitly routes to list_users to discover user_ids. There are no stated exclusions or prerequisites such as scope/auth needs, so it falls short of a 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?

Annotations declare readOnlyHint=true, so the safe-read profile is covered by structured data rather than the description. The description adds the tenant scope and pagination behavior, which is useful, but does not describe filter capabilities or auth/rate-limit context. A moderate score is appropriate given the annotations do the safety heavy-lifting.

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 core verb and resource, then return/pagination details. No filler, though the mention of 'logical collections of users' is somewhat tangential but still informative.

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?

A read-only list tool with no output schema, readOnlyHint covering safety, and complete parameter documentation in the schema. The description covers tenant scope and pagination but omits return field details or link to alternatives among the many group-listing siblings. Adequate but not rich.

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 all four parameters thoroughly (skip, filter, order_by, page_size). The description only names the parameter families (page_size, skip, filter, order_by) without elaborating on syntax or semantics. Baseline 3 when the schema does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (list) and resource (groups) scoped to the tenant, which is clear on its own. However, it does not differentiate from the many sibling group-listing tools such as get_groups, scim_list_groups, or list_user_groups, leaving the agent to guess which one applies.

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?

No guidance on when to use this tool versus the numerous sibling group/list tools. There's no mention of prerequisites or conditions selecting this tool over get_groups or scim_list_groups. Usage is only implied by 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful context beyond that: it returns full user objects and supports pagination. It does not describe auth requirements, rate limits, or default page size behavior.

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, front-loaded with purpose, then return shape, then the prerequisite and alternative. Zero filler.

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 no output schema, the description usefully discloses that full user objects are returned with pagination, which is what an agent needs to know. Minor gaps remain around default page size and filter/sort behavior, but they are documented in the 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?

Schema description coverage is 100%, so skip, filter, order_by, page_size, and group_id are all documented in the schema. The description only restates the group_id requirement and the pagination nature, adding little beyond the schema. 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 ('List all users that are members of a group'), which distinguishes it from sibling list_users (all users) and list_user_groups (groups for a user). It stops short of explicitly named differentiation, but the phrasing is unambiguous.

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 ('Requires group_id') and a concrete discovery path ('use list_groups to discover groups'). No when-not guidance, but the context is effectively covered for a straightforward read.

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?

Annotations only declare readOnlyHint=true, so the description carries the rest. It adds genuinely useful behavioral context: the returned fields (state, type, associated user info) and that pagination/filtering are supported. No auth or rate-limit notes, but this goes meaningfully beyond the annotation.

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 the core action front-loaded. The final sentence defining passkeys is mildly educational rather than operational, but it is brief 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?

With no output schema, the description usefully enumerates the returned fields. Pagination and filtering are flagged, and the filter/order syntax lives in the schema, so an agent has enough to call it. Missing detail on result volume or defaults is minor.

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 skip, filter, order_by, and page_size are already fully documented including SCIM filter grammar and sort syntax. The description only restates that filtering and pagination exist, adding no syntax 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+resource+scope: 'List all passkeys across the tenant.' An agent can distinguish it from delete_passkey or list_passkey_tags, though no sibling is named explicitly to sharpen 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?

'Supports pagination and filtering' hints at how to use it, but there is no explicit when-to-use versus alternatives guidance, no prerequisites, and no exclusions. Usage is implied by the listing verb 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?

The readOnlyHint annotation already tells the agent this is a safe read operation, so the description's main additional value is clarifying that tags are key-value metadata. It does not describe return format, pagination, ordering, or empty-list behavior; with annotations covering the safety profile, this is adequate but not rich.

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 zero waste. Purpose is front-loaded, tag definition follows, and the required-parameter directive closes the description cleanly.

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 read-only list tool with 100% schema coverage and readOnlyHint, the description is nearly complete: it states purpose, defines tags, and directs parameter discovery. It lacks only return-shape or empty-result guidance, which is minor given the tool's simplicity.

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 passkey_id parameter is fully documented in the schema. The description reinforces that passkey_id is required and how to obtain it but adds no format or semantic 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?

States a specific verb+resource: 'List all tags associated with a passkey.' The second sentence clarifies what tags are, and the third ties the tool to its sibling context by naming list_passkeys for passkey discovery.

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 states the tool requires passkey_id and points to list_passkeys as the way to discover passkeys. It provides clear when-to-use context (when you have a passkey and want its tags) but does not contrast against set_passkey_tags or explain when-not-to-use.

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?

The readOnlyHint annotation already establishes the safety profile, so the description's job is to add context. It does so usefully: it discloses the exact return payload (metadata on schemas, endpoints, and supported operations) and that the endpoint is fixed, meaning no parameters and a stable result. Return format beyond the general content is not detailed, keeping it 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 zero filler: the first states what is listed, the second what is returned, the third a key behavioral constraint. Information is front-loaded and 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?

With no output schema, the description compensates by summarizing the return contents (schemas, endpoints, supported operations), and the absence of parameters matches the fixed-endpoint framing. An agent has everything needed to decide and invoke correctly.

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 and the schema is an empty object, so there is nothing to disambiguate. Per the scoring baseline for 0-param tools, a 4 is appropriate; the description correctly implies no input is needed by calling it a fixed endpoint.

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 names a specific verb and resource ("List SCIM resource types supported by this server") and narrows the scope to User and Group. It also labels the tool as a "fixed server-capability endpoint," which helps separate it from dynamic listing siblings, though it never names a specific alternative like list_schemas or get_service_provider_config.

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: an agent should call this to discover which SCIM resource types exist before operating on them, and the "fixed server-capability endpoint" phrasing hints this is static discovery info. However, there is no explicit when-to-use guidance and no comparison against sibling discovery tools such as list_schemas or get_service_provider_config.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that the endpoint is fixed/server-capability, meaning results are static and unfiltered, which is genuinely useful context. It does not, however, describe response shape or pagination, so it is a modest rather than rich addition.

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 compact sentences, front-loaded with the action and resource, with the second sentence adding the only non-obvious fact. Nothing is wasted.

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 no-parameter, read-only discovery endpoint with no output schema, the description tells the agent what is returned (core schemas and vendor extensions) and that it is static. That is sufficient; only the concrete return format is unstated, which is minor.

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 the baseline is 4. The description correctly implies there is nothing to configure by calling it a fixed capability endpoint, and the empty schema confirms this.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (SCIM schemas), and names the scope: core schemas plus Beyond Identity extensions. It does not explicitly differentiate from the closely related discovery sibling list_resource_types, so it falls 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 phrase 'fixed server-capability endpoint' implies this is a static discovery call with no filtering, which hints at when to reach for it, but there is no explicit when-to-use guidance or comparison to list_resource_types or get_service_provider_config.

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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely new behavioral context beyond that: it returns full group objects and the result set is paginated, which tells the agent to expect paging behavior and complete group payloads rather than ids.

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, zero waste, with the core purpose front-loaded and the prerequisite/routing note last. 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?

With no output schema, the description usefully covers the return shape ('full group objects with pagination'), which is exactly what an agent needs to interpret results. Only minor omissions remain, such as default page size behavior, which the schema partially covers.

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 skip, page_size and user_id are already documented in the schema. The description only restates that user_id is required and alludes to pagination, adding little beyond the structured fields — the expected baseline of 3.

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 ('List all groups a user belongs to'), and the relational direction ('groups a user belongs to') inherently separates it from the inverse sibling list_group_users. It stops short of explicitly naming list_groups or get_groups as the alternatives an agent might confuse it with.

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 clear preconditions ('Requires user_id') and routes the agent to list_users to obtain that id. There is no explicit when-not guidance or comparison against sibling group-listing tools, so it falls just short of a 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?

Annotations already confirm this is a safe read operation. The description adds pagination context, which is helpful for behavior. However, it does not disclose return limits, default page sizes, or any other operational constraints beyond basic pagination.

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 description is a single, efficient sentence that front-loads the core action. It is appropriately sized but could be slightly more structured by separating pagination and filtering details.

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?

Given the lack of an output schema and no usage guidelines, the description is adequate but not complete. It covers the basic behavior but omits crucial context about when to choose this tool over siblings.

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 fully documents all four parameters. The description only lists parameter names without adding meaning beyond what is already available, meeting the baseline for high-coverage 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?

States a specific verb and resource ('List all users for the tenant'), making its purpose immediately clear. It is distinguishable from write-oriented siblings like create_user or update_user.

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?

No guidance is provided on when to use this tool versus alternatives. It fails to mention sibling tools like scim_list_users or scim_get_user, leaving the agent to infer the correct context.

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 flags the operation as sensitive, discloses that the old certificate can no longer issue new credentials, and clarifies that existing credentials stay valid until expiry. It omits auth/permission requirements and confirmation of irreversibility, which keeps it 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?

Two sentences, front-loaded with the action and resource, then the consequence. Every clause carries information; nothing is redundant.

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 destructive mutation with no annotations and no output schema, the description conveys the key outcome and the scope of impact on existing credentials. It falls short only on operational prerequisites (permissions, need for a successor certificate) that an agent would want 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?

The tool effectively takes no meaningful input (a single empty body object, 100% schema coverage with no fields to document). There is nothing for the description to add on parameters, so the baseline for a zero-parameter call 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 (Retire) and a precisely scoped resource (the intermediate tenant certificate used for device credential signing). No sibling tool overlaps with this action, so the agent can identify it immediately 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?

The description implies when the tool is relevant by describing the effect of retiring, but it never states the preconditions for calling it (e.g., whether a replacement certificate must already be provisioned) or any situation in which it should be avoided. With no alternative tools offering this capability, there is no sibling routing to clarify either.

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. It does disclose useful traits: rejected reserved names, a 404 for non-existent member IDs, and the optional/required split. It omits permission/auth requirements, name-collision behavior, and what the response returns, leaving meaningful gaps for a write operation.

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?

Four short sentences, front-loaded with the action and the required field, with each constraint earning its place. "Requires displayName" partly restates the schema's required array, which is the only mild redundancy.

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-parameter SCIM write with nested member objects and no output schema, the definition covers the constraints an agent needs to construct a valid call. It is missing auth/permission context and any note on the extension schema's optionality, but it is close to 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%, so the schema already documents members, schemas, displayName and the extension object. The description reinforces the required/optional split and the existing-user constraint on members but adds no syntax or format detail beyond the schema, so the baseline 3 is right.

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 precise verb+resource ("Create a group via SCIM") and the protocol qualifier helps separate it from the sibling create_group. It stops short of explicitly contrasting with that sibling, but the action and object are unambiguous.

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 preconditions: displayName is required, reserved permission group names are disallowed, members must reference existing users. However, it never states when to choose this over the sibling create_group or add_group_users, so routing guidance is only implied.

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 disclose a genuinely non-obvious trait: on duplicate externalId/userName the existing user is reactivated instead of erroring (upsert semantics). It omits auth/permission requirements and the response shape, 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?

Three tight sentences, front-loaded with purpose and then the two most decision-relevant facts (required fields, conflict behavior). The required-field enumeration partially duplicates the schema's required array, a minor redundancy.

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 nested objects, no output schema, and no annotations, the definition covers inputs and the conflict path but leaves out auth requirements, what happens to unmentioned fields on reactivation, and the response format. Adequate but with meaningful 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?

Schema description coverage is 100%, so the schema already documents all 8 parameters including the nested name and emails objects. The description's required-field recap (including "at least one primary" email) mostly restates what the schema already says, adding little beyond the baseline.

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 ("Create a user") plus the API surface ("via SCIM"), which implicitly separates it from the sibling create_user. It stops short of explicitly naming which sibling to use under what conditions, so it's 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?

No when-to-use / when-not-to-use guidance and no routing among the many siblings (scim_replace_user, scim_update_user, create_user). The required-field list and conflict note describe mechanics rather than selection criteria, leaving usage entirely implied.

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?

The destructiveHint annotation already signals a write/destroy operation, and the description adds value beyond it by disclosing the cascade side effect ('automatically removes the group from all member users') and a hard precondition (reserved groups are undeletable). It does not cover auth requirements or failure behavior for non-existent group IDs.

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 zero filler, ordered by importance: action, hard constraint, side effect. 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?

For a one-parameter destructive tool with annotations and no output schema, the definition covers the essential risk surface: irreversibility is implied by the annotation, cascade impact and the reserved-group guard are explicit. Minor gaps remain around authorization and error conditions on invalid IDs.

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% for the single group_id parameter, so the schema already carries the parameter's meaning. The description adds no format, sourcing, or lookup guidance beyond it, making the 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 ('Delete a SCIM group'), and the 'SCIM' qualifier distinguishes it from the sibling delete_group, which operates on a different group model. An agent can route between them without opening 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 exclusion: reserved permission groups cannot be deleted, which is a real when-not condition an agent must know before calling. It stops short of naming alternatives (e.g. scim_update_group for modifying membership instead of deleting), so it is not fully prescriptive.

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?

Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses the cascading side effect (removal from all groups) and the non-deterministic soft-vs-hard delete behavior driven by configuration, which an agent cannot learn from the annotations or 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?

Three short sentences, front-loaded with the action and followed by the two behavioral facts that matter most. No filler, though the phrasing is clipped rather than polished.

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 delete with no output schema, the description covers the essential behavior: what is removed, the cascading group effect, and the variability of the operation. It omits only secondary details like permission requirements and the response shape after deletion.

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 (user_id) and schema description coverage is 100%, so the schema fully documents it. The description adds nothing about the ID's format or source, 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?

States a specific verb and resource ('Delete a SCIM user') and the SCIM qualifier implicitly separates it from the generic delete_user sibling. It also adds scope detail ('Removes the user from all groups'). It stops short of explicitly naming when to prefer it over delete_user, but the intent is unambiguous.

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. With siblings like delete_user, scim_delete_group, and delete_group_users present, the description never clarifies which deletion tool applies to which resource, leaving the agent to infer from the name alone.

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?

readOnlyHint=true already tells the agent this is a safe read, so the annotation carries the safety profile. The description adds the return shape ('full SCIM Group resource including members array'), which is genuinely useful context, but says nothing about permissions, error behavior on unknown IDs, or whether members are paginated.

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 purpose front-loaded and the return value immediately after. Every clause earns its place with no filler.

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 no output schema, the description usefully compensates by naming the returned resource and the members array, which is the key detail for a get-by-id call. It stops short of covering error cases or auth requirements, leaving a minor gap for a tool this simple.

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 required group_id is already documented in the schema as 'ID of the group.' The description names the parameter but adds no format, source, or constraint beyond what the schema provides, 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 description states a specific verb (Retrieve) and resource (SCIM group) scoped by group_id, so an agent can distinguish it from list-style siblings like scim_list_groups. It does not explicitly name a sibling, but 'a specific ... group by group_id' adequately contrasts with the list variants.

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 — you use it when you already have a group_id, versus scim_list_groups when you don't. There is no explicit when/when-not statement and no named alternative, so an agent must infer the routing decision.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that it returns the full SCIM User resource but says nothing about error behavior, missing users, or permissions. Some added value but not rich.

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 concise sentences with the core action front-loaded and no wasted words.

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-by-ID tool with annotations covering safety and a fully documented parameter, this is adequate. However, it lacks any disambiguation from the many similar get/list siblings and does not mention what a missing user 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 coverage is 100%, so the single user_id parameter is fully documented in the schema. The description repeats that user_id identifies the user but adds no format, constraints, or examples 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?

The description states a specific verb (Retrieve) and resource (SCIM user by user_id), and clarifies the return payload is the full SCIM User resource. It does not explicitly differentiate from sibling get_user or scim_list_users, but the SCIM and single-user scope makes it reasonably distinct.

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?

No guidance on when to use this versus alternatives like get_user, scim_list_users, or scim_get_group. The description implies fetching a single user by ID but offers no context or 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?

readOnlyHint=true is already declared, so the safety profile is covered; the description earns credit for adding the return shape (displayName, externalId, members, Beyond Identity extensions) and the permission-group limitation, which is real behavioral context not present in the annotations. It omits pagination/response-envelope behavior, which is a minor 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?

Two sentences, zero filler: the first establishes the resource and protocol, the second covers the return payload and the key limitation. Front-loaded with the identity-relevant information.

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 no output schema, the description usefully enumerates the return fields, and annotations cover the read-only nature. For a zero-required-parameter list tool this is largely complete, though it could say more about how count/startIndex interact with the result paging.

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?

All three parameters (count, filter, startIndex) carry full descriptions in the schema, giving 100% coverage, and the description adds nothing about count semantics, filter grammar, or index behavior. With the schema doing all the work, 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?

States a specific verb (List) and resource (groups) and scopes it to the SCIM v2.0 protocol, which distinguishes it from the plain list_groups sibling. It also enumerates the returned Group fields, so the agent knows exactly what comes back. It stops short of naming an alternative explicitly, which keeps it below 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 implies usage (SCIM protocol, read-only listing) and adds a useful boundary note that permission groups cannot be created or modified via SCIM, which hints this listing covers non-permission groups. However, it never states when to prefer this over list_groups or get_groups, so the routing guidance is only implied.

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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely new behavioral context: the 1000-result page cap, the pagination model, and the shape of returned resources. It does not mention auth requirements or totalResults semantics, keeping it 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 tight sentences, front-loaded with the protocol and scope, then capabilities, then return shape. No filler or redundancy.

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 no output schema, the description usefully states what comes back (SCIM User resources with standard and extension attributes) and covers the page-size limit. It omits totalResults/pagination cursor behavior and any auth prerequisites, which is a modest gap for a read-only list 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 all three parameters are already documented in the schema with their own semantics. The description only restates that filtering and pagination exist, adding no syntax or format detail beyond what the schema provides — the baseline 3 for high-coverage 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?

States a specific verb+resource (list users) and names the protocol (SCIM v2.0), which is what separates it from the plain `list_users` sibling. It stops short of explicitly contrasting with `list_users` or `scim_get_user`, so an agent must infer the 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?

No when-to-use or when-not-to-use guidance is given. It describes capabilities (filtering, pagination) rather than conditions for choosing this tool over `list_users`, `get_user`, or `scim_get_user`, so routing is left entirely 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses ETag-based optimistic locking for concurrency and the consequence of full-replacement semantics (all required fields must be supplied). It does not mention auth requirements or what happens to omitted optional fields, leaving some gaps.

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, no waste, front-loads the PUT semantics and the concurrency mechanism. Every clause carries information the agent needs for correct invocation.

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?

Given full schema coverage of a complex nested object and the absence of annotations, the description supplies the key behavioral facts (full replacement, ETag locking). It is slightly thin on auth/prerequisite details and doesn't clarify the ETag round-trip, but is otherwise sufficient for correct invocation.

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 all ten parameters thoroughly, including nested email handling and schema constraints. The description adds the meta-level rule that all required fields must be present, but no per-parameter guidance beyond what the schema provides. 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 (replace) and resource (SCIM user) and explicitly distinguishes full-replacement PUT semantics from partial update. This clearly separates it from scim_update_user (likely PATCH).

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 states 'this is not a partial update', which tells the agent when to prefer scim_update_user instead. It doesn't name the sibling tool directly, but the semantic distinction is clear enough for 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses a max batch size limit and the add/remove member scope, but says nothing about permission requirements, atomicity of PATCH ops, failure behavior, or what a successful response contains 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?

Two tightly written sentences with the operation type front-loaded and zero filler; the constraint (max batch size) is attached to the relevant capability.

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?

No output schema and no annotations, and low schema coverage mean the description should carry more. It omits the required 'schemas' parameter, permission/role requirements, and error or partial-failure semantics that an agent needs before issuing a PATCH.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33% (group_id documented; schemas undocumented; Operations partially documented). The description adds the batch-size limit and member add/remove context but does not explain the 'schemas' parameter or the semantics of op/path/value beyond what the schema already shows.

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+resource+mechanism: 'Partially update a SCIM group via PATCH operations.' This distinguishes it from a full-replacement sibling, though it does not name the siblings (update_group, scim_replace_user-style tools) it differs from.

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?

No guidance on when to choose this over update_group, create_group, or other group siblings, and no prerequisites or exclusions given. Usage is only implied by the verb 'partially update'.

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 it does add real behavior: operations run in order and optimistic locking is available via version headers. However, it also claims 'remove' is supported while the Operations.op enum only permits 'add' and 'replace', a description-vs-schema mismatch, and it says nothing about auth requirements or failure 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?

Three short, front-loaded sentences with no filler; the update mechanism leads and supporting semantics follow. Slightly terse for a mutation tool, but nothing is wasted.

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 mutation tool with no annotations, no output schema and partial schema coverage, the description covers ordering and concurrency but omits auth/permission needs, error behavior, and any detail on the required schemas parameter. It is adequate but leaves an agent with real gaps before calling 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 description coverage is only 33%, so the description should compensate, and it partly does by explaining the add/replace/remove operations and their ordering. It adds nothing about the required 'schemas' or 'user_id' parameters, and its 'remove' mention conflicts with the enum, so it does not fully close the gap.

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 (partially update), resource (SCIM user) and mechanism (PATCH operations). The word 'partially' implicitly separates it from the sibling scim_replace_user, though it never names that sibling or scim_update_group to make the routing 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?

Usage is only implied: an agent can infer PATCH-style partial edits are the intent, but there is no statement of when to choose this over scim_replace_user or update_user, nor any prerequisite about which user IDs are valid or what state the user must be in.

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. It implies a safe read-only search but never states that it is non-mutating, nor how results are ranked, truncated, or what a returned entry contains. It is adequate but leaves meaningful behavioral questions unanswered.

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, front-loaded with the core action, then the use case, then examples. Nothing is redundant and the examples are illustrative rather than filler.

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 no output schema, the description is the only place a return-value contract could be stated, yet it never says what search returns (tool names, descriptions, input schemas) or how many results. For a discovery tool meant to route an agent, the shape of the response is a notable omission.

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 and schema description coverage is 100%, so the schema already documents 'query' fully. The description's example queries ('add user to group', 'list applications') duplicate what the schema description already provides, adding no new syntax or constraint information. 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 ('Search') and resource ('all available Beyond Identity API tools') and makes clear this is a meta-discovery tool, which no sibling tool does. An agent can immediately distinguish it from the concrete CRUD siblings like create_user or list_groups.

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 says 'Use this to discover which tools are available for a task,' which is a clear when-to-use statement, and the example queries reinforce the invocation context. It does not name exclusions or alternatives (e.g. when to skip search and call a known tool directly), so it stops short of 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 provided, the description carries the full behavioral burden. It discloses the destructive replacement behavior and PUT semantics, which is important. It does not mention permissions, error behavior, or returned values, leaving some behavioral gaps 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?

The description is three concise sentences, front-loading the core action and replacement semantics. Every sentence adds useful information without redundancy or filler.

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 no annotations, no output schema, and full schema coverage, the description covers the essential replacement behavior an agent needs. It is largely complete, though it omits permission requirements and post-operation details.

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 baseline would be 3. However, the description adds meaningful parameter-level guidance beyond the schema: it stresses that the complete desired tag set must be provided and that omitted existing tags are removed. The phrase 'key-value metadata' is not reflected in the schema, which only exposes a tag 'name', but this does not seriously hinder use.

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: 'Set tags on a passkey, replacing all existing tags.' It clearly distinguishes the operation from siblings like list_passkey_tags and delete_passkey by specifying both the mutation and its replacement scope.

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 clear usage guidance by explaining PUT semantics: 'provide the complete set of desired tags; any existing tags not included will be removed.' This tells the agent when and how to use the tool. It does not name alternatives or explicit exclusions, so it falls short of a 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?

No annotations are provided, so the description carries the full burden. It does disclose genuinely useful behavior — PATCH semantics with omitted fields unchanged, and that the updated group object is returned — but omits permissions, error/conflict behavior on duplicate names, and any side effects on group membership.

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 tight clauses with zero padding; the mutability and return behavior are front-loaded. The only blemish is the inaccurate 'display_name' label, which slightly undercuts otherwise efficient structure.

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 no output schema the description helpfully states the return value, and it covers the patch semantic, but with no annotations and two sibling update paths it leaves the safety profile, permissions, and sibling differentiation unaddressed for a mutation 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 coverage is 100%, so the nested name/description fields are documented, establishing a baseline of 3. The description adds the PATCH/omitted-fields semantic beyond the schema, but it also names the field 'display_name' while the schema uses 'name', a minor mismatch that could confuse the agent.

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+resource (update a group) and names the mutable attributes, so the agent knows what it does. It does not, however, distinguish itself from the very close sibling scim_update_group, which also updates groups, leaving the reader to guess which endpoint applies.

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 guidance, no prerequisites (e.g. required permissions or name-uniqueness constraints), and crucially no routing against the near-identical scim_update_group or update_user siblings. The reader is left to infer usage entirely.

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 it delivers two substantive behaviors: partial-update semantics (omitted fields preserved) and a specific failure mode (409 on email/username conflict). It omits other behavioral context such as permission requirements or behavior on non-conflict errors, but the disclosed traits are the ones an agent most needs for a mutation call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero filler; the core action and its update semantics are front-loaded, followed immediately by the notable error condition. Every clause 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 two-parameter mutation tool with no annotations and no output schema, the description covers the essential semantics and the key failure mode. It stops short of describing required permissions or the response shape, but no output schema exists to signal those are needed.

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% (user_id plus the nested user object and its four fields are all documented in the schema), so the baseline is 3. The description adds the PATCH nuance that sub-fields may be omitted, but it does not otherwise extend parameter meaning 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 ('Update attributes of a user') and adds the PATCH-semantics qualifier, which implicitly distinguishes it from a full-replace sibling like scim_replace_user. It does not name any sibling explicitly, so the differentiation is inferred 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?

'Uses PATCH semantics — omitted fields unchanged' implies when this tool is appropriate (partial modification rather than replacement), giving usable context. However, it never names the alternative replace/update siblings or states exclusions or prerequisites, leaving usage largely to inference.

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