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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the return payload — Client ID, and Client Secret only for confidential clients — which is important since no output schema exists and the secret is not retrievable later.

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

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

Three short sentences, front-loaded with the core action and the return value before the configuration hint. Nothing is padded, though the final sentence largely restates schema content and is the least load-bearing.

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 10 parameters and no output schema, the description does the key job of telling the agent what comes back from the call. It omits secondary operational details (duplicate-name behavior, whether the secret is ever re-issuable), but for a creation tool with fully documented parameters this is close to complete.

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

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

Schema description coverage is 100%, and the schema itself carries rich per-parameter documentation (defaults, enum meanings, PKCE guidance for authMethodType, JWT-vs-bearer tradeoffs). The description's third sentence ('Configure redirect URIs, response types, and grant types') only names categories already fully documented in 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?

States a specific verb and resource ('Create a new OIDC application in a Zitadel project'), which cleanly separates it from sibling creation tools like zitadel_create_project, zitadel_create_user, and zitadel_create_service_user. The agent knows exactly what object is produced.

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

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

The description implies when the tool is relevant (creating an OIDC app, configuring redirect/grant/response types) but never states when to prefer it over alternatives such as zitadel_create_service_user or zitadel_create_project, nor any prerequisites or when-not conditions. Usage is inferable but not spelled out.

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

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

Annotations indicate this is a non-read-only, non-idempotent, non-destructive operation, which the description aligns with by implying creation (a write). It adds minimal behavioral context beyond annotations—mentioning that projects contain applications, roles, and grants—but doesn't cover aspects like permissions needed, rate limits, or error handling.

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 (two sentences) and front-loaded with the core purpose. The second sentence provides useful context without redundancy. It could be slightly improved by integrating usage hints, but it's efficient overall.

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

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

For a creation tool with no output schema and moderate complexity (3 parameters), the description is minimally adequate. It covers the purpose but lacks details on usage, behavioral traits beyond annotations, and output expectations. With annotations providing safety info, it's not incomplete, but gaps remain.

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 parameters are well-documented in the schema. The description doesn't add any semantic details about parameters beyond what's in the schema (e.g., explaining 'projectRoleAssertion' further), but it doesn't need to given the high coverage. 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 ('Create a new project') and resource ('in Zitadel'), with additional context about what projects contain. It distinguishes from siblings like 'zitadel_create_user' or 'zitadel_create_oidc_app' by focusing on projects, though it doesn't explicitly contrast with 'zitadel_get_project' or 'zitadel_list_projects'.

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 doesn't mention prerequisites (e.g., needing admin permissions), compare to sibling tools (e.g., 'zitadel_get_project' for reading), or specify scenarios for project creation (e.g., initial setup vs. adding new projects).

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety/idempotency profile is covered. The description adds no behavioral context of its own — nothing about duplicate role keys, required permissions, or side effects — so it contributes almost nothing beyond the structured fields.

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

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

Two tight sentences with the core action front-loaded and the key convention as supporting detail. No filler or redundancy.

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

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

For a simple create mutation with 100% schema coverage and annotations handling safety and idempotency, the description is adequate. It is still thin on failure behavior (e.g., duplicate roleKey in an idempotent tool), but the structured fields carry most of the load.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description's note about "admin"/"standard" keys merely repeats the schema's own roleKey description, adding no syntax or format detail beyond it; baseline 3 applies.

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

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

States a specific verb (Create) and resource (role in a Zitadel project), which clearly separates it from siblings like zitadel_list_project_roles. It does not explicitly name an alternative to differentiate further, but the purpose is unambiguous.

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

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

The description gives a key-vocabulary convention ("admin" or "standard") and cross-references zitadel_provision_user, which implies when the standardized model applies. However, it never states when to create a custom role instead, nor any prerequisites 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?

Annotations already indicate this is a non-readOnly, non-destructive, non-idempotent operation. The description adds useful behavioral context about authentication method (JWT keys) that isn't captured in annotations, but doesn't disclose other important traits like rate limits, error conditions, or what happens on duplicate userName. No contradiction with annotations exists.

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

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

Two concise sentences that are front-loaded with the core purpose. Every word earns its place - first sentence states what the tool does, second adds crucial authentication context. No wasted words or redundant information.

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

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

For a creation tool with good annotations (readOnlyHint=false, destructiveHint=false) and comprehensive schema coverage, the description provides adequate context about the tool's purpose and authentication method. However, without an output schema, it doesn't describe what gets returned (e.g., user ID, credentials), leaving a minor gap in 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?

