kinde

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

Annotations already declare destructiveHint=true, so the safety bar is lower. The description adds genuinely useful context: that roles/permissions can optionally be attached on join, that the effect is reversible by removing the user, and the underlying API endpoint. It does not address auth requirements or duplicate-membership behavior, and the 'reversible' framing sits in slight tension with the destructive hint.

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

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

Three short sentences, purpose front-loaded, with the optionality and reversibility notes placed early. The trailing endpoint reference is mildly redundant but consistent with the service's style and costs little.

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

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

For a simple two-parameter tool with fully documented schema and no output schema, the description covers purpose, optional fields, and reversibility. It omits idempotency/duplicate-membership behavior and permission requirements, which are minor gaps rather than blockers.

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

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

Schema description coverage is 100%, so org_code, users, roles, and permissions are already documented in the schema. The description only restates that roles and permissions are optional, adding no syntax or format detail beyond what the structured fields provide. Baseline 3 applies.

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

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

States a specific verb (add), resource (users), and scope (to an organization), plus the qualifier that only existing users can be added and roles/permissions may be attached. This clearly separates it from siblings like kinde_list_organization_users and kinde_grant_user_role_in_organization.

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 word 'existing' implies a prerequisite (the user must already exist), and the tool is implicitly the batch membership operation, but there is no explicit when-to-use/when-not or named alternative (e.g., grant_user_role_in_organization for single-role grants). Usage is only lightly implied.

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

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

Annotations carry only destructiveHint=true, so the description must bear most of the behavioral burden. It adds only the raw endpoint (POST /api/v1/organization) and says nothing about required auth/scopes, what happens with duplicate names or external_id, or what is returned. No contradiction with the mutation annotation, but very thin disclosure for a write tool.

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

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

Two compact sentences, front-loaded with the action and resource, with no filler. The trailing API-endpoint restatement is redundant but small.

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

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

For a create tool with no output schema and minimal annotations, the description omits the returned organization identifier and error behavior, which the agent needs to chain into siblings like kinde_add_users_to_organization. The surviving gaps are significant given how little structured data compensates.

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

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

Schema description coverage is 100%, with name, external_id, and feature_flags all documented in the schema. The description adds no parameter-level meaning (e.g., external_id uniqueness or feature-flag value format), so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a new organization'), and usefully disambiguates the domain term with '(tenant)'. It is clearly distinguishable from create_permission/create_role by resource, though it does not explicitly contrast with any sibling.

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

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

There is no guidance on when to create an organization versus using an existing one, no prerequisites, and no mention of alternatives such as kinde_get_organization or kinde_list_organizations. The agent must infer usage entirely.

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

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

Annotations supply only destructiveHint=true and a title, so the description carries nearly the full burden. It adds the REST endpoint (POST /api/v1/permissions), which is contextual but not behavioral: it says nothing about key uniqueness/collision behavior, whether creation is idempotent, required scopes, or what happens to the permission on failure. No contradiction with annotations, but little added 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.

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

Two short sentences with the purpose front-loaded; nothing is bloated or buried. The endpoint reference ('Kinde: POST /api/v1/permissions') is marginal filler for an agent but costs little.

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

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

For a simple create with full schema coverage and no output schema, the minimum is arguably met: resource, scope of use, and endpoint are stated. Still missing are the behavioral facts an agent would need to call it safely (uniqueness of 'key', failure/repeat behavior), which the annotations do not cover.

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

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

Schema description coverage is 100% (key, name, description all documented), so the schema already carries parameter meaning and a baseline 3 applies. The description adds no syntax, format, or constraint detail about the three fields beyond what the schema states.

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

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

The description states a specific verb and resource ('Create a permission') and even clarifies that permissions are held by roles and users, which helps distinguish it from kinde_create_role. It stops short of explicitly naming the sibling tools or the boundary between them, so it is clear but not fully differentiated.

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

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

There is no statement of when to use this tool versus alternatives such as kinde_create_role or kinde_create_organization, nor any prerequisites (e.g., whether the key must be unique or whether the permission must later be granted). The only hint is the phrase 'roles and users can hold', which implies downstream use but gives no actionable routing guidance.

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

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

The description adds nothing beyond the name and the raw HTTP endpoint ('POST /api/v1/roles'). It does not mention uniqueness constraints on 'key', permissions required to create a role, whether re-creating an existing role errors, or what happens to existing users. The annotation only carries destructiveHint, so behavioral gaps remain.

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

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

