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

No annotations are present, so the description must carry the full burden of behavioral disclosure. It does not mention side effects, permission requirements, idempotency, error behavior, or what happens if the user is already a member. The description only states the action, providing minimal transparency.

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 concise sentence with no redundant words. It is front-loaded and direct. However, it is slightly under-specified for the dimensions it covers, but concise formatting is not the issue.

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 lacks essential context such as whether the user must already exist, if the operation is idempotent, or what the response indicates. The simple schema does not make up for the missing behavioral and usage 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% (orgId, realm, userId each have descriptions), so the baseline is 3. The description adds no additional meaning beyond the schema, such as the order of parameters or relationships between them. It is adequate but does not compensate further.

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

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

The description clearly states the verb 'add' and the resource 'a user to an organization', which matches the tool name. It distinguishes from sibling tools like remove-organization-member and list-organization-members. However, it lacks any additional scope or context (e.g., required role or realm behavior) that would make it a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., user must exist), exclusions, or recommended usage scenarios. The description simply states the action without contextual cues.

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, and the description only states the assignment action without disclosing behavioral traits such as idempotency, permission requirements, or response behavior. The clientId vs realm role distinction is parameter semantics, not behavioral transparency.

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?

One clear, front-loaded sentence that fully conveys the core purpose and the key conditional. No filler or redundant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple assignment operation, the description covers the core purpose with 4 parameters and no output schema. However, it omits behavioral details like idempotency or expected response status, which an agent might need to know to confirm success.

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 parameters. The description reiterates the clientId/realm role distinction but adds no new meaning beyond the schema; baseline 3 is appropriate.

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

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

The description clearly states the action (assign), the resource (a role to a group), and distinguishes between realm and client roles via the clientId condition. It also differentiates from sibling tools like assign-role-to-user by specifying the target is a group.

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 explicitly explains when to use clientId (for client roles) vs omit it (for realm roles), providing clear context for parameter usage. It does not explicitly mention alternatives or exclusions, but the target audience (a group vs a user) is implicitly clear from the tool name and sibling set.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It does add context about the dual realm/client role behavior, but it does not mention permissions, idempotency, what happens if the role already exists, or the response format. This is a clear but basic mutation tool; more transparency would be valuable.

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 sentence of about 15 words, front-loaded with the action and resource. It is optimally concise with no filler or redundant detail.

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 4-parameter assignment tool with no output schema, the description covers the essential behavior and the one conditional parameter (clientId). It could mention response details or error conditions, but given the low complexity, it 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 per the rubric the baseline is 3. The description adds no new parameter semantics beyond what the schema already provides, and the clientId explanation mirrors the schema description.

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 clearly states the action: 'Assign a realm role, or a client role when clientId is given, to a user'. It uses a specific verb ('assign') and identifies the resource (role) and recipient (user). It also distinguishes between realm and client roles, which differentiates it from sibling tools like remove-role-from-user or assign-role-to-group.

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 provides clear usage context by specifying that clientId is used for client roles, otherwise a realm role is assigned. However, it does not explicitly mention alternatives or when not to use this tool, so it stops 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 must fully disclose behavioral traits. 'Clear' implies a destructive action, but the description fails to state whether the action is irreversible, the exact scope (all events vs. filtered), permission requirements, or side effects. For a destructive operation, this is a significant transparency gap.

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

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

The description is extremely concise at three words, with no filler or unnecessary detail. It is front-loaded and easily parsed. However, the brevity contributes to under-specification, but conciseness as a dimension is well-handled.

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 absence of an output schema and annotations, the description is the only source of context. It fails to explain what 'clear' operationally entails—whether it deletes all events, is permanent, or is scoped to the realm. This is inadequate for a destructive tool, even with low parameter complexity.

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 input schema has 100% coverage for the single required parameter 'realm', described as 'Realm name'. The description adds no additional meaning beyond the schema, so the baseline score 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 'Clear event logs' uses a specific verb ('Clear') and resource ('event logs'), making the primary purpose unambiguous. It distinguishes from sibling 'list-events' and other read operations, though it lacks an explicit scope (e.g., 'in the realm') beyond what the schema implies.

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 provides no guidance on when to use this tool versus alternatives such as 'list-events' or other deletion tools. There is no mention of when it is appropriate, what prerequisites exist, or when another tool would be preferred.

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 for behavioral disclosure. It only says 'Create a child group' without mentioning permissions, parent group validation, idempotency, or side effects. This is a significant gap 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 a single, focused sentence with no wasted words. It clearly states the action and resource without any redundant elaboration.

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, no annotations, and a one-line description, the tool lacks essential context for an agent: no return format, no side effects, no edge cases (e.g., duplicate names, invalid parent group), and no guidance on handling the nested attributes parameter. This makes it incomplete for a reliable call.

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 input schema has 100% coverage with descriptive parameter names and summaries. The tool description adds no extra meaning beyond the schema, 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 clearly identifies the action (create) and the resource (child group/subgroup), and the qualifier 'child' distinguishes it from the sibling 'create-group'. It could be more explicit about the parentGroupId requirement, but the core 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?

No explicit guidance is given on when to use this tool vs. alternatives like create-group. The word 'child' implies subgroup creation, but there is no mention of prerequisites, exclusions, or conditions that would help an agent choose this tool over others.

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 full responsibility for disclosing behavioral traits. It only states the action ('Register') without mentioning permissions, idempotency, side effects, or error behavior. For a mutation tool, this lack of detail leaves significant 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?

The description is a single, front-loaded sentence that states the essential purpose without extraneous words. It is concise and well-structured, making it easy to parse.

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?

Despite a rich schema (7 params), there is no output schema and no annotations. The description only covers the basic creation action, omitting details like prerequisites, idempotency, return values, or potential errors. For a create operation with moderate complexity, this is inadequate for full contextual completeness.

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

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

The input schema provides descriptions for all 7 parameters, giving 100% coverage. The tool description adds no additional parameter-level context beyond 'client/application in a realm', so it neither compensates for nor detracts from the schema's already sufficient parameter documentation.

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 the specific verb 'Register' and identifies the resource as 'client/application in a realm', clearly distinguishing it from siblings like update-client, delete-client, and list-clients. It unambiguously states the tool's function.

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 the tool is for creating clients, but it does not explicitly state when to use it vs. alternatives such as update-client or list-clients. No exclusions or alternative tool references are provided, so guidance is only implied by the verb 'Register'.

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 present, the description carries the full burden of disclosing behavior. It only states that it creates a client scope and hints at its role in token scopes, but does not mention side effects, authorization requirements, idempotency, or error behavior (e.g., duplicate name). This is a significant gap for a create 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?

