database_roles_listList custom database roles in a cluster to review role-based access and support database user administration, with optional namespace filtering and pagination.
List custom database roles
Role administration uses the database-users RBAC resource.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| cluster | Yes | ||
| namespace | No |
Changes observed during successful MCP inspections.
v0.4.3Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds one sentence regarding RBAC resource usage, providing valuable architectural context beyond the annotations. However, it does not disclose operational behaviors such as pagination limits or specific failure modes, keeping the score moderate.
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, but the first sentence is a simple restatement of the title, offering no functional value that wasn't already captured in the name and title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a listing tool involving a 'cluster' and 'namespace' parameter, the description is incomplete. It doesn't explain the scope of the listing (e.g., does it list globally, or is it limited to a namespace?) beyond what is already implied by the inputs.
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 0%, and the description fails to add any meaning to the four input parameters (cluster, namespace, limit, cursor). It does not explain what criteria define these custom roles relative to the provided schema fields.
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 repeats the title and clearly states the tool's function (list custom roles). However, it does not differentiate these 'custom' roles from other specific database roles listed among the siblings, like postgres_roles_list, making the scope slightly ambiguous.
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 minimal guidance on when to use this tool. It only states the core function without comparing it against alternatives like database_role_get or database_users_list, leaving the user to infer usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.