Two short sentences with the action front-loaded; every clause is readable at a glance. The trailing 'Kinde: POST /api/v1/roles' is mildly redundant but cheap and provides endpoint context.

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

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

With 100% schema coverage and no output schema, the description needs only to convey purpose and any behavioral caveats. Purpose is covered, but for a mutation tool with a destructive annotation and no return-value docs, the absence of any note on side effects or required scopes leaves it merely adequate.

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

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

Schema description coverage is 100% – all four parameters (key, name, description, is_default_role) are documented in the schema itself, so baseline 3 applies. The description adds no param-level meaning beyond the schema, e.g. no note that 'key' must be unique or immutable.

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

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

States a specific verb and resource ('Create a role') and clarifies the lifecycle purpose ('can then be granted to users'), which separates it from read/list siblings. It does not explicitly distinguish itself from kinde_create_permission or kinde_create_organization, so it lands at clear-but-undifferentiated.

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

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

The phrase 'that can then be granted to users' implies the role's downstream use, but there is no guidance on when to create a role versus a permission, nor any prerequisites or preconditions. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context about what the payload contains (client id, login URLs), but says nothing about permissions required, error behavior for unknown ids, or auth scope.

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

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

Two short sentences, with the purpose and payload contents front-loaded. The trailing endpoint reference ('Kinde: GET /api/v1/applications/{application_id}') is mildly redundant for an agent but aids API mapping without bloating the text.

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

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

With no output schema, the description usefully names the key returned fields, and annotations cover the read-only nature. It is adequate for a single-parameter read tool, though it omits error/not-found behavior.

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

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

Schema description coverage is 100% for the single application_id parameter, so the schema fully documents it. The description's 'by id' phrasing is consistent but adds no format, source, or constraint detail beyond the schema.

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

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

States a specific verb (Fetch), resource (a single application), and lookup key (by id), and it enumerates payload highlights (client id, login URLs). This clearly differentiates it from the sibling kinde_list_applications.

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

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

The phrase 'a single application by id' implies the retrieval-by-identifier use case and contrasts implicitly with the list sibling, but there is no explicit when-to-use, prerequisites, or named alternative. Usage is inferable rather than stated.

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

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

readOnlyHint=true already establishes the safe-read profile, and the description adds useful context beyond it: the result is scoped to the token's own business, the call is cheap/low-risk, and it doubles as a credential/audience check. It doesn't discuss error behavior for invalid tokens, but the added value over annotations is real.

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

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

Two tight sentences, front-loaded with the verb and result, followed by the practical motivation. The trailing REST endpoint note is compact and no sentence is wasted.

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

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

With no parameters and no output schema, the description carries the return-value burden itself and discharges it by naming the three fields returned plus the token scoping. Nothing an agent needs to call this correctly is missing.

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

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

Zero parameters, so per the baseline this scores 4. There is nothing for the description to disambiguate, and it correctly makes no parameter claims.

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

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

States a specific verb and resource ("Fetch the Kinde business") and immediately enumerates the returned fields (name, industry, timezone). No sibling competes for this resource — the other get_* tools target applications, organizations and users — so the agent can route here unambiguously.

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?

"A cheap way to confirm the credentials and audience are right" gives a concrete usage context: a low-cost connectivity/identity sanity check. It stops short of explicit when-not-to-use or naming alternates, but the intended trigger is clear.

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

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

With readOnlyHint=true already declaring the safety profile, the description's added value is limited to naming the underlying endpoint (GET /api/v1/organization), which merely corroborates the read-only annotation. It says nothing about error behavior for an unknown org code or what the response contains.

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

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

Two short sentences, the core action front-loaded, and the endpoint reference appended without padding. No sentence is wasted.

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

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

For a one-parameter read the description covers invocation adequately, but with no output schema it never indicates what an organization object returns (fields, nesting). That leaves a modest but real gap for such a simple tool.

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

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

Schema description coverage is 100% and the single parameter already documents the org_1234abcd format. The description's 'by its org code' adds no syntax, format, or lookup detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Fetch') and resource ('a single organization'), and the word 'single' implicitly distinguishes it from the sibling kinde_list_organizations. It does not explicitly name that sibling, so it stops short of a 5.

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

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

The phrase 'by its org code' implies the precondition (you must already have a code) and the singular framing implies you use it for one record rather than a listing. However, no alternative tool is named and no when-not guidance is given, so usage is only implied.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the API endpoint and that expansion returns organizations and identities, but says nothing about pagination, error behavior for missing ids, or response size.

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

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