The description is a single sentence and front-loaded with the core action. The parenthetical 'CRITICAL for managing token scopes' adds a bit of context but could be seen as slightly dramatic; still, it is concise and no words are wasted. It earns a 4 for efficiency.

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 create operation with 5 parameters (2 required), no output schema, and no annotations, the description is under-specified. It gives no information about return values, prerequisites (e.g., realm must exist), or special constraints. An agent would need to infer too much about how to correctly invoke 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 100% (all 5 parameters have descriptions). The description text adds no additional meaning beyond the schema, so the baseline of 3 applies. It does not clarify required fields, uniqueness constraints, or format expectations beyond what the schema already provides.

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 clearly states the tool's action: 'Create a new client scope'. The verb 'create' and resource 'client scope' are specific, and it distinguishes itself from sibling tools like update-client-scope and delete-client-scope by focusing on creation. The parenthetical adds relevant context about token scopes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It does not mention that this is for new scopes, that update-client-scope should be used for modifications, or any prerequisites such as an existing realm. The sibling list exists but the description does not reference it.

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 of disclosing side effects. It only states 'create' without revealing whether the operation is idempotent, whether it overwrites existing mappers, required permissions, or any consequences. This is a minimal disclosure 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 a single sentence, which is concise. However, it does not earn its place by adding valuable information beyond the tool name; it simply rephrases it. The structure is not problematic, but the content is so minimal that it borders on under-specification rather than effective conciseness.

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 tool has 6 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain the protocol mapper concept, the purpose of the 'config' nested object, or any return value or errors. An agent would struggle to use this tool correctly without additional context from documentation or examples.

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 input schema has 100% description coverage for all parameters, each with a short description. The tool description adds no additional meaning beyond the schema, so the baseline of 3 applies. The 'config' object is mentioned in the schema but not elaborated, and the description does not compensate.

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 'Create a protocol mapper for a client scope' restates the tool name in sentence form, providing little additional clarity. It does specify the resource (client scope protocol mapper) but does not distinguish it from the similar create-protocol-mapper tool or explain what a protocol mapper is. The verb and resource are clear, but the description is essentially a tautology of the tool name.

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 alternatives like create-protocol-mapper (for clients) or update-client-scope-protocol-mapper. The description does not mention any conditions or exclusions. Without context, the agent cannot determine the appropriate scenario for this tool compared to siblings.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It merely states the action and a synonym for composite; it does not mention permissions, side effects, idempotency, prerequisites, or what happens to existing roles. There is no added context beyond the tool's name.

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 sentence with no wasted words, making it concise and front-loaded. However, it is arguably under-specified, so it loses a point for not balancing brevity with necessary detail.

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 moderately complex tool creating role hierarchies, the description and schema provide minimal context. There is no explanation of the relationship between roleId and roles, whether roles must already exist, or what the resulting composite role structure looks like. No output schema or annotations compensate.

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 baseline is 3. The description adds no parameter-specific meaning; 'role hierarchies' is a general concept but does not clarify how 'roleId' and 'roles' interact.

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: 'Create composite roles', and adds a clarifying parenthetical 'role hierarchies' that distinguishes it from simple role creation. However, it doesn't explicitly differentiate from sibling tools like 'create-role' or point to alternatives.

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 alternatives such as 'create-role' or 'update-role'. The phrase 'role hierarchies' implies a use case but it is not explicit about when to choose this over related role tools.

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, and the description offers no additional behavioral context. It doesn't disclose permission requirements, the significance of 'parentId' (e.g., whether it creates a subgroup), or any side effects beyond the creation itself.

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, direct sentence that immediately conveys the purpose without unnecessary elaboration. It earns its place by being clear and to the 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?

The tool has a simple create operation and the schema covers parameters fully. However, the description doesn't explain the optional 'parentId' relationship to sibling tool 'create-child-group', nor what the tool returns, making it only minimally complete for an agent to use 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 input schema already provides descriptions for all 3 parameters, covering 100% of them. The description adds no extra semantics or usage tips beyond what the schema states, which is acceptable given the high coverage.

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

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

The description 'Create user groups' clearly states the action (create) and the resource (user groups), making the tool's function obvious. However, it doesn't differentiate from the sibling tool 'create-child-group', leaving ambiguity about whether this handles top-level groups only.

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 like 'create-child-group' or 'create-role'. The description lacks any exclusions or contextual hints for choosing this tool.

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

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

With no annotations, the description carries the full burden but only says 'create' with no detail on side effects, prerequisites, default values, error handling, or idempotency. It does not mention whether a realm must exist or what happens on duplicate aliases, leaving significant behavioral ambiguity.

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, front-loaded sentence with no filler. Every word adds context, making it appropriately concise and well-structured.

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 tool with 11 parameters, no annotations, and no output schema, this one-sentence description is inadequate. It omits return format, required preconditions, and usage scenarios, leaving the agent without enough context to use the tool correctly in a complex operation.

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

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

The input schema has 100% description coverage for all 11 parameters, so the schema does the heavy lifting. The description adds general SSO context but does not enrich parameter meanings beyond what is already in the schema, 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?

The description clearly states the action (create) and resource (identity provider) with an SSO integration scope. However, it does not distinguish from the sibling tool import-identity-provider-from-url, which also creates an identity provider but via URL import.

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 like import-identity-provider-from-url or when to prefer updating an existing provider. There are no mentions of prerequisites, exclusions, or contextual triggers, leaving the agent without selection support.

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 full responsibility for behavioral disclosure. It only states a creation action, but does not reveal side effects, required permissions, what happens if the mapper exists, whether the operation is idempotent, or what the 'config' object should contain. This is insufficient for a mutating 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 a single concise sentence that immediately conveys the core purpose. It is appropriately sized, though it could be expanded with a second sentence to offer practical guidance without losing conciseness.

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?

The description lacks essential context for a create operation. It does not reference the list-identity-provider-mapper-types sibling for valid mapper types, does not explain the config object structure, and provides no information about the response or error conditions. With no output schema and no annotations, the description is too thin to fully support an agent.

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 documents all parameters adequately. The description adds only a small semantic hint ('external user mapping') but does not elaborate on the 'config' object or the possible values for 'identityProviderMapper'. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description uses a clear verb ('Create') and specific resource ('mapper for identity provider'), with a parenthetical explaining it's for external user mapping. It clearly distinguishes from sibling tools like update-identity-provider-mapper and delete-identity-provider-mapper, though it could be slightly more explicit that it creates a new mapper.

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. There is no mention of the relationship to list-identity-provider-mapper-types, which would be useful for selecting the correct mapper type, nor any prerequisites like needing an existing identity provider alias.

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

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