With 100% schema description coverage, the schema already documents all 4 parameters thoroughly. The description doesn't add any parameter-specific semantics beyond what's in the schema (e.g., doesn't explain userName uniqueness constraints or accessTokenType implications). Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the specific action ('Create a new service account') and resource ('machine user for API access'), distinguishing it from sibling tools like 'zitadel_create_user' (regular user) and 'zitadel_create_service_user_key' (key for existing service account). It adds valuable context about authentication method (JWT keys vs passwords).

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 ('for API access', 'authenticate via JWT keys') but doesn't explicitly state when to use this tool versus alternatives like 'zitadel_create_user' or 'zitadel_create_oidc_app'. No guidance on prerequisites, permissions needed, or when-not-to-use scenarios 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?

Annotations indicate this is a non-readOnly, non-idempotent, non-destructive operation. The description adds valuable behavioral context: it explicitly warns that 'The private key is returned ONLY at creation time — save it immediately,' which is critical for security and operational awareness beyond what annotations provide. However, it doesn't mention rate limits, authentication requirements, or error conditions.

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, well-structured sentence that efficiently conveys the core action and critical warning. Every word earns its place—no fluff or redundancy, and the key behavioral detail is 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?

Given the complexity (a write operation with security implications), lack of output schema, and rich annotations, the description is partially complete. It covers the main action and a crucial behavioral warning but omits details like response format, error handling, or prerequisites. It's adequate but has clear gaps for a tool that generates sensitive credentials.

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 clear parameter documentation in the schema itself. The description doesn't add any parameter-specific details beyond what's in the schema (e.g., it doesn't explain key formats or default behaviors for expirationDate). Baseline score of 3 is appropriate since the schema carries the full burden.

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 specific action ('Generate a new key pair') and target resource ('for a service account'), distinguishing it from sibling tools like 'zitadel_create_service_user' (creates the account itself) or 'zitadel_list_service_user_keys' (lists existing keys). It goes beyond just restating the name/title.

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 doesn't mention prerequisites (e.g., needing an existing service account), compare to sibling tools like 'zitadel_list_service_user_keys', or specify scenarios where key generation is appropriate versus other operations.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds valuable context: an invitation email is sent automatically, and supplying a userId enables idempotent retries with clean conflict behavior. This goes beyond the annotations, which only mark it as a non-destructive write. However, it doesn't mention permission requirements or what happens on conflict beyond the userId case.

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

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

Three sentences, each earning its place: purpose, side effect (email), and idempotency detail. Front-loaded with the core action and no wasted words.

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

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

No output schema exists, but the description covers the key behavioral aspects: it's a create operation that sends an email and supports idempotent retries. Missing details on required permissions and what the response contains (e.g., the new user ID) are minor gaps for this complexity level.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds meaning for userId (idempotency, conflict behavior) beyond the schema's description, but for email, firstName, and lastName it adds nothing beyond what the schema provides. Baseline 3 is appropriate when schema does most of the work.

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

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

States a specific verb (Create), resource (human user), and scope (in Zitadel), which distinguishes it from sibling tools like zitadel_create_service_user and zitadel_provision_user. An agent can tell what the tool does without opening the schema.

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

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

The description implies this is for creating new human users and mentions the invitation email flow, but it doesn't explicitly state when to use this tool versus alternatives like zitadel_provision_user or zitadel_create_service_user. A clear use case is provided (human user with email invitation), which is better than no guidance, but lacks exclusion criteria or explicit routing 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?

Annotations already declare the write/non-idempotent/non-destructive profile, so the bar is lower. The description still adds genuine behavior beyond them: pre-grant validation that roles exist in the project and drift-flagging for non-standard keys. It omits what happens on validation failure or duplicate grants, hence 4.

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

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

Three tight sentences, front-loaded with the core action before the role-model guidance. Every sentence carries information; the only marginal cost is the internal 'v2 AuthorizationService' reference, which is closer to implementation detail than agent-facing guidance.

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 3-parameter, 100%-covered schema with annotations present and no output schema, this is largely complete: it covers purpose, validation behavior, and role conventions. Error semantics (role not found) and non-idempotency consequences are the remaining gaps but are not essential to invoking it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond it by explaining the consequence of non-standard roleKeys ('allowed but flagged as drift') and reinforcing the admin/standard model. Nice added semantic layer over 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?

Specific verb+resource: 'Assign project roles to a user' clearly separates it from zitadel_create_project_role (which defines roles) and zitadel_remove_user_grant (which reverses this). The 'v2 AuthorizationService' detail anchors it further. It stops short of explicitly naming a sibling for contrast, keeping it at 4.

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

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

Provides a preference rule for role keys ('prefer admin/standard') but gives no when-to-use context relative to alternatives such as zitadel_grant_org_manager or zitadel_create_project_role, and no prerequisites (permissions, project existence). Usage is implied rather than scoped.

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

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

Annotations already indicate this is a destructive, non-read-only, idempotent operation. The description adds valuable context beyond annotations by specifying the behavioral consequence ('The user will no longer be able to log in') and the confirm requirement for execution, which clarifies the tool's safety mechanism and user impact.

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 front-loaded with the core action and consequence, followed by a concise prerequisite. Both sentences are essential—the first defines the tool's purpose and effect, and the second specifies a critical usage requirement—with no wasted words.

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

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

Given the tool's complexity (destructive user management), rich annotations (destructiveHint, idempotentHint), and full schema coverage, the description is mostly complete. It covers the action, consequence, and a key parameter behavior. However, without an output schema, it does not describe return values or error conditions, leaving 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?

Schema description coverage is 100%, so the schema fully documents both parameters. The description adds some meaning by explaining the purpose of 'confirm' ('Must be true to execute. Omit to preview the action.'), but this is partially redundant with the schema's description. It does not provide additional context for 'userId' beyond what the schema states.

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 specific action ('deactivate a user account') and the resource ('user'), and distinguishes it from siblings like 'delete_user', 'lock_user', and 'reactivate_user' by specifying the user will no longer be able to log in, which is a distinct state change.

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 context for when to use it (to deactivate a user account so they can't log in) and includes a prerequisite ('Requires confirm: true'), but does not explicitly mention when not to use it or name alternatives like 'delete_user' or 'lock_user' for different 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?

The description adds valuable behavioral context beyond what annotations provide. While annotations already declare destructiveHint=true, the description emphasizes 'This action cannot be undone' and specifies the confirm parameter requirement. It doesn't contradict annotations but enhances understanding of the tool's irreversible nature and safety mechanism.

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 and front-loaded, with every sentence earning its place. The first sentence states the core action, the second warns about irreversibility, the third specifies the confirm requirement, and the fourth provides alternative guidance—all in just four sentences with no wasted words.

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

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

Given the tool's destructive nature and lack of output schema, the description provides strong contextual completeness. It covers the irreversible consequence, confirm requirement, and alternative tool. While it doesn't detail return values (no output schema exists), it adequately addresses the critical aspects needed for safe usage of this high-stakes 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?

With 100% schema description coverage, the input schema already fully documents both parameters. The description adds minimal semantic context by mentioning 'Requires confirm: true', which slightly clarifies the confirm parameter's purpose beyond the schema's description. This meets the baseline expectation when schema coverage is high.

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 specific action ('permanently delete a user') and resource ('user'), distinguishing it from sibling tools like 'zitadel_deactivate_user' which is mentioned as an alternative. It goes beyond just restating the name/title by emphasizing the irreversible nature of the action.

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

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

The description explicitly provides when to use this tool vs. alternatives by stating 'Consider using zitadel_deactivate_user instead (reversible)', offering clear guidance on when to choose this destructive option over a reversible one. It also specifies a prerequisite with 'Requires confirm: true'.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, so the description doesn't need to repeat these. It adds value by specifying the type of details returned ('Client ID and OIDC configuration'), which helps the agent understand the output content beyond what annotations provide. No contradictions with annotations are present.

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

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

The description is a single, efficient sentence that front-loads the key action and details without any wasted words. It directly communicates the tool's purpose and output, making it easy to parse and understand quickly.

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's low complexity (2 required parameters, no output schema), the description is reasonably complete. It specifies what details are retrieved, which compensates for the lack of output schema. However, it could be more comprehensive by mentioning potential error cases or linking to sibling tools for better context.

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 fully documents the two parameters ('projectId' and 'appId'). The description doesn't add any additional meaning or context about the parameters beyond what's in the schema, such as format examples or relationships between them, but this is acceptable given the 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 clearly states the verb ('Get details') and resource ('specific application'), specifying what information is retrieved ('Client ID and OIDC configuration'). It distinguishes from sibling tools like 'zitadel_list_apps' by focusing on a single application, though it doesn't explicitly contrast with other get tools like 'zitadel_get_project' or 'zitadel_get_user'.

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

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

The description implies usage when details of a specific application are needed, but it doesn't provide explicit guidance on when to use this tool versus alternatives (e.g., 'zitadel_list_apps' for listing applications or 'zitadel_update_app' for modifications). No exclusions or prerequisites are mentioned, leaving usage context somewhat vague.

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

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

Annotations already indicate this is a read-only, idempotent, non-destructive operation. The description adds valuable context beyond this by specifying the output format ('ready-to-paste configuration' for .env.local) and the purpose (fetching app details for environment variables), which helps the agent understand the tool's specific behavior and use case.

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 two concise sentences that are front-loaded with the main purpose. Every word earns its place by clearly explaining what the tool does and its specific output format, with no wasted text or redundancy.

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

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

Given the tool's moderate complexity (2 required parameters, no output schema), the description is mostly complete. It explains the purpose, output format, and context well, but doesn't detail potential errors, authentication requirements, or rate limits, which could be helpful for an agent despite the annotations covering safety aspects.

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 clear descriptions for both parameters ('projectId' and 'appId'). The description doesn't add any additional semantic information about these parameters beyond what the schema provides, so it meets the baseline of 3 for adequate coverage without extra 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 clearly states the specific action ('Get the environment variables'), the resource ('app details'), and the output format ('formats them as ready-to-paste configuration'). It distinguishes itself from sibling tools like 'zitadel_get_app' by specifying the unique formatting purpose for .env.local files.

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 context for when to use this tool ('for a new application's .env.local file'), but it doesn't explicitly mention when not to use it or name alternatives. For example, it doesn't contrast with 'zitadel_get_app' which might return raw app details without formatting.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: default returns the merged effective file (overrides on top of shipped defaults), onlyOverrides surfaces just the stored level, and level defaults to the configured org with instance as the alternative.

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

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

Front-loaded with the core purpose, then scope, then the merged-vs-overrides distinction, then the key format. Three dense sentences with no filler; slightly long but each clause carries information.

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

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

No output schema exists, so the description carries some return-format burden, and it does describe the shape of the returned file (merged effective vs stored overrides). For a read-only, well-documented tool this is close to complete, though exact response structure is only implied.

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 goes further by giving the override-key convention and a concrete example ('password.errors.couldNotCreateSessionForUser') mirroring apps/login/locales/<locale>.json, and by restating the inheritance semantics of onlyOverrides meaningfully.

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

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

States a specific verb (Read) and resource (Login V2 hosted login text overrides for a locale) and explicitly distinguishes the target from the legacy Management 'Custom Login Texts'. An agent can identify this as the read counterpart to set_hosted_login_translation without opening a schema.

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

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

Explains when this is the correct resource ('the ONLY text-customization that affects the new login') and rules out the legacy alternative. It gives context for the parameter branches (onlyOverrides, level) but never names the sibling write tool as the complement, leaving a small routing gap.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it tells the agent the read targets the current org and that the result reflects inheritance from the instance default versus a custom org policy.

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 leads with the verb and resource, with the elaborating clause placed after. No filler or redundancy.

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

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

For a zero-parameter read with no output schema, the description usefully names the key fields returned (allowRegister, inheritance status), which compensates for the missing output schema. It stops short of covering error or empty/null 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 tool takes zero parameters, so the baseline is 4; there is no argument syntax the description needs to compensate for. The parenthetical clarifies that org scope is implicit via ZITADEL_ORG_ID rather than a call argument.

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

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

States a specific verb (Get) plus resource (the login policy of the current organization, pinned to ZITADEL_ORG_ID) and enumerates what the policy carries (allowRegister, inherited vs custom). This is distinguishable from the nearest sibling, zitadel_get_auth_config, which concerns a different configuration surface.

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 never states when to call this tool versus alternatives, nor any preconditions (e.g., required org context or permissions). Only the scope of what is read is implied, with no exclusions or routing 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds value by specifying it retrieves details for the 'current organization' based on a configuration, which is useful context not in annotations. However, it doesn't disclose additional behaviors like rate limits, authentication needs, or response format, keeping it at a baseline 3.

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

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

The description is a single, efficient sentence that front-loads the key information ('Get details of the current organization') and adds necessary context ('based on the configured ZITADEL_ORG_ID'). There is zero waste, and every word earns its place, 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?

Given the tool has 0 parameters, rich annotations (read-only, idempotent, non-destructive), and no output schema, the description is reasonably complete. It explains what the tool does and the context (current organization based on config). However, it could slightly improve by hinting at the return type (e.g., 'details' like name, ID) since there's no output schema, preventing a perfect 5.

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 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, earning a baseline 4 for not adding unnecessary information. It correctly focuses on the tool's purpose instead.

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 details') and resource ('current organization'), making the purpose understandable. It distinguishes itself from sibling tools like 'zitadel_get_user' or 'zitadel_get_project' by specifying it retrieves organization details. However, it doesn't explicitly contrast with all siblings (e.g., 'zitadel_list_users'), so it's not a perfect 5.

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

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

The description provides clear context by stating it retrieves 'current organization (based on the configured ZITADEL_ORG_ID)', which implies when to use it—when you need details for the pre-configured organization. It doesn't explicitly mention when not to use it or name alternatives (e.g., for other organizations), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, repeatable read operation. The description adds no behavioral context beyond what annotations provide, such as authentication needs, rate limits, or error conditions, but it doesn't contradict annotations either.

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

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

The description is a single, efficient sentence that directly states the tool's function without any fluff or redundancy. It's front-loaded and every word serves a 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?

Given the simple single-parameter input, rich annotations covering safety and idempotency, and lack of output schema, the description is minimally adequate. However, it doesn't explain what 'details' are returned or potential error cases, leaving gaps for a read operation that could benefit from more context.

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 one parameter ('projectId') fully documented in the schema. The description adds no additional meaning or context about the parameter beyond implying it's required for lookup, so it meets the baseline for high schema coverage without compensating 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 clearly states the action ('Get details') and resource ('specific project by its ID'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'zitadel_get_org' or 'zitadel_get_user' beyond mentioning 'project' specifically, which is why it doesn't reach a perfect 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?

The description provides no guidance on when to use this tool versus alternatives like 'zitadel_list_projects' or other 'get_' tools. It mentions 'by its ID' which implies you need the ID, but doesn't specify prerequisites or contrast with siblings, leaving usage context unclear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, repeatable read operation. The description adds minimal behavioral context beyond this—it specifies 'detailed information' as the output, which hints at richer data than a basic list, but doesn't elaborate on what details are included, error conditions, or authentication needs. No contradiction with annotations exists.

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

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

The description is a single, efficient sentence that front-loads the core action ('Get detailed information') and resource ('specific user'), with no wasted words. It directly addresses the tool's purpose without redundancy, making it easy for an agent to parse quickly.

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's low complexity (one parameter, no output schema) and rich annotations covering safety and idempotency, the description is minimally adequate. However, it lacks details on output format (e.g., what 'detailed information' includes), error handling, or authentication requirements, which could help an agent use it more effectively despite the annotations.

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 one parameter ('userId') fully documented in the schema. The description adds no additional parameter semantics beyond what the schema provides—it mentions 'user ID' but doesn't clarify format, examples, or constraints. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

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 detailed information') and resource ('specific user'), making the purpose unambiguous. It distinguishes from sibling tools like 'zitadel_list_users' by specifying retrieval of a single user by ID rather than listing multiple users. However, it doesn't explicitly contrast with other 'get' tools like 'zitadel_get_app' or 'zitadel_get_project' beyond the user focus.

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 when detailed user information is needed for a specific ID, but provides no explicit guidance on when to use this versus alternatives like 'zitadel_list_users' for browsing or other 'get' tools for different resources. It mentions the 'user ID' requirement, which is helpful context, but lacks when-not-to-use scenarios or prerequisite conditions.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false; the description corroborates and enriches this by explaining the merge semantics ('merges with any existing manager roles'), which tells the agent existing roles are preserved rather than replaced. It omits who is authorized to call it and whether super-admin privileges are required.

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

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

Three short sentences, each carrying distinct payload (purpose, usage pattern, idempotency/default), with the core action front-loaded and no filler.

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

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

For a two-parameter mutation tool with no output schema, the description covers purpose, the common pattern, merge behavior, and defaults. The main remaining gap is caller authorization context (whether the invoking identity needs super-admin rights), which matters for a role-granting tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters, including the default and the meaning of ORG_OWNER. The description's mention of the default and 'ORG_OWNER = full org control' largely restates 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?

States a specific verb and resource ('Grant org-level manager (administrator) role(s) to a user'), and the directionality of the verb cleanly separates it from the sibling zitadel_revoke_org_manager and from the read-only zitadel_list_org_manager_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?

Gives a concrete usage scenario ('For the no-super-admin pattern, grant ORG_USER_MANAGER to every Admin so they can manage any user'), which tells the agent when this tool is the right call. It never names the alternative tools (revoke_org_manager, list_org_manager_roles) or states when NOT to use it, so it stops short of explicit routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, repeatable read operation. The description adds no behavioral context beyond what annotations provide, such as pagination, rate limits, or what 'all applications' means in practice.

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

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

The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a simple list operation and front-loads the essential information.

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

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

For a simple read-only list tool with good annotations but no output schema, the description is minimally adequate. It states what the tool does but lacks context about return format, pagination, or error conditions that would help the agent use it 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?

With 100% schema description coverage, the input schema fully documents the single parameter 'projectId'. The description adds no additional meaning about the parameter beyond implying it's required for scoping, which is already clear from the schema.

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

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

The description clearly states the action ('List all applications') and resource ('in a Zitadel project'), making the purpose immediately understandable. However, it doesn't distinguish this tool from other list tools like 'zitadel_list_projects' or 'zitadel_list_users' beyond specifying the resource type.

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. There's no mention of prerequisites, when not to use it, or how it differs from sibling tools like 'zitadel_get_app' or 'zitadel_update_app'.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that — it does not note that the result set is static/fixed or how it is returned — so with annotations carrying the load, a 3 is appropriate.

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

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

Two tight sentences, front-loaded with the resource and scope, followed by the actionable purpose. Every clause earns its place, including the example keys that make the output concrete.

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

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

For a zero-parameter, read-only enumeration tool with annotations covering the safety profile, the description supplies everything needed: what is listed, at what scope, with sample values, and when to call it. Nothing an agent needs before invoking it 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter-level confusion is possible.

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

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

States a specific verb (List) and resource (org-level manager/administrator role keys) with concrete example keys (ORG_OWNER, ORG_USER_MANAGER). The 'org-level' qualifier implicitly separates it from the sibling zitadel_list_project_roles, which covers project 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?

Explicitly gives the use case: 'Use to confirm the exact keys before granting', which ties it to the grant_org_manager workflow. It does not state any when-not condition or name alternatives, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that results include each user's manager roles, which is useful return-content context, but says nothing about pagination, result size, or permission requirements. Adequate but not rich given the low bar set by annotations.

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

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

Two tight sentences with zero filler: the first front-loads what is returned, the second covers the optional filter. Nothing is redundant and every clause earns its place.

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

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

For a read-only list tool with one optional parameter and no output schema, the description covers the resource, the returned fields, and the filter behavior. It omits result shape (pagination, ordering, limits), which is a minor gap given the tool's simplicity and its safe annotations.

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 single 'role' parameter is already fully documented in the schema with examples. The description's mention of the role-key filter and the ORG_OWNER example largely restates 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 a specific verb and resource: 'List users who hold org-level manager (administrator) grants, with their manager roles.' This clearly separates it from the sibling zitadel_list_org_manager_roles, which enumerates role definitions rather than holders. It does not name that sibling explicitly, so it falls short of a 5.

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

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

It explains the purpose of the optional filter ('to see who holds it'), which implies the use case for a role-scoped query versus listing all managers. However, it never states when to prefer this tool over zitadel_list_user_grants or zitadel_list_org_manager_roles, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered and not contradicted. The description adds nothing beyond that – no note on default-project fallback behavior, result size, or pagination – which is acceptable but minimal given annotations carry the load.

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 compact sentence that front-loads the verb and resource, with the examples earning their place by clarifying what a 'role' means here. Nothing is wasted.

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

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

For a simple single-parameter read tool with fully documented schema and annotations covering the safety profile, the description is adequate. The only minor gap is that it does not mention the no-filter scope behavior when projectId is omitted, though the schema states this.

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

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

Schema coverage is 100%, so the schema already documents projectId including the 'uses default project if omitted' behavior. The description adds no parameter-level meaning, 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?

States a specific verb and resource ('List all roles defined in a Zitadel project') and grounds it with example role names. It does not explicitly differentiate itself from the adjacent zitadel_list_org_manager_roles or zitadel_create_project_role, so it falls short of a 5.

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

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

There is no statement of when to call this versus related tools such as zitadel_list_org_manager_roles, nor any prerequisites or exclusions. Usage is only implied by the phrase 'defined in a project'.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds no behavioral context beyond this, such as pagination details or rate limits, but doesn't contradict annotations, so it meets the lower bar with minimal added value.

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, clearly front-loading the purpose. It's appropriately sized for a simple listing tool, making it easy to parse quickly.

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's low complexity (one optional parameter), rich annotations covering safety, and no output schema, the description is minimally adequate. However, it lacks details on output format or pagination, which could help an agent use it effectively, leaving room for improvement.

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 the single parameter 'limit' fully documented in the schema. The description doesn't add any parameter semantics beyond what the schema provides, so it defaults to 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 clearly states the action ('List all projects') and resource ('in the Zitadel organization'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'zitadel_list_apps' or 'zitadel_list_users' beyond the resource type, missing explicit sibling distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for listing projects, or compare with similar tools like 'zitadel_get_project' for retrieving a single project, leaving usage unclear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context by specifying that it 'Shows key metadata only (not private keys)', which clarifies output limitations beyond what annotations provide. No contradictions with annotations exist.

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 two concise sentences with zero wasted words, front-loading the core purpose and efficiently adding a key behavioral detail. It's appropriately sized for a simple 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?

Given the tool's low complexity (1 parameter, no output schema), rich annotations covering safety, and clear purpose, the description is largely complete. It could slightly improve by mentioning output format or pagination, but the metadata clarification compensates well for the lack of output schema.

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

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

The input schema has 100% description coverage, with 'userId' clearly documented as 'The service account user ID'. The description doesn't add any parameter details beyond the schema, so it meets the baseline for high schema coverage without extra 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 clearly states the action ('List existing keys') and resource ('for a service account'), with the clarifying detail about showing only metadata. It distinguishes from sibling tools like 'zitadel_create_service_user_key' by focusing on listing rather than creation, though it doesn't explicitly differentiate from other list tools like 'zitadel_list_apps'.

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 when needing to view keys for a specific service account, but provides no explicit guidance on when to use this versus alternatives, prerequisites, or exclusions. It doesn't mention when not to use it or refer to other tools for related operations.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds semantic framing (grants = assigned project roles) but nothing about pagination, result size, or ordering for a list endpoint, which is a real gap even at the lower annotated bar.

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 with no wasted words, and the defining scope ('for a specific user') comes early. It is appropriately sized, though it could have traded a few words for actual usage guidance.

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-param, fully documented, read-only list tool with no output schema, the description covers the essentials of what is returned. It is adequate but thin: no indication of result shape, volume, or how to interpret multiple grants, leaving the agent to discover behavior at call time.

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

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

Schema description coverage is 100%, including the 'uses default project if omitted' nuance, so the schema carries parameter meaning. The description only restates that grants belong to a specific user and adds no syntax, format, or filter semantics beyond that baseline.

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

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

Uses a specific verb+resource ("List role grants (authorizations)") and scopes it to a user, with a clarifying parenthetical that distinguishes it from the project-scoped sibling zitadel_list_project_roles. It stops short of naming the alternatives (list_project_roles, list_users) that an agent might confuse it with.

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

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

Usage is only implied: "for a specific user" suggests it answers 'what can this user access?', and the schema's projectId hints at project filtering. There is no explicit when-to-use/when-not or routing to siblings, so the agent must infer the boundary against list_project_roles and create_user_grant itself.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, repeatable read operation. The description adds value by specifying the return content ('user details including name, email, status, and login names'), which isn't covered by annotations. However, it lacks details on pagination, rate limits, or authentication requirements.

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

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

The description is a single, efficient sentence that front-loads the core action ('List or search users') and includes key return details. Every word earns its place with no redundancy or fluff.

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's low complexity (read-only list/search), rich annotations, and full parameter documentation, the description is adequate but minimal. It lacks output schema, so describing return values is helpful, but it doesn't cover error cases or behavioral nuances like pagination. It meets basic needs but leaves gaps.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description mentions 'search' which aligns with the 'query' parameter but adds no additional semantics beyond what the schema provides. With high schema coverage, 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 ('List or search') and resource ('users in the Zitadel instance'), making the purpose evident. It distinguishes from siblings like 'zitadel_get_user' (singular retrieval) by emphasizing listing/searching multiple users. However, it doesn't explicitly differentiate from 'zitadel_list_user_grants', which might cause some ambiguity.

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 doesn't mention when to prefer 'zitadel_get_user' for single-user retrieval, 'zitadel_list_user_grants' for related data, or other sibling tools. Usage context is implied but not explicit.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, but the description adds valuable context: it explains the consequence ('user will not be able to log in until unlocked') and the confirm parameter's role in execution vs. preview. However, it lacks details on permissions, rate limits, or error conditions.

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 two sentences with zero waste: the first sentence states the purpose and effect, and the second specifies the confirm requirement. It is front-loaded and appropriately sized for a destructive action 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 destructive tool with no output schema, the description is mostly complete: it covers purpose, effect, and a key parameter requirement. However, it lacks details on permissions needed, potential errors, or return values, which would be helpful given the tool's 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?

With 100% schema description coverage, the schema fully documents both parameters. The description adds minimal value by mentioning the confirm parameter's requirement, but does not provide additional semantics beyond what the schema already states (e.g., format of userId or implications of confirm).

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 ('Lock') and resource ('user account'), specifies the effect ('will not be able to log in until unlocked'), and distinguishes it from sibling tools like 'zitadel_unlock_user' and 'zitadel_deactivate_user' by focusing on locking functionality.

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 context for when to use this tool (to lock a user account) and includes a prerequisite ('Requires confirm: true'), but does not explicitly state when not to use it or name alternatives like 'zitadel_deactivate_user' for comparison.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description still adds substantive context beyond them: the exact set of mutations performed, the last-Admin/ORG_OWNER protection rules, and the confirm-gated preview mode. That is exactly the elevated bar annotations should not count toward.

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?

Dense but front-loaded: the offboard action leads, the guards are compressed into one clause-heavy sentence, and the confirm requirement is stated last where it is most likely to be acted on. No filler sentences, though the semicolon-heavy guards take a second read.

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 7-param mutation with full schema coverage and no output schema, the description covers the action, the guards, and the preview/confirm protocol adequately. It stops short of describing reversibility or what happens to other grants the user may hold, which would matter for an offboarding operation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: it explains why actingUserId exists (self-demotion block), what confirm does beyond 'must be true' (omitting previews), and names the role removals tied to removeManager. It does not cover projectId or deactivate defaults, so not a 5.

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

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

States a specific verb (offboard) plus the concrete sub-actions it performs (remove Admin|Standard project role, revoke org-manager grant, deactivate account), which distinguishes it from siblings like zitadel_deactivate_user and zitadel_delete_user that do only one of those things.

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

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

Gives explicit preconditions and exclusions: 'Requires confirm: true', 'Omit to preview', and three hard guards (last Admin, self-demotion, last ORG_OWNER). It doesn't explicitly route to a sibling for partial operations, but the guard conditions clearly scope when this tool may be used.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description adds real substance on top: atomicity, the three cascade steps (create user, assign project role via v2 AuthorizationService, grant ORG_USER_MANAGER for admins), the idempotency key semantics, and the no-super-admin rationale. It stops short of stating permission requirements or conflict/error behaviour when an email already exists.

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

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

Front-loads the verb and scope, then enumerates the cascade compactly, ending with the return shape and a one-line 'Safe to re-run' reassurance. Dense jargon ('app-portal cascade-up', 'no-super-admin pattern') makes it slightly hard to parse but nothing is wasted.

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

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

With no output schema, the description usefully supplies the return shape { zitadelUserId, role, authorizationId } and covers idempotency and role-grant side effects. It omits failure/conflict handling and required permissions, which an agent calling a mutating provisioning tool would want.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema: userId is explained as the idempotent-retry key ('idempotent by email or supplied userId'), and grantOrgManager's admin-only coupling to ORG_USER_MANAGER clarifies why the default varies by role. projectId and the required fields gain no extra description-level detail.

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

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

States a specific verb (provision) and resource (user) and scopes it to 'the core SSO apps (the app-portal cascade-up)', which implicitly separates it from the raw zitadel_create_user sibling by signalling it is a composite operation. It never names a sibling explicitly, so an agent must infer the boundary rather than being routed.

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 conveys context ('for the core SSO apps', 'safe to re-run') and the no-super-admin pattern, so the intended scenario is implied. It gives no explicit when-to-use/when-not guidance or comparison against zitadel_create_user, zitadel_create_user_grant, or zitadel_grant_org_manager, which are the obvious alternatives.

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

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

Annotations cover key behavioral traits (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description doesn't need to repeat these. It adds minimal context by specifying 'previously deactivated,' but doesn't elaborate on effects like permission restoration or error conditions. No contradiction with annotations exists.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, making it easy for an agent to parse quickly.

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 simple parameter schema and annotations covering safety and idempotency, the description is adequate but minimal. It lacks details on output (no schema provided) and doesn't address potential errors or side effects, which could be helpful for a mutation tool despite the annotations.

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

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

Schema description coverage is 100% for the single parameter 'userId,' with a clear description in the schema. The tool description adds no additional parameter semantics beyond what's already documented, so it meets the baseline for high schema coverage without compensating 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 clearly states the action ('reactivate') and resource ('previously deactivated user account'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'zitadel_unlock_user' or 'zitadel_create_user', which could cause confusion about when to use each.

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 doesn't mention prerequisites (e.g., the user must be deactivated first), exclusions, or relationships with sibling tools like 'zitadel_deactivate_user' or 'zitadel_unlock_user', 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description reinforces this with the confirm gate and the preview-if-omitted behavior, but that same detail is already in the schema, so it adds limited new context (no permission requirements, no effect on other grants).

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

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

Two sentences, zero waste, with the action stated first and the confirm requirement front-loaded as the second sentence.

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

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

For a destructive mutation whose safety hints are already in annotations, and with no output schema to explain, the description plus schema give the agent enough to call it correctly. Missing only privilege/scope context, which keeps it from a 5.

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

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

Schema coverage is 100%, so all three parameters are already documented, including the confirm/preview semantics. The description only restates the grant-ID targeting, adding nothing the schema does not already say — baseline 3.

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

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

States a specific verb and resource ('Remove a role grant (authorization) from a user by grant ID'), which cleanly separates it from siblings like zitadel_create_user_grant and zitadel_list_user_grants without needing to name them.

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

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

Gives one hard prerequisite ('Requires confirm: true'), which is genuinely useful, but offers no when-to-use vs. alternatives guidance and no exclusions — e.g. it never distinguishes itself from revoke_org_manager or offboard_user, which also remove access.

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?

Adds beyond annotations: the last-ORG_OWNER guard is a concrete safety constraint and the confirm:true requirement is a behavioral contract. Annotations already flag destructiveHint and idempotentHint, so this supplements with operational detail. Slightly short on what happens on guard failure.

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

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

Three short sentences, front-loaded with the action, then the default behavior, then the guard and confirm requirement. No filler.

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

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

Covers purpose, omissible roles, safety guard, and confirm. Lacks detail on error behavior if guard triggers or required auth level, but sufficient for correct invocation given schema and annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the semantic of omitting roles (removes entire manager membership) and the confirm gate, which enriches understanding beyond raw field descriptions.

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?

Specific verb (revoke) + resource (org-level manager role) + object (user). Clearly distinguished from its inverse sibling zitadel_grant_org_manager and from zitadel_remove_user_grant.

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?

States behavior when roles are omitted, but gives no explicit when-to-use vs alternatives or prerequisites (e.g., admin permissions needed). Usage is implied rather than 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false): it explains the read-deep-merge-write mechanics, that only supplied keys change and other overrides/defaults survive, the org-level default scope affecting every app tied to the org, and the IAM-level grant needed for instance scope. That is exactly the behavioral context an agent needs before mutating shared login text.

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?

Dense but front-loaded, leading with what is overridden and the critical scope warning before mechanics. Some clauses (the JSON example, the deep-merge explanation) are long, but each carries actionable information rather than filler.

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

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

For a mutation tool with no output schema, the description covers scope, merge semantics, idempotency, permissions, and per-call granularity. The only omission is any indication of the return payload or error behavior, which is minor given the annotations.

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 already 100%, but the description adds real meaning: the flat dot-path key format mirroring apps/login/locales/<locale>.json, a concrete example, placeholder support like {failedAttempts}, and the defaulting/grant semantics of the level parameter. This exceeds the baseline 3 for fully documented schemas.

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

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

States a precise verb+resource+scope: overriding Login V2 / hosted login texts for a locale via the Settings v2 API. It also distinguishes itself from the legacy Management 'Custom Login Texts' path, which an agent could otherwise pick by mistake.

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

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

Gives clear when-to-use context (the correct lever for the new login) and an explicit when-not (legacy Management custom texts are ignored by it), plus operational guidance to set one locale per call and repeat per language. It does not name the sibling get_hosted_login_translation as the read counterpart, which is the only notable gap.

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

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

Annotations provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false, indicating it's a non-destructive, idempotent mutation. The description adds value by specifying it unlocks 'a previously locked user account,' clarifying the precondition, but doesn't mention side effects (e.g., user regains access), permissions required, or rate limits. No contradiction with annotations exists.

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

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

The description is a single, direct sentence with zero waste—it immediately states the tool's action and target. It's appropriately sized for a simple tool and front-loaded with essential information, 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 mutation tool with no output schema and rich annotations, the description is minimal but covers the core action. It lacks details on return values, error conditions, or broader context (e.g., how unlocking integrates with other user states), making it adequate but incomplete for full agent 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, with 'userId' clearly documented. The description doesn't add any parameter-specific details beyond the schema, such as format examples or constraints, so it meets the baseline for high schema coverage without extra 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 clearly states the action ('Unlock') and resource ('a previously locked user account'), making the purpose evident. It distinguishes from siblings like 'zitadel_lock_user' by specifying the opposite action, though it doesn't explicitly mention other user management tools like 'zitadel_deactivate_user' or 'zitadel_reactivate_user' for full differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't specify prerequisites (e.g., the user must be locked first), exclusions (e.g., cannot unlock a deleted user), or compare to related tools like 'zitadel_reactivate_user' for deactivated users, leaving usage context unclear.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety and repeatability profile is covered. The description adds no behavioral context beyond that—it does not state that this is a partial update, what permissions are required, or what happens to omitted fields (that detail lives in the schema, not the description).

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 with no filler; the verb and resource lead immediately. It is appropriately sized, though the parenthetical list is partly redundant with the schema.

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?

Annotations plus a fully documented schema mean an agent can invoke this correctly. However, the description omits the partial-update nature of the operation and required permissions, which are meaningful for a mutation tool even with rich structured fields.

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

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

Schema description coverage is 100%, so all 11 parameters including the enum and the 'omit to keep current' semantics are already documented in the schema. The description only echoes a few field names (redirect URIs, grant types) without adding meaning, so the baseline 3 applies.

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

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

States a specific verb (Update) and resource (OIDC application's configuration) and names representative fields (redirect URIs, auth method, grant types). It clearly distinguishes the mutation intent from siblings like zitadel_create_oidc_app or zitadel_get_app, though it never names those siblings explicitly.

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

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

The description gives no when-to-use guidance, no prerequisites (e.g., the app must already exist), and no routing to alternatives such as create_oidc_app for new apps or get_app for reads. Usage is only implied by the word 'Update'.

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