Two tight sentences, front-loading the core action and scope, with the endpoint reference appended as a compact provenance note. No wasted words.

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

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

For a simple two-parameter read with no output schema, the description conveys the core return concept (a user, optionally with organizations and identities). It is nearly complete, missing only error or not-found behavior.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description restates that expand can pull organizations and identities, adding mild emphasis but no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (fetch) and resource (a single user) scoped by id, which implicitly distinguishes it from kinde_list_users. It does not explicitly name the sibling, so differentiation relies on inference rather than an explicit contrast.

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 requirement of an id implies you must already know the user, which hints at when to use this over a list tool, but no alternative is named and no exclusions are given. Usage is implied rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the backing REST endpoint, which is mildly useful for tracing, but says nothing about pagination, result ordering, or what an empty list means.

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

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

Two short sentences, front-loaded with the purpose, plus a compact endpoint reference. No filler or redundancy.

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

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

For a simple two-parameter read tool with full schema coverage and no output schema, this is adequate but thin: it never describes the shape of the returned permission list (permission ids, names, pagination), which an agent must guess at.

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

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

Schema description coverage is 100% (user_id and org_code are both documented in the schema), so the baseline is 3. The description adds no format, encoding, or lookup guidance beyond what the schema already supplies.

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

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

States a specific verb ('List'), resource ('permissions'), and precise scope ('one user holds in one organization'), which cleanly distinguishes it from siblings such as kinde_list_permissions (all permissions) and kinde_get_user_roles_in_organization (roles, not permissions).

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 'one user / one organization' scoping implies when to use it over the broader list_permissions sibling, but no alternative is named and there are no explicit when-not conditions or prerequisites. Usage is inferable rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the underlying GET endpoint, reinforcing read-only semantics, but says nothing about pagination, response shape, or whether only direct (non-inherited) roles are returned — a meaningful ambiguity for a roles lookup. Modest value beyond annotations.

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

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

One tight sentence plus the endpoint reference. The scope constraint and purpose are front-loaded with zero filler.

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

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

For a simple two-param read with no output schema, the definition is nearly sufficient. The only gap is that it never hints at the returned structure (array of roles, direct vs inherited), which an agent might want, but this is minor given the tool's simplicity.

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

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

Schema description coverage is 100% for both parameters (user_id, org_code), so the schema already carries the parameter meaning. The description adds no format or syntax detail beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb (List/sense of 'get') and resource (roles), with precise scope: one user in one organization. This cleanly separates it from kinde_list_roles (global) and kinde_get_user_permissions_in_organization (permissions, not roles) without needing to open any schema.

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

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

The phrase 'the direct answer to what can this person do here?' implies when the tool is useful, but there is no explicit when-not guidance and no named alternative (e.g., use kinde_get_user_permissions_in_organization for permission-level grants). Usage is implied rather than stated.

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

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

Annotations only declare destructiveHint=true, so the description's 'Reversible.' is genuinely additive context about the mutability profile, and the raw endpoint adds a little. However, it omits idempotency (what happens on a repeat grant), whether the permission must already exist in the organization, and authorization requirements for a mutating call.

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

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

Three short front-loaded statements: action, reversibility, endpoint. Nothing redundant and no filler.

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

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

For a simple 3-parameter mutation with no output schema, the description covers the action, the reversibility profile, and the underlying endpoint. The remaining gap is failure/precondition behavior (nonexistent permission, duplicate grant), which is real but modest.

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

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

Schema description coverage is 100%, so the schema already documents user_id, org_code, and permission_id. The description adds no format, ID-source, or lookup detail beyond the schema's own one-line descriptions, so baseline 3 is correct.

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

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

States a specific verb (give/grant), resource (permission), and both scoping dimensions (one user, one organization). This cleanly distinguishes it from sibling kinde_grant_user_role_in_organization and from the read-side kinde_get_user_permissions_in_organization without opening either schema.

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

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

No when-to-use guidance and no alternatives named, despite near-identical siblings (kinde_grant_user_role_in_organization, kinde_add_users_to_organization) that an agent could easily confuse it with. The only usage-adjacent content is the 'one user / one organization' scoping constraint.

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

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

Annotations only supply destructiveHint=true, so the description usefully adds that the operation is reversible via kinde_revoke_user_role_in_organization and identifies the underlying POST endpoint, confirming a state-mutating authenticated API call. It adds real context without contradicting the destructive hint (a grant is reversible yet still a state change).

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

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