With no annotations, the description must disclose behavioral traits, but it only states the basic action. It does not mention side effects, return values, required parent resources (e.g., an existing realm), idempotency, or permission requirements. This is a significant gap 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 concise at one sentence, though the 'CRITICAL for organization management' phrase is not essential. It remains front-loaded and does not contain wasteful content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters, nested objects, and no output schema, the description is under-specified. It does not explain success responses, error conditions, or preconditions, leaving the agent without adequate context 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?

The schema covers 100% of parameters with individual descriptions. The tool description adds no extra meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states 'Create a new organization' with a specific verb and resource, distinguishing it from sibling operations like update, delete, or list. The parenthetical emphasizing criticality adds urgency but does not obscure purpose.

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 explicit guidance is provided for when to use this tool over alternatives. Usage is implied by the name and the create/update/delete pattern among sibling organization tools, but no prerequisites, exclusions, or conditions are mentioned.

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 of behavioral disclosure. It only states the action and a vague 'CRITICAL' note, but does not disclose side effects (e.g., token impact), permissions required, or whether existing mappers are overwritten. This is insufficient for a creation 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?

The description is a single sentence with a parenthetical emphasis note. It is concise and front-loaded with the essential action, earning its place without clutter.

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 complexity (6 parameters, nested config object, no output schema), the description is incomplete. It does not hint at return values, the expected structure of 'config', or any prerequisites for the protocol mapper. The 'CRITICAL' note is vague and does not compensate for these 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 coverage is 100% (each parameter has a description), so the baseline is 3. The description does not add extra semantic detail beyond the schema; config is only named as 'Protocol mapper configuration' without further elaboration, but the schema itself covers the basic meaning.

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

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

The description clearly states the action (create) and resource (protocol mapper for a client), using a specific verb and object. It distinguishes from related sibling tools like create-client-scope-protocol-mapper by specifying 'for a client'.

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 'for a client' provides clear context that this is the client-level mapper creation tool, distinguishing it from client-scope mappers. The 'CRITICAL for JWT organization claims' hint gives a use case, though no explicit alternatives or exclusions are listed.

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 only says 'create' and does not disclose side effects, uniqueness constraints, permission requirements, or error behavior if the realm already exists. This is insufficient 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 a single, short sentence with no redundant words. It is concise, though it sacrifices some specificity for brevity.

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 annotations and no output schema, the description does not explain return values, failure conditions, or prerequisites for creating a realm. For a create operation, this is a significant gap beyond the bare action.

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 input schema fully documents all three parameters with descriptions (100% coverage), so the description adds little beyond labeling them as 'configurable settings'. The baseline of 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the action ('Create') and resource ('realm'), and 'new' distinguishes it from update-realm/delete-realm. However, 'configurable settings' is vague and does not specify which settings, though the core 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?

Usage is implied by the word 'new' – use when creating a realm. There is no explicit mention of when not to use or alternatives, but sibling names like update-realm and delete-realm provide 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?

No annotations, so description carries the full burden. It mentions realm/client level scope but does not disclose permissions, duplicate behavior, idempotency, or return results. For a mutation tool, this is insufficient.

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?

Single sentence, no fluff, directly states purpose. Perfectly concise and front-loaded.

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?

Adequate for a simple create tool with well-documented schema, but lacks return value details and side-effect information (e.g., duplicate roles, permissions). Given no output schema and no annotations, more would be expected for full completeness.

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

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

Schema has 100% description coverage, with all parameters meaningfully described (realm, clientId, roleName, description). The description adds no new semantic value beyond restating 'realm or client level', which is already in the schema.

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

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

Clearly states it creates roles, with explicit scope at realm or client level. The verb 'Create' and resource 'roles' are specific, and the realm/client distinction distinguishes it from role management tools like update-role or delete-role.

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?

Implied usage for creating simple roles, but no explicit guidance on when to choose this over create-composite-role or how to scope realm vs client. Sibling tools include create-composite-role, yet no differentiation is provided.

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 burden for behavioral disclosure. It only states the action and scope, but doesn't mention required permissions, potential conflicts (e.g., duplicate username), or what happens on error. This is insufficient 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 a single, focused sentence with no filler words, making it easy to parse quickly. It avoids redundancy and is appropriately front-loaded.

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?

The description is too terse for a 5-parameter create operation with no annotations or output schema. It lacks critical context like whether realm must exist, whether duplicate usernames are rejected, or what the response contains.

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 schema already covers all 5 parameters with short descriptions, so the baseline is 3. The description adds no additional parameter semantics—it merely mentions 'specific realm' which maps directly to the realm parameter.

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 ('Create') and resource ('user') plus a scope ('in a specific realm'), clearly distinguishing it from siblings like update-user, delete-user, and list-users. It leaves no ambiguity about what the tool does.

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 for creating a user within a realm but doesn't explicitly state when to use it instead of related tools, nor does it mention prerequisites like the realm needing to exist. The context is clear but not fully developed.

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 of behavioral disclosure. It states the action but does not communicate that the deletion is permanent, destructive, or any potential side effects on associated data. This is a significant gap for a destructive 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?

The description is a single, efficient sentence with no wasted words. It directly conveys the core purpose without fluff, earning 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?

Given the tool is a simple delete operation with 2 parameters and no output schema, the description is minimally adequate but lacks critical behavioral context. With no annotations, it should disclose the destructive nature, reversibility, or error handling, but it does not. This leaves the agent under-informed for a potentially impactful operation.

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

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

Schema description coverage is 100%, so both parameters (realm and clientId) are already self-explanatory. The description 'from a realm' hints at the realm parameter but adds no new meaning beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description 'Remove a client from a realm' uses a specific verb ('Remove') and resource ('client'), clearly distinguishing it from sibling tools that delete other entities like users or roles. It fully states the action and 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?

The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The context signals show many sibling delete tools, but no comparison or explicit usage context 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?

With no annotations, the description must disclose behavioral traits. It only says 'Delete', implying destructiveness, but does not mention if the deletion is permanent, cascades to related entities, or requires special permissions. No side effects or error behavior 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?

The description is a single sentence with no wasted words, but it is under-specified. While concise, it lacks substantive details needed to understand the tool's behavior, making it minimally acceptable in 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?

For a simple delete tool with two well-documented parameters, the description is adequate but not complete. It provides no context about side effects, prerequisites, or response expectations, and with no annotations or output schema, the agent is missing important information for a destructive operation.

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

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

