Zitadel MCP

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.2
Disambiguation5/5
Every tool has a clearly distinct purpose targeting specific resources and actions in the Zitadel domain. For example, user management tools like create_user, deactivate_user, lock_user, and unlock_user each handle different states without overlap, and tools for applications, projects, roles, and service accounts are well-separated. The descriptions reinforce these distinctions, making misselection unlikely.
Naming Consistency5/5
All tools follow a consistent 'zitadel_verb_noun' pattern with snake_case throughout, such as zitadel_create_user, zitadel_list_projects, and zitadel_update_app. This predictability makes it easy for agents to understand and navigate the toolset without confusion from mixed conventions or styles.
Tool Count3/5
With 25 tools, the count is on the higher side and may feel heavy for the Zitadel identity management scope, potentially overwhelming agents. While it covers many operations, a more streamlined set could improve usability without sacrificing functionality, placing it in the borderline range for appropriateness.
Completeness5/5
The toolset provides comprehensive CRUD and lifecycle coverage for Zitadel's domain, including users, applications, projects, roles, and service accounts. It handles creation, retrieval, listing, updating, and deletion/deactivation for key resources, with no obvious gaps that would cause agent failures in typical identity management workflows.
Average 3.7/5 across 25 of 25 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- Last stable release on March 1, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-destructive, idempotent mutation (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds minimal behavioral context beyond this—it specifies what aspects of the app can be updated but doesn't mention permissions needed, rate limits, or what happens to unspecified fields (e.g., are they preserved or reset?).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. Every word contributes to understanding the tool's function without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 8 parameters and no output schema, the description is minimal. Annotations cover safety (non-destructive, idempotent), but the description lacks context on error conditions, response format, or dependencies. It's adequate given annotations but leaves gaps for operational use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The description mentions 'redirect URIs, auth method, etc.', which loosely maps to some parameters but doesn't add meaningful semantics beyond what the schema already provides (e.g., clarifying 'auth method' isn't a direct parameter). Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('OIDC application's configuration'), with specific examples of what can be updated ('redirect URIs, auth method, etc.'). It distinguishes from creation tools like 'zitadel_create_oidc_app' by specifying 'Update', but doesn't explicitly differentiate from other update operations on the server.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 app), when not to use it, or how it relates to sibling tools like 'zitadel_get_app' for checking current configuration before updating.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover basic traits (non-readOnly, non-idempotent, non-destructive), and the description adds useful context about validation behavior. However, it doesn't disclose additional details like authentication requirements, rate limits, error conditions, or what happens on duplicate grants, which would enhance transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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 a key behavioral trait (validation). It's front-loaded with the main purpose and avoids unnecessary details, making it highly concise and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 moderate complexity (3 parameters, validation logic), the description is adequate but not complete. It covers the purpose and validation but lacks details on return values, error handling, or prerequisites, which would help an agent use it more effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing clear documentation for all parameters. The description adds minimal value beyond the schema by implying validation for 'roleKeys' but doesn't elaborate on semantics like role key formats or project defaults. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Assign roles to a user by creating a grant') and resource ('user'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'zitadel_create_project_role' or 'zitadel_remove_user_grant', which would require more specific language about scope or operation type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning validation ('Validates that the roles exist in the project before granting'), suggesting it should be used when assigning existing roles. However, it lacks explicit guidance on when to choose this tool over alternatives like 'zitadel_create_project_role' (for creating roles) or 'zitadel_remove_user_grant' (for revoking grants), leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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 no additional behavioral context (e.g., pagination, rate limits, or authentication needs), but doesn't contradict annotations. With annotations present, the bar is lower, and the description adds minimal value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part earns its place by clearly stating the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (list operation), rich annotations covering safety, and no output schema, the description is reasonably complete. It could improve by hinting at output format or filtering behavior, but it adequately conveys the tool's intent without being overly verbose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description mentions 'specific user' aligning with userId but adds no further semantic context beyond what the schema provides. With high schema coverage, the baseline is 3, and the description doesn't compensate with extra details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('role grants for a specific user'), specifying it shows assigned roles. It distinguishes from general user listing tools but doesn't explicitly differentiate from sibling 'zitadel_list_users' or 'zitadel_list_project_roles' in terms of scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to see a user's assigned roles, but provides no explicit guidance on when to use this versus alternatives like 'zitadel_get_user' for basic info or 'zitadel_list_project_roles' for role definitions. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a non-read-only, idempotent, non-destructive operation. The description adds value by specifying the key format for app-specific roles, which is behavioral context not covered by annotations. It doesn't contradict annotations, as 'create' aligns with readOnlyHint=false, but could provide more on permissions or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and includes a specific usage tip. There's no wasted text, and it's appropriately sized for the tool's complexity, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations cover safety and idempotency, and the schema fully describes parameters, the description is reasonably complete. However, without an output schema, it could benefit from hinting at the return value (e.g., the created role object), though the concise nature still supports effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 adds minimal semantics by mentioning the key format for 'roleKey,' but doesn't elaborate on other parameters like 'projectId' or 'group.' This meets the baseline for high schema coverage without significant added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 role') and resource ('in a Zitadel project'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from its sibling 'zitadel_list_project_roles' or other creation tools like 'zitadel_create_project', leaving room for improvement in sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage guidance by specifying 'Use key format "app:{slug}" for app-specific access roles,' which implies when to use this format. However, it lacks explicit guidance on when to use this tool versus alternatives like 'zitadel_list_project_roles' for viewing roles or other creation tools, and doesn't mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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 valuable behavioral context by specifying what gets returned (Client ID and Client Secret for confidential clients) and mentioning key configuration aspects like redirect URIs, which helps the agent understand the tool's behavior beyond the basic annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences. The first sentence states the core purpose and return value, while the second mentions configuration aspects. It's front-loaded with the most important information, though the second sentence could be slightly more specific about what 'response types' and 'grant types' refer to.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 and comprehensive schema coverage, the description provides adequate context. It mentions the return values (Client ID/Secret) which is important since there's no output schema. The main gap is lack of explicit guidance on when to use this versus update or get operations, but overall it's reasonably complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema already documents all 7 parameters thoroughly. The description adds minimal parameter semantics by mentioning redirect URIs, response types, and grant types configuration, but doesn't provide additional details beyond what's in the schema. 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.
Purpose5/5
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 OIDC application'), the target resource ('in a Zitadel project'), and the return value ('Returns the Client ID (and Client Secret for confidential clients)'). It distinguishes from sibling tools like 'zitadel_create_project' or 'zitadel_create_user' by specifying OIDC application creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning configuration of redirect URIs, response types, and grant types, but doesn't explicitly state when to use this tool versus alternatives like 'zitadel_update_app' or 'zitadel_get_app'. No prerequisites or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose4/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-readonly, non-idempotent, non-destructive operation. The description adds valuable behavioral context beyond annotations by disclosing that 'An invitation email will be sent automatically so the user can set their password' - this explains a side effect that isn't captured in the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that both earn their place. The first states the core purpose, and the second provides critical behavioral context about the invitation email. There's no wasted verbiage or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 but no output schema, the description provides adequate context. It explains the core action and a key behavioral consequence (email invitation). While it doesn't detail response format or error conditions, it covers the essential information needed to understand what this tool does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema already documents all three parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline expectation without providing additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 human user') and resource ('in Zitadel'), distinguishing it from sibling tools like 'zitadel_create_service_user' by specifying 'human user' rather than service user. It provides a complete, unambiguous purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning the automatic invitation email, which suggests this is for onboarding human users. However, it doesn't explicitly state when to use this versus alternatives like 'zitadel_create_service_user' or provide any exclusion criteria or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, repeatable read operations. The description adds value by clarifying the scope ('all roles') and giving examples, but it does not disclose additional behavioral traits like pagination, rate limits, or authentication needs beyond what annotations cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List all roles defined in a Zitadel project') and includes helpful examples without unnecessary elaboration. Every word contributes to clarity, making it appropriately sized and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 idempotency, and no output schema, the description is largely complete. It could be improved by mentioning the return format or any limitations, but it adequately supports agent understanding for a read-only list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'projectId' fully documented in the schema. The description does not add any parameter-specific information beyond what the schema provides, such as format details or default behavior implications, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List all roles') and resource ('defined in a Zitadel project'), with concrete examples ('admin', 'app:finance') that help distinguish it from sibling tools like 'zitadel_list_projects' or 'zitadel_list_users'. It precisely communicates what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the resource context ('in a Zitadel project'), but it does not explicitly state when to use this tool versus alternatives like 'zitadel_get_project' or 'zitadel_list_user_grants'. There is no guidance on prerequisites, exclusions, or specific scenarios for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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 by specifying that 'confirm: true' is required to execute and that omitting it allows previewing the action. This clarifies the tool's safety mechanism and preview behavior, enhancing transparency beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that are front-loaded and waste-free. The first sentence states the purpose, and the second provides critical usage guidance, with every word earning its place to aid the AI agent efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a destructive operation with a confirmation mechanism, the description is reasonably complete. It covers the purpose and a key behavioral trait (confirm requirement). However, without an output schema, it does not describe return values or potential errors, and it could benefit from more context on when to use versus siblings, slightly limiting completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, providing clear details for userId, grantId, and confirm parameters. The description adds minimal semantics by emphasizing the requirement for 'confirm: true', but does not elaborate further on parameter meanings or usage beyond what the schema already documents, aligning with the baseline score for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Remove a role grant from a user') and identifies the resource ('by grant ID'), distinguishing it from sibling tools like 'zitadel_delete_user' or 'zitadel_deactivate_user' which affect the user entity differently. It precisely communicates what the tool does without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage with 'Requires confirm: true', indicating a prerequisite for execution. However, it does not explicitly state when to use this tool versus alternatives like 'zitadel_list_user_grants' for viewing grants or other user management tools, nor does it specify exclusions or edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![zitadel-mcp MCP server](https://glama.ai/mcp/servers/takleb3rry/zitadel-mcp/badges/card.svg)](https://glama.ai/mcp/servers/takleb3rry/zitadel-mcp)

Score Badge

Copy to your README.md:

[![zitadel-mcp MCP server](https://glama.ai/mcp/servers/takleb3rry/zitadel-mcp/badges/score.svg)](https://glama.ai/mcp/servers/takleb3rry/zitadel-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/takleb3rry/zitadel-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server