Two short sentences plus an endpoint reference; the operation is front-loaded and every clause (scope, reversibility, API path) carries distinct information.

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

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

For a simple three-parameter mutation with no output schema, the description plus annotations and a fully documented schema cover what an agent needs. The only gap is that no return value is described — acceptable given there is no output schema, and no prerequisites (e.g. existing role) are mentioned.

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

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

Schema description coverage is 100% with all three required parameters documented inline, so the schema already carries the parameter burden. The description only restates the user/org cardinality and adds nothing about id formats or lookup sources — baseline 3 applies.

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

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

States a specific verb+resource combination ('give one user a role within one organization') with explicit scoping to a single user/org pair, which distinguishes it from the sibling 'kinde_grant_user_permission_in_organization' by resource type and from 'kinde_add_users_to_organization' by cardinality.

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

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

Usage is implied by the verb and the named undo path, but there is no explicit when-to-use guidance, no prerequisites (e.g. role must already exist via kinde_create_role), and no statement of when the permission-granting sibling is preferred.

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

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

The readOnlyHint=true annotation already establishes the safe-read profile, so the description does not need to restate that. It adds the concrete upstream endpoint (GET /api/v1/apis) and the token-audience semantics, but says nothing about pagination, result size, or ordering—the main behavioral unknowns for a list endpoint.

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

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

Two short clauses with zero padding, and the core purpose is front-loaded before the endpoint detail. Nothing could be removed without losing information.

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

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

For a no-parameter list operation with no output schema, the description covers purpose, resource meaning, and the underlying call. The only material omission is pagination/result-set behavior, which an agent would want to know before relying on full results.

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

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

The tool takes no parameters (empty object schema with 100% coverage), so there is nothing for the description to compensate for; the baseline of 4 applies. The description correctly implies an unfiltered listing rather than suggesting optional arguments.

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

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

States a specific verb and resource ("List the APIs") and adds domain meaning by clarifying that these APIs are "registered as token audiences," which disambiguates the resource from the many other listable resources. It does not explicitly contrast with siblings like kinde_list_applications, but the resource noun is distinct enough to route correctly.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. However, with zero parameters this is an unconditional enumerate-everything call, so the usage is largely self-evident from the description; a 3 reflects implied rather than stated guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the underlying REST mapping (GET /api/v1/applications), which is useful for traceability, but says nothing about pagination behavior, result ordering, or volume despite three paging-related parameters.

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

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

A single tight sentence with scope front-loaded; the trailing endpoint reference is compact and arguably useful, with no filler or redundancy.

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

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

No output schema exists, so return values need not be described, and annotations carry the read-only profile. The main gap is that pagination semantics are left entirely to the schema, which is acceptable for this simple, zero-required-parameter list tool.

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

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

Schema description coverage is 100%, so sort, page_size, and next_token are fully documented in the schema. The description adds no parameter-level meaning beyond what the schema already provides; baseline 3 applies.

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

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

States a specific verb (List) and resource (applications), plus a scope qualifier ('registered in the business, with their types'). The singular sibling kinde_get_application is implicitly differentiated by the plural/list framing, though the description never names that alternative.

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

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

There is no explicit when-to-use guidance: nothing says to prefer this over kinde_get_application for a single lookup, or when to page with next_token. Usage is only implied by the verb 'List'.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description's GET endpoint restates that rather than adding behavior. It does add that values are returned alongside the flags, which is mild extra context, but says nothing about pagination, ordering, or freshness. With annotations carrying the safety profile, a 3 is appropriate.

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

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

Two short sentences, zero filler, with the scope-defining qualifier front-loaded before the API citation. Every clause earns its place.

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

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

For a parameterless read-only lister with no output schema, the description conveys the resource, the scope, and that values are included. A brief note on pagination or result shape would make it airtight, but nothing essential to calling it is missing.

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

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

The tool takes 0 parameters, so per the baseline this scores 4. There is nothing for the description to disambiguate, and the empty schema is consistent with the described operation.

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

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

States a specific verb (List) and resource (feature flags) plus the scope qualifier 'at the environment level', which cleanly separates it from the sibling kinde_list_organization_feature_flags. An agent can pick the right scope without opening either schema.

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

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