The input schema fully documents both parameters (realm, clientScopeId) with 100% coverage. The description adds no additional semantic content about the parameters, so it meets the baseline for high schema coverage.

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

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

The description 'Delete a client scope' is a direct restatement of the tool name, providing no additional nuance or distinction beyond the verb+resource. It does not add detail about what a client scope is or how this deletion differs from deleting other resources.

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 information is provided about when to use this tool, prerequisites, or alternative approaches. The description simply states the action without any context about use cases, permanence, or safer 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action 'delete' without mentioning permanence, required permissions, or potential side effects. This is insufficient for a destructive 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?

The description is a single concise sentence: 'Delete a protocol mapper from a client scope'. It is front-loaded, contains no unnecessary words, and is appropriately sized for the simple operation it describes.

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 delete tool with no annotations and no output schema, the description is too minimal. It fails to provide crucial context about irreversibility, prerequisites (e.g., the mapper must exist), or any safety warnings. The simple operation still needs more behavioral context than one sentence.

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 input schema has 100% description coverage, with each of the three parameters (realm, clientScopeId, mapperId) having a brief explanation. The description adds no additional parameter semantics beyond what the schema already provides, aligning with the baseline for high coverage.

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

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

The description is specific: 'Delete a protocol mapper from a client scope' clearly states the verb (delete) and resource (protocol mapper) with the scope (client scope), distinguishing it from sibling tools like delete-protocol-mapper or delete-client-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?

The description implies usage by specifying the exact resource and scope, but it does not explicitly contrast with alternatives such as delete-protocol-mapper or explain when this tool should be preferred. No when-not-to-use guidance is provided.

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 must disclose behavioral traits. It only says 'Delete composite roles from a role' and does not clarify whether this destroys the composite role entities or just their associations, nor does it mention permissions, reversibility, or side effects. The ambiguity around what is actually deleted is a significant transparency gap.

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

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

The description is a single, concise sentence with no filler words. Every word contributes to the core meaning, making it highly efficient and front-loaded.

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?

The tool has no output schema and no annotations, and the description is extremely brief. It lacks essential context such as prerequisites (e.g., the role must exist), how the 'roles' array should be structured, and what the tool returns. The presence of many sibling role-management tools increases the need for clearer contextual guidance, which is missing.

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

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

Schema coverage is 100% (all parameters have descriptions), so the baseline is 3. The description does not elaborate on parameter meaning beyond the schema. The schema's 'Array of roles to remove' is ambiguous, but the description's 'from a role' adds a small clarifier that the removal is scoped to a role. No additional details about role IDs or names are provided.

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 'Delete composite roles from a role' clearly identifies the action (delete) and the resource (composite roles), and the phrase 'from a role' differentiates it from deleting the role itself. However, it does not explicitly distinguish it from sibling tools like 'delete-role' or 'delete-role-by-id', which could cause confusion in edge cases.

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 provides no guidance on when to use this tool versus alternatives. It does not mention that this is specifically for removing composite role assignments from a role, nor does it advise using 'delete-role' for full role deletion. Sibling tools exist, but no exclusions or recommended contexts are given.

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 must disclose behavioral traits. It only says 'Delete groups' with no mention of side effects, required permissions, irreversibility, or impact on related entities like group members, sub-groups, or role mappings. This is a severe gap for a destructive 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?

The description is extremely short, but it is under-specified rather than appropriately concise. While there is no fluff, the lack of necessary context prevents it from earning full marks for 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?

The tool has two parameters and no output schema, but the description does not explain deletion behavior such as cascade effects, authorization requirements, or error conditions. The description is inadequate for an agent to fully understand the tool's impact.

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 parameters realm and groupId are already documented. The description adds no additional meaning beyond the schema, which is the baseline expectation for full coverage.

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

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

The description 'Delete groups' is essentially a restatement of the tool name 'delete-group', adding no new information. It does specify a verb and resource, but fails to differentiate from sibling tools beyond what the name already implies.

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 alternatives, no prerequisites, and no context about typical use cases. It simply states the action without any situational framing.

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 of behavioral disclosure. It only says 'Delete an identity provider' but does not mention any side effects, prerequisites, reversibility, or impact on associated mappers. This is a significant gap for a destructive 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?

The description is a single sentence, extremely brief and front-loaded. However, it repeats the tool name without adding value, so it doesn't fully 'earn its place,' though it remains concise.

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 tool with two parameters and no output schema, the description might be minimally sufficient, but because it is a delete operation with no mention of consequences or related resources (e.g., mappers), it feels incomplete. The tool would benefit from noting impact or prerequisite steps.

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% with descriptions for both parameters ('Identity provider alias' and 'Realm name'). The description adds no extra meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Delete') and the resource ('an identity provider'), making the purpose unambiguous. It does not explicitly differentiate from sibling tools like 'delete-identity-provider-mapper', but the identity provider vs. mapper distinction is implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool over alternatives, or any context about when deletion is appropriate. It simply restates the operation without offering usage scenarios 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?

With no annotations, the description carries full responsibility. It only states the deletion action without disclosing consequences, reversibility, required permissions, or side effects—a significant gap for 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?

The description is a single concise sentence with zero waste. However, it is essentially a restatement of the tool name and adds little value beyond the name itself, making it efficient but minimal.

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 deletion tool with no annotations and no output schema, the description lacks behavioral context such as idempotency, side effects, prerequisites, or post-conditions. This makes it incomplete for an agent to fully understand the impact.

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 input schema already documents all three parameters (realm, alias, mapperId) with descriptions, providing 100% coverage. The description adds no extra parameter meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete an identity provider mapper' with a specific verb and resource, making the purpose unambiguous. It distinguishes from sibling tools like update/get/list by the delete action, though it lacks additional scoping details.

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 about when to use this tool versus alternatives. There is no mention of prerequisites, alternatives, or conditions under which deletion should occur.

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 available, the description carries the full burden of behavioral disclosure. It only says 'Delete an organization' without indicating irreversibility, cascading effects on members or associated data, or permission requirements. The destructive nature is implied but not elaborated.

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, front-loaded sentence with no redundancy or fluff. It is concise, though minimal; the lack of elaboration is more a completeness issue than a conciseness issue.

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 operation with no annotations and no output schema, the description should provide more context about consequences, side effects, or scope of deletion. The current description is adequate only for a trivial understanding of the tool's action.

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 both parameters (orgId and realm) already have clear descriptions. The tool description adds no further semantic detail, but the schema adequately documents the parameters.

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

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

The description clearly states the verb (delete) and resource (organization), which directly indicates the tool's function. It distinguishes from sibling tools that target other resources like realms, users, or clients.

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 merely states the action without mentioning prerequisites, exclusions, or situational context that would help an agent decide to invoke this vs. other delete tools.

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 burden of disclosing behavioral traits. It clearly states the destructive action and what is deleted, but lacks details on reversibility or required permissions. 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?

The description is a single, focused sentence with no wasted words, effectively front-loading the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple delete operation with three straightforward parameters, the description is mostly complete. The only gap is the lack of explicit differentiation from similar siblings, but the client-level context provides sufficient clarity.

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 input schema already describes all three parameters with complete coverage (100%), and the description adds no additional parameter meaning 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?

The description uses a specific verb 'Delete' and clearly identifies the resource as 'a protocol mapper from a client', effectively differentiating it from sibling tools like delete-client-scope-protocol-mapper.

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 'from a client' provides clear context that this tool is for client-level protocol mappers, implying when to use it. However, it does not explicitly mention alternatives or exclusions, such as not using it for client-scope protocol mappers.

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 exist, so the description carries the full burden. It fails to disclose that deletion is destructive, irreversible, may cascade to related resources, or require special permissions. It adds no behavioral information beyond the tool's name.

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 sentence with no filler or redundancies. It is efficiently concise for a simple delete operation.

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 operation with no annotations and no output schema, the description lacks essential context about irreversibility, preconditions, or side effects. It is too sparse to fully inform an agent about the tool's implications.

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% with 'realm' described as 'Realm name'. The description adds no additional parameter context, but the schema already fully documents the only param, 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?

Description clearly states 'Delete an existing realm' with a specific verb and resource, directly distinguishing it from sibling deleters like delete-user and delete-client. The purpose is unambiguous and complete.

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 vs alternatives, prerequisites, or consequences. The bare statement 'Delete an existing realm' gives no context for decision-making beyond the obvious.

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 of behavioral disclosure, but it reveals nothing beyond the name. It does not mention side effects (e.g., cascading removal from composites), reversibility, or permissions, and the plural 'roles' is misleading given a singular roleName.

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 under-specified, consisting of a two-word phrase that restates the tool name. While short, it lacks any structural detail that would help an agent understand scope or usage, making it minimally viable at best.

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 delete tool with an optional clientId and no output schema or annotations, the description is incomplete. It fails to clarify the distinction between deleting realm roles and client roles, or what happens to dependent entities, leaving significant gaps for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no meaning beyond the schema fields; the optional clientId and its role in targeting client roles remain unexplained in the description.

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 'Delete roles' is essentially a restatement of the tool name 'delete-role' with no added specificity, failing to distinguish it from sibling tools like delete-role-by-id or delete-composite-roles. It does not mention whether it handles realm roles, client roles, or both.

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 usage guidance is provided. The description gives no indication of when to use this tool versus other delete tools, nor does it explain the optional clientId parameter for client roles or any prerequisites.

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 full responsibility for behavioral disclosure. It only states the action without explaining cascading effects, reversibility, required permissions, or return behavior. This is a significant gap for a destructive 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?

The description is a single concise phrase with no unnecessary words. It is front-loaded and appropriately sized for a simple delete operation.

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 operation with no output schema and no annotations, the description is too minimal. It fails to mention consequences, necessary permissions, or whether associations with users/groups are removed, which are important for correct tool selection and 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?

The input schema covers 100% of parameters, with descriptions for both 'realm' and 'roleId'. The description adds no additional semantic meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description 'Delete role by ID' uses a clear verb 'delete' and specifies the resource (role) and identifier (by ID). It clearly distinguishes from sibling tools such as 'delete-role' (likely by name) and 'delete-composite-roles' (composite roles).

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 provides no guidance on when to use this tool versus alternatives like 'delete-role' or 'delete-composite-roles'. There is no mention of context, exclusions, or preferred scenarios.

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 of behavioral disclosure. It only states 'Delete a user', which is inherently destructive, but does not mention permanence, side effects (e.g., removing user sessions or cascading deletions), permission prerequisites, or reversibility. This is a significant gap for a mutation tool with no annotation support.

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, front-loaded sentence that conveys the essential action and scope without any superfluous words. It is well-suited for quick parsing by an agent.

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 simplicity of the tool (two required string parameters, no output schema), the description is minimally adequate. However, it lacks behavioral context such as whether the deletion is permanent, what happens to related entities, or any prerequisites, which would be helpful for complete understanding. It is not incomplete enough to warrant a 2, but not rich enough for a 4.

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 input schema covers 100% of the parameters with descriptions ('Realm name' and 'User ID'). The tool description does not add any additional semantic meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Delete') and the resource ('a user from a specific realm'), making the tool's purpose distinct from sibling tools like update-user, get-user, or delete-realm. The addition of 'from a specific realm' provides contextual scoping that differentiates it from other deletion 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?

The description implies usage for deleting a user in a realm, but it does not explicitly state when to use this tool versus alternatives (e.g., update-user to modify or logout-user to end sessions). No exclusions or alternative recommendations are provided, so the guidance is implied 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?

No annotations are provided, so the description carries the burden. It discloses the dual behavior (realm vs client role) which is useful, but does not state anything about read-only safety, pagination behavior, or error conditions. Given the tool is explicitly a 'find' operation, it is implicitly read-only, but this is not confirmed.

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?

A single, front-loaded sentence that conveys the purpose and key condition. No fluff or redundant wording, making it highly efficient and easy to parse.

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 5-parameter tool with no output schema, the description covers the core functionality but omits expected return details (e.g., user fields, pagination format). However, the parameters themselves are fully described in the schema, and the description clarifies the primary invocation pattern. It is minimally adequate but leaves uncertainty about the response.

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 does not add meaning beyond the schema's clientId description, which already explains the distinction between realm and client roles. The parameters are adequately documented individually.

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?

Description states a specific verb ('Find') and resource ('users') with a clear scope ('with a realm role, or with a client role when clientId is given'). This distinguishes it from broader tools like list-users or search-users by focusing on role-based lookup.

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 provides a conditional usage rule: use clientId for client roles, omit for realm roles. This gives clear context for when to use the tool, though it does not explicitly mention alternative tools or exclusions. The indication 'when clientId is given' is a practical guideline.

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 of behavioral disclosure. 'Get details' implies a read-only operation but does not explicitly state non-mutating behavior, required permissions, or what 'details' entails. It lacks context about return format or error semantics.

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

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