The scope phrase implies when this tool applies (environment-scoped flags), but there is no explicit when-to-use guidance, no exclusions, and no named alternative such as kinde_list_organization_feature_flags for organization-level flags. Usage must be inferred.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds genuinely useful context that goes beyond annotations: the result is the set of overrides for the org, not the full effective flag list, which affects how an agent interprets the output. It does not mention pagination, ordering, or empty-result behavior.

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

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

Two short sentences, front-loaded with the purpose and followed by the backing API route. Nothing is wasted, though the second sentence is a bare API reference whose value to an agent is marginal.

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

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

For a one-parameter read-only list tool with a fully covered schema and a readOnlyHint annotation, the definition supplies enough to call it correctly. The main remaining gap is absence of any hint about the returned shape or pagination, which is acceptable given no output schema is declared.

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

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

Schema description coverage is 100% and the single org_code parameter is documented in the schema as 'The organization's code.' The description adds no format, example, or source-of-value guidance for org_code, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the feature-flag overrides') scoped to one organization, and the phrase 'overrides set for one organization' implicitly separates it from the environment-level sibling kinde_list_environment_feature_flags. It stops short of naming that sibling explicitly, so differentiation requires the agent to infer it.

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 scoping phrase 'for one organization' implies when this tool applies (org-specific overrides rather than environment-level flags), but it never states when to prefer this over kinde_list_environment_feature_flags or any prerequisites for having overrides. Usage must be inferred rather than read.

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

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

The readOnlyHint annotation already declares this a safe read, so the description carries a lower burden, but it adds almost nothing behavioral beyond the resource scope. It does not disclose pagination behavior (next_token), result limits, or return shape for a list tool.

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

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

Two short front-loaded sentences with the purpose first and the API endpoint appended. The endpoint reference is marginally useful but borders on filler.

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

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

For a simple read-only list tool with no output schema, the description is close to adequate, but it omits pagination guidance despite a next_token parameter, and gives no routing among the many list siblings. A brief note on cursor paging would complete it.

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

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

Schema description coverage is 100% with three optional parameters (sort, page_size, next_token) fully documented in the schema. The description adds no parameter meaning, so the baseline 3 is correct.

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

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

States a specific verb+resource ('List the organizations') and adds the clarifying synonym '(tenants) in the business', so the object is unambiguous. It does not, however, explicitly distinguish it from the singular kinde_get_organization sibling, leaving that differentiation to inference.

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

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

There is no guidance on when to use this versus kinde_get_organization or the many other list_* siblings, and no mention of prerequisites or pagination context. It only restates what the tool does.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description confirms a GET endpoint, but says nothing about pagination flow, result shape, or ordering despite a next_token/page_size cursor mechanism being present.

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

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

Two front-loaded sentences: purpose and filters first, endpoint path last. No redundant or filler content.

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

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

For a six-parameter paginated list tool with no output schema, the description is thin: it does not explain pagination behavior, ordering semantics, or what a returned user record contains. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so all six parameters including sort, roles, permissions, and next_token are documented in the schema. The description only restates the role/permission filter idea, adding no syntax beyond the structured 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?

States a specific verb (List) and resource (users) scoped to one organization, plus the optional role/permission filters. This implicitly separates it from kinde_list_users and the get_user_* siblings, though it never names an alternative explicitly.

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

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

The description's 'belonging to one organization' plus optional filters implies when to reach for it, but there is no explicit when-to-use/when-not guidance or pointer to kinde_list_users for environment-wide listing.

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

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

Annotations already declare readOnlyHint=true, so the safe read-only nature is covered. The description adds only the upstream endpoint (GET /api/v1/permissions) and nothing about pagination behavior, ordering, or result size, which is the more useful missing context for a cursor-paginated list tool.

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

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

Two short sentences, no filler, with the resource scope front-loaded ahead of the endpoint reference. Every clause earns its place.

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

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

For a read-only paginated list with no output schema and three optional parameters, the description is adequate but thin. It never tells the agent that results are paged via next_token or what a permission entry contains, information an agent would need to chain calls correctly.

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

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

Schema description coverage is 100%, so sort, page_size, and next_token are fully documented in the schema itself. The description adds no syntax or format hints beyond that, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (permissions) with scope ('defined in the business'), which separates it from kinde_list_role_permissions and create_permission. It stops short of explicitly naming the sibling it differs from, so an agent must infer the business-level vs role-level distinction from phrasing alone.

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

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