The description is a single sentence that is perfectly concise and front-loaded with the verb and resource. Every word contributes to the meaning, with no unnecessary elaboration.

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 getter with only two parameters and no output schema, the description is minimally adequate. However, it lacks usage guidance and behavioral context, which would be helpful even for a straightforward read operation, leaving some gaps for the agent.

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 both parameters (realm and clientScopeId) with clear descriptions. The description adds no extra meaning beyond the schema, so the baseline of 3 applies; it neither compensates nor detracts.

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 clearly states the action ('Get') and the resource ('client scope'), specifying it's for a 'specific' one, which distinguishes it from list, create, update, and delete operations. It could be more explicit that it fetches by ID, but the schema clarifies the identifier parameter.

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 like list-client-scopes. It doesn't state prerequisites, exclusions, or typical use cases, leaving the agent to infer context from the tool 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?

With no annotations provided, the description must carry the full burden of behavioral disclosure. It only restates the action (get) and provides no information about pagination, search behavior, authorization requirements, or whether results are filtered by realm or role scope.

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, concise sentence without redundancy. It front-loads the verb and resource, but its brevity sacrifices necessary detail for completeness.

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?

The tool has no output schema, no annotations, and only a one-sentence description. It fails to explain return format, pagination behavior, search semantics, or how this differs from related role tools. This is highly inadequate for a tool with 5 parameters and no structured output metadata.

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 all five parameters, so the individual parameter descriptions already define their meanings. The tool description adds no extra semantic value beyond what is already in the schema, warranting the baseline score.

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 clearly specifies the verb 'Get' and the resource 'composite roles' scoped 'for a role'. It is distinguishable from sibling tools like 'delete-composite-roles' and 'create-composite-role', though it could be more explicit about what 'composite' means in this context.

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 provides no guidance on when to use this tool versus alternatives such as 'get-role-by-id' or 'list-composite-group-roles'. There is no mention of prerequisites, typical scenarios, 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?

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Get', implying a read operation, but fails to mention return format, authentication needs, side effects, or error behavior. This is minimal and inadequate.

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 extremely short but under-specified. It merely rephrases the tool name without adding any new information, so the sentence fails to earn its place as a useful description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and no annotations, the description should explain what attributes are returned or any relevant context. It does not, leaving agents to rely solely on the sparse schema descriptions. This is incomplete for a complete understanding.

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 input schema has 100% description coverage for both parameters (realm and groupId), so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already provides.

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 'Get group attributes' is a direct restatement of the tool name 'get-group-attributes'. It identifies the action and resource but adds no scope, detail, or differentiation from sibling tools like get-user-attributes or get-group-roles, making it a tautology.

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 such as set-group-attributes, get-user-attributes, or get-group-roles. The description lacks any context for tool selection.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds a useful detail by specifying the return shape, but it does not mention permissions, whether the roles returned are direct or inherited/composite, or any error conditions. The description adds some transparency but lacks depth.

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 concise sentence that front-loads the action ('Get roles assigned to a group') and includes the return structure. There is no redundant or extraneous wording, making it highly efficient.

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 tool with two well-described parameters and no output schema, the description is largely complete. It explains the purpose and the response shape. However, it could be more complete by clarifying whether the roles are direct assignments only or include composite/inherited roles, and by mentioning any required permissions. Still, it is adequate for most use cases.

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 input schema fully describes both parameters ('realm' and 'groupId') with 100% coverage. The description does not add any semantic meaning beyond the schema; it merely restates the concept of getting roles for a group. Since the schema covers the parameters, 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 'Get' and clearly identifies the resource as 'roles assigned to a group'. It also specifies the return format as '{ realmMappings, clientMappings }', which distinguishes it from sibling tools like 'get-user-roles' or 'list-available-group-roles'. This is a clear and specific purpose.

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 makes it clear what the tool does, but it doesn't explicitly state when to use it over alternatives like 'list-available-group-roles' or 'list-composite-group-roles'. The usage context is implied through the verb and resource, but there is no explicit exclusion or comparison, so the guidance is only implicit.

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 burden of behavioral disclosure. It only states 'Get details' and does not mention response format, error handling (e.g., not found), or any prerequisites, leaving the agent without critical behavioral context beyond the obvious read-only nature of 'get'.

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, concise sentence with no unnecessary words or repetition. It efficiently conveys the core purpose without 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 simple get operation with two schema-documented parameters, the description is minimally adequate. However, the absence of an output schema and any detail on return values or error behavior leaves gaps in what the agent can expect from invoking the 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?

The input schema already provides 100% coverage for both parameters with descriptions ('Identity provider alias' and 'Realm name'). The description adds no additional parameter semantics beyond what the schema already contains, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'details of a specific identity provider', which distinguishes it from sibling list, create, update, and delete tools. The specificity of 'details' and 'specific' makes the purpose 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?

No explicit when-to-use guidance or alternative tools are mentioned. However, the required parameters (realm and alias) imply this is for targeted lookups, making the usage context reasonably clear by 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 burden. 'Get' implies a read-only operation with no side effects, which is minimal behavioral disclosure. It does not mention error handling, permissions, or return format.

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, concise sentence ('Get details of a specific identity provider mapper') that conveys the essential purpose without waste. It is appropriately sized for a simple getter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple getter with fully documented schema parameters, the description is sufficient. It doesn't explain what 'details' includes, but no output schema exists and the tool is straightforward. Slightly more context about the returned data would improve completeness, but it's not critical.

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 each parameter (realm, alias, mapperId) having a clear description. The tool description adds no parameter-specific information, so it relies on the schema, earning the baseline score 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 uses a specific verb 'Get' and resource 'details of a specific identity provider mapper', clearly distinguishing from sibling list/create/update/delete mapper tools. The word 'specific' differentiates it from list-identity-provider-mappers.

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 explicit usage guidance or alternatives are given. Usage is implied by the name and description: use when you need details of one specific mapper. It does not mention when not to use it or point to list/get 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?

No annotations are provided, so the description carries the full burden. It only states 'Get details' without disclosing behavior such as read-only nature, output format, required permissions, or error handling. This is a significant gap for a tool with no structured transparency signals.

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 concise sentence with no redundant information. It is front-loaded and every word contributes meaning.

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 2-parameter get tool with no output schema, the description is adequate: the purpose is clear and distinguishes from siblings. However, it lacks explicit usage guidance and behavioral details, which would make it more 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?

The input schema covers both parameters with descriptions (orgId and realm), so coverage is 100%. The description adds no additional parameter meaning beyond what the schema already provides, which aligns with the baseline score of 3 for high schema coverage.

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

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

The description uses the specific verb 'Get' and the resource 'organization' with the qualifier 'specific', clearly indicating a single-entity retrieval. This distinguishes it from siblings like 'list-organizations' (list all) and create/update/delete operations.

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 for retrieving details of one organization, but does not explicitly state when to use it versus alternatives like 'list-organizations' or provide contextual guidance. The verb 'get' vs 'list' gives an implied usage, but no clear when-to-use or exclusions are provided.

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

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

With no annotations, the description must disclose side effects and safety. The verb 'Retrieve' implies a read-only operation, which is transparent about non-destructive behavior. However, it does not mention error handling, permissions, or response format, leaving some ambiguity.

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 sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (one parameter, no output schema), the description is adequate but minimal. It says 'detailed settings' but does not enumerate what those settings include or hint at return values. For a simple get tool, this is sufficient but not comprehensive.

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 input schema already provides full coverage for the single parameter 'realm' with description 'Realm name'. The tool description does not add any extra parameter semantics beyond what the schema states, so it meets the baseline but provides no additional value.

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 the specific verb 'Retrieve' and identifies the resource as 'detailed settings of a realm', which clearly distinguishes it from sibling tools like list-realms (listing all realms) and update-realm (modifying settings). It is concise and 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 usage for fetching a specific realm's settings but does not explicitly state when to use it versus alternatives like list-realms or update-realm. There is no mention of exclusions or conditions, so it relies on the tool name and 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 must carry the full burden of behavioral disclosure. It only says 'Get role details' which implies read-only, but does not mention required permissions, realm-dependence, error handling, or response format. This is insufficient for a tool with no structured metadata.

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, concise sentence with no redundant wording. It is front-loaded and communicates the essential purpose without unnecessary detail.

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 absence of annotations and output schema, the description is too minimal to be complete. It fails to explain how realm and roleId interact, what 'role details' includes, or any return behavior, making it hard for an agent to invoke correctly without additional assumptions.

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 input schema fully describes both parameters ('realm' and 'roleId') with 100% coverage. The description adds no extra meaning beyond the schema, so 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 ('Get') and resource ('role details') with identifier ('by ID'), clearly conveying the tool's function. It distinguishes from list-roles or update-role-by-id, though it omits the realm scoping which is a key part of the operation.

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 alternatives like list-roles or get-composite-roles. No exclusions or context are provided, leaving the agent without decision support.

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 burden. It indicates a read operation ('Get'), which is non-destructive, but it does not disclose behavior such as possible errors, return format, or whether the operation is read-only. The description is not misleading, but it adds minimal behavioral context beyond what the tool name implies.

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 sentence that immediately states the verb, resource, and parameters. It is front-loaded and contains no filler or redundant phrasing. Every word 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 simple getter tool with two parameters and no output schema, the description is mostly complete. It specifies the lookup criteria (realm, userId) and the general purpose. However, it could be slightly more explicit about what 'user details' includes (e.g., profile attributes, roles, etc.), though the sibling context and schema partially compensate.

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%: the schema already explains 'realm' as 'Realm name' and 'userId' as 'User ID'. The description's 'from a specific realm' slightly reinforces the realm's role, but it does not add meaning beyond the schema. Baseline is 3 due to high schema coverage.

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

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

The description uses a specific verb ('Get'), names the resource ('user details'), and adds the scoping mechanism ('by ID from a specific realm'). This clearly distinguishes it from sibling tools like list-users and search-users, which have broader or different purposes.

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 this tool: when you have a known user ID and realm. It does not explicitly state when not to use it or name alternatives, but the context is clear given the tool's getter nature and the sibling set. No exclusions are mentioned, but the specificity of 'by ID' and 'from a specific realm' provides sufficient guidance.

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

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

With no annotations, the description carries the burden of disclosing behavior. The verb 'Get' implies a read-only operation, and 'including unmanaged attributes' adds useful context about the return scope. However, it does not specify permissions, error behavior, or what constitutes 'unmanaged', 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?

The description is a single, succinct sentence that is front-loaded with the key action and includes the most important differentiator without any 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?

The tool is simple with two well-documented params and no output schema, but the description covers the essential purpose and the unique 'unmanaged attributes' scope. It lacks details on response format or permissions, but for a simple getter it is nearly 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% for both parameters (realm and userId), and the description adds no additional parameter-level semantics. Baseline of 3 is appropriate as the schema already documents the parameters clearly.

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 clearly states the tool's function with a specific verb ('Get') and resource ('user attributes'), and the qualifier 'including unmanaged attributes' distinguishes it from sibling tools like 'get-user' and 'get-group-attributes'.

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 this tool is for retrieving user attributes, especially when unmanaged attributes are needed, but it does not explicitly state when to use it over alternatives or provide exclusion criteria.

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 burden of behavioral disclosure. It discloses the return structure ({ realmMappings, clientMappings }) and scopes the operation to directly assigned roles, but does not mention read-only semantics, required permissions, or error behavior. The added detail about the return shape provides some value beyond the schema, but the lack of annotation support leaves 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?

The description is a single, concise sentence that immediately states the action, target, and return shape. Every word adds value, and there is no 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 simple read operation with two self-explanatory parameters and no output schema, the description is fairly complete. It specifies the return structure and the 'directly assigned' scope. It could elaborate on the exact structure of realmMappings and clientMappings, but given the tool's simplicity and the absence of an output schema, this is a minor 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?

The input schema provides full descriptions for both parameters ('realm' and 'userId'), so the baseline is 3. The description does not add additional detail about the parameters beyond what the schema already states, such as the nature of the userId (e.g., internal ID vs username). No extra semantic value is provided.

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 clearly states the tool retrieves all roles directly assigned to a user, with the specific verb 'Get' and the resource being 'roles directly assigned to a user'. It distinguishes from sibling tools like 'list-roles' (all roles in a realm) and 'get-group-roles' (roles assigned to a group) by focusing on the user's direct assignments.

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 'directly assigned' implies the tool should be used when needing only direct assignments, not composite or inherited roles, but it does not explicitly name alternatives or when-not-to-use scenarios. Despite lacking explicit exclusions, the context is clear enough for an agent to infer appropriate usage.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It implies a read-only operation but lacks details on permissions, pagination, result format, or any side effects. Minimal transparency.

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, focused sentence with no wasted words. It effectively conveys the core purpose without unnecessary detail.

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?