The phrase 'defined in the business' implicitly signals the business-level permission catalog as opposed to role-scoped permissions, giving an implied use case. However, there is no explicit when-to-use, when-not-to-use, or named alternative, leaving the choice between this and kinde_list_role_permissions to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main addition is the API endpoint mapping (GET /api/v1/roles/{role_id}/permissions). It does not describe pagination behavior despite page_size/next_token params, nor return shape. Adequate given annotation coverage, but not rich.

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

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

Two short sentences with zero filler, purpose front-loaded before the endpoint reference. Every element earns its place.

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

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

For a read-only list tool with full schema coverage and no output schema, the description supplies enough to invoke correctly. The only missing piece is explicit pagination/return guidance, which the params largely cover.

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

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

Schema description coverage is 100%, so role_id, page_size, and next_token are already documented in the schema (including the 1-100 bound and cursor semantics). The description adds nothing beyond the schema, so the baseline 3 is correct.

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

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

States a specific verb (list) and resource (permissions) and narrows scope to 'one role', which implicitly distinguishes it from kinde_list_permissions (all permissions) and kinde_list_roles. It is clear, though it never names the sibling endpoints an agent might confuse it with.

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

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

No when-to-use guidance, no exclusions, and no mention of the closely related kinde_list_permissions or kinde_get_user_permissions_in_organization alternatives. The agent must infer from the name alone which listing scope applies.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. The description adds only the API mapping (GET /api/v1/roles); it says nothing about pagination behavior despite the next_token parameter, and nothing about whether results are tenant- or business-scoped beyond the phrase 'in the business'.

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

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

Two short sentences, front-loaded with the purpose; nothing is padded. The endpoint reference is mildly redundant but harmless and cheap.

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

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

A read-only list tool with fully documented parameters and annotations covering safety needs little more, and no output schema exists so return values need not be explained. Still, pagination semantics and the exact scope of 'roles' (vs. role permissions) are left unstated, leaving minor gaps.

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

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

Schema description coverage is 100% – sort, page_size, and next_token are all documented in the schema with ranges and format hints. The description contributes no additional parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the roles defined in the business') and even names the underlying endpoint, so the agent knows exactly what is returned. It does not, however, differentiate itself from adjacent siblings like kinde_list_role_permissions or kinde_list_permissions, which an agent could easily confuse with this one.

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

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

No guidance on when to use this tool versus alternatives such as kinde_list_role_permissions or kinde_get_user_roles_in_organization. The description just states the operation; the agent must infer selection from the name alone.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds nothing beyond that — no note on pagination behavior via next_token, no auth/permission requirements, no indication of what fields a subscriber carries.

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

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

Two short fragments, purpose front-loaded, nothing bloated. The endpoint reference is largely redundant for an agent that never issues raw HTTP, but it costs little.

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

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

A simple read-only list tool with full schema coverage and a safety annotation needs only modest prose. The absence of any pagination or result-shape note (no output schema exists) leaves a minor gap, but the definition is minimally sufficient.

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

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

Schema description coverage is 100%, so sort, page_size, and next_token are fully documented in the schema. The description adds no parameter meaning, which is acceptable at this coverage level but earns only the baseline.

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

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

States a specific verb ('List') and resource ('marketing subscribers'), and the 'marketing' qualifier distinguishes it from the many user/role/permission list siblings. It does not explicitly name a sibling, but the resource is unambiguous.

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

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

Provides no when-to-use guidance, no exclusions, and no routing to alternatives such as kinde_list_users. The only context is a raw REST endpoint, which does not help an agent choose the tool.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered by structured data. The description adds the underlying REST endpoint, which aids traceability, but says nothing about pagination flow or result limits despite next_token/page_size being present.

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

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

Two short sentences, zero padding, with the core action front-loaded and the endpoint reference appended. Nothing could be removed without losing information.

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

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

For a read-only list tool with no output schema and full schema description coverage, the description covers the essential action and endpoint mapping. The only omission is describing the pagination loop, though the schema's next_token description largely compensates.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, making 3 the baseline. The description only echoes the email and user_id filters and adds no syntax or format detail beyond what the schema provides for expand, page_size, or next_token.

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

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

States a specific verb and resource ('List users in the business') plus an optional narrowing scope, and maps to a concrete endpoint (GET /api/v1/users). It does not explicitly distinguish itself from the closest sibling, kinde_list_organization_users, so it stops short of a 5.

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

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

No when-to-use guidance is given. The phrase 'optionally narrowed by email or user id' faintly implies this is the enumeration path versus kinde_get_user, but the description never states when to prefer it over list_organization_users or get_user, nor any prerequisites.

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