Despite the low complexity, the description is missing key context for an agent to fully understand the tool: it doesn't clarify how it differs from list-sessions, what permissions are needed, or what the return structure looks like (no output schema). It feels under-specified for a tool that could be confused with a sibling.

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

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

Schema description coverage is 100%, and both parameters (realm, userId) are adequately described in the schema. The description adds no additional param context, but the schema already does the heavy lifting, so 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 clearly states the tool lists active sessions for a user, using a specific verb and resource. It is unambiguous but does not explicitly differentiate from the sibling list-sessions tool, so it misses the top score.

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 about when to use this tool versus alternatives like list-sessions. The description only states what it does, leaving the agent to infer usage 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?

There are no annotations, so the description must cover behavioral traits. It merely says 'Import' without clarifying whether this creates, updates, or upserts an identity provider, what happens if the provider already exists, or what side effects (e.g., network calls, overwrites) are involved. This is a significant transparency gap.

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

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

The description is a single, front-loaded sentence with no filler. Every word is relevant and the core action is immediately clear.

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 annotations, no output schema, and a moderate-complexity import operation, the description is too sparse. It omits success/failure behavior, prerequisites, and how it relates to other identity provider management tools, leaving the agent without essential context for reliable 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%, with all three parameters (realm, providerId, fromUrl) having basic descriptions. The description adds nothing beyond the schema, 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 'Import identity provider configuration from URL' — a specific verb (Import), resource (identity provider configuration), and source (URL). This clearly distinguishes the tool from siblings like create-identity-provider and update-identity-provider.

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 provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where URL-based import is preferred, nor does it exclude any use cases. The agent is left to infer context 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?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It indicates the tool returns a filtered set (roles that can still be granted), which is useful, but it does not mention permissions, whether already-assigned roles are excluded, or any sorting/pagination behavior. The phrase adds transparency but is incomplete.

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?

A single, well-structured sentence with no filler. It states the core purpose and the one conditional variation (clientId) efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only listing tool, the description covers what, scope, and parameter usage sufficiently. It is complete enough for correct invocation given the well-documented schema, though it could mention whether composite roles are included or excluded to be more thorough.

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?

Input schema covers all parameters (100%). The description repeats the realm-vs-client distinction already present in the schema, but does not add new semantics beyond the schema descriptions. Baseline of 3 is appropriate.

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

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

The description is specific and action-oriented: 'List roles a group could still be granted' identifies the exact resource and scope. The optional 'when clientId is given' further distinguishes which role set is returned, differentiating it from sibling tools like list-roles or get-group-roles.

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 'could still be granted' implies usage for pre-assignment discovery, and the clientId conditional clarifies how to narrow to a specific client. However, it does not explicitly name alternatives or exclusions (e.g., 'for currently assigned roles, use get-group-roles'), so clear context but no explicit when-not.

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 burden. The verb 'List' clearly indicates a read-only operation, which is useful. However, it does not disclose details such as whether composite roles are included, pagination behavior, or the response structure. For a simple list operation, the basic transparency is adequate, but richer context would improve it.

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

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

The description is a single, front-loaded sentence that directly states the operation. Every word earns its place, with no redundancy or fluff. It is concise without sacrificing clarity.

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?

The tool has only two parameters and no output schema, but the description does not clarify whether 'all roles' includes only top-level roles or also composite roles, which is a relevant ambiguity given sibling tools like 'list-composite-roles'. The description is sufficient for a basic list but lacks completeness in delineating edge cases.

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 input schema covers 100% of the parameters, each with a description ('Realm name' and 'Client ID'). The tool description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate. No extra context is provided about how the parameters interact or format requirements.

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 'List all roles defined on a client' uses a specific verb ('List') and identifies the resource ('roles') and scope ('on a client'). It clearly distinguishes from sibling tools like 'list-roles' by indicating client-scoped roles, making the purpose 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 phrase 'on a client' implies the tool is used for client-specific roles, and the existence of 'list-roles' suggests a realm-level alternative. However, the description does not explicitly state when to use this vs. list-roles, nor does it mention any exclusions or preconditions. Usage context is implied, not explicitly guided.

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 of behavioral disclosure. It only states 'List all clients' and does not mention return format, pagination, authentication needs, or the read-only nature beyond what the name implies. This lack of detail is a significant gap.

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

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

The description is a single sentence with no filler, front-loading the verb and resource. Every word contributes to the tool's purpose, making it highly concise and well-structured.

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?

The tool has no output schema and no annotations, so the description should provide context about return values or behavior. It simply says 'List all clients in a realm' without noting whether full client objects, summaries, or paginated results are returned. This underspecification makes it incomplete for an agent selecting the 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?

The schema already documents the single 'realm' parameter with 100% coverage. The description adds minimal context by clarifying that listing is scoped to a realm, but does not add semantics beyond the schema's 'Realm name' description. 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 the specific verb 'List' with the resource 'clients' scoped to 'realm', clearly distinguishing it from sibling tools like create-client, update-client, and delete-client. There is no ambiguity about what the tool does.

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 context: it lists clients within a specified realm. However, it does not explicitly state when to use this tool over alternatives or provide exclusions. Since there are no direct sibling tools for listing clients, the guidance is minimal but adequate.

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 of behavioral disclosure. The verb 'list' implies a read-only operation, which is a useful signal, but the description does not elaborate on response format, pagination, filtering, permissions, or any side effects. For a simple list operation, this is minimally adequate but lacks depth.

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, focused sentence with no redundant words or filler. It front-loads the action and resource, making it immediately scannable and valuable.

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 list operation with no output schema, the description gives the core purpose and leaves little ambiguity about the operation's intent. However, it does not describe the shape of the returned list, any default ordering, or whether there are system limits, which could be helpful. Given the low complexity, the description is mostly 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?

The input schema already provides descriptions for both parameters ('Realm name' and 'Client scope ID'), achieving 100% coverage. The tool description adds no additional meaning or context for these parameters, so the baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'list' and identifies the resource as 'protocol mappers' with the scope modifier 'for a client scope', clearly distinguishing it from the sibling 'list-protocol-mappers' which likely applies to clients. This provides a precise and unambiguous purpose.

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 the similar 'list-protocol-mappers' or 'list-identity-provider-mappers' tools. The description does not mention any exclusions, prerequisites, or alternative tools, leaving the agent to infer the intended usage solely 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?

No annotations are provided, so the description carries the full burden. It only states the operation is a list, but does not disclose return format, pagination behavior, required permissions, or other side effects. Minimal transparency beyond the action itself.

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?

Exactly one sentence, front-loaded with the verb and object, no redundant words or fluff. Perfectly concise for a simple listing tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.