Read Kisi places, doors, users, groups, access rights and access logs (no unlocking).
Scored across 20 tools
Each tool maps to a distinct resource+action (get_X vs list_X for group, lock, place, user; search_events vs get_event_set for pagination). The only mild overlaps (get_user vs get_current_user, list_locks vs list_group_locks) are clearly differentiated by their descriptions.
Every tool follows the same kisi_ prefix plus verb_noun pattern (kisi_get_user, kisi_list_groups, kisi_search_events). No mixing of conventions or verb styles.
20 tools is on the heavier side but earns its place given the broad access-control domain (users, groups, locks, places, cards, controllers, readers, schedules, events, role assignments). Nothing appears redundant.
The surface is almost entirely read-only (get/list/search); there are no create/update/delete operations for users, groups, locks, schedules, or cards, and no direct door actions like unlock. For an access-control management domain this is a notable gap, though read workflows are well covered.
The Kisi user the API key belongs to (id, name, email, organization). Good first call. GET /user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the returned field set (id, name, email, organization) and ties the resource to API-key identity, but says nothing about auth requirements or failure modes.
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 fragments, front-loaded with the resource definition, then usage hint, then endpoint. Every clause carries information and none 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 compensates by enumerating the returned fields (id, name, email, organization), which is exactly what an agent needs to consume the response. Nothing material is missing for such a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. It correctly avoids inventing parameter semantics that don't exist.
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 resource and scope: 'The Kisi user the API key belongs to,' which cleanly distinguishes it from the sibling kisi_get_user (fetches an arbitrary user by id). The parenthetical list of returned fields and the explicit 'GET /user' endpoint make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Good first call' gives concrete usage context — an agent knows to invoke this early to establish identity. However, it does not name an alternative or state when not to use it, so it falls short of explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read an event set from kisi_search_events: its status and events. Pass the previous page's cursor for the next page. GET /event_sets/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Events per page (default 50). | |
| cursor | No | The cursor from the previous page. | |
| event_set_id | Yes | The event set id (numeric). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds value beyond that by disclosing the pagination trait (cursor from previous page drives the next page) and the shape of the result (status plus events). It does not mention rate limits or error conditions, but credit is due for the added behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and its source tool, then the pagination mechanic. No filler and no restatement of the 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?
For a simple read-only paged GET, the description covers origin (kisi_search_events), the returned content (status and events), and the paging mechanic, while annotations cover the safety profile and there is no output schema to account for. Nothing an agent needs to call it 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?
Schema description coverage is 100%, so the schema already documents event_set_id, limit and cursor; baseline is 3. The description only restates the cursor workflow already implied by the schema's 'cursor from the previous page' and adds nothing about the default/limit behavior, so it does not exceed the structured data in a meaningful way.
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 (read an event set), and explicitly names the sibling that produces it (kisi_search_events), telling the agent exactly what this tool consumes. It also names the payload contents (status and events), so it is distinguishable from the list_* and get_* siblings without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: use this to page through an event set created by kisi_search_events, and pass the previous page's cursor to advance. It does not state when-not to use it or an alternative paging path, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One access group by id (name, description, place, member/lock counts, restrictions). GET /groups/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | The group id (numeric). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the returned-field inventory and the underlying route (GET /groups/{id}), but does not discuss auth requirements, error behavior for missing/nonexistent ids, or pagination. Modest added value on top of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two terse fragments, front-loaded with the resource and its payload, with zero filler. Slightly telegraphic (parenthetical list, bare route), but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, listing the returned fields is the right compensating detail, and annotations carry the safety semantics. Only minor gaps remain (error handling for invalid ids), so it is essentially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the sole parameter's schema description already says 'The group id (numeric)'. The description adds no format, range, or lookup guidance beyond that, so the baseline 3 holds.
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 ('One access group by id') and even enumerates the returned fields (name, description, place, counts, restrictions), which tells an agent exactly what it gets. It differentiates from kisi_list_groups by the 'by id' singular framing, though it never names the sibling 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 'by id' phrasing implies this is for fetching a single known group versus listing, but there is no explicit when-to-use, when-not, or named alternative. Usage is left to inference from the singular/plural split in the tool set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One lock/door by id: online/unlocked/locked-down state, place, floor, settings. GET /locks/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| lock_id | Yes | The lock id (numeric). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds the HTTP verb/path and the set of state fields returned, which is modest extra context; it says nothing about error behavior for missing ids or freshness of the state values.
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, and the core resource is front-loaded before the returned fields. The telegraphic fragment style ('One lock/door by id: ...') is compact but slightly clipped rather than fully polished.
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 and only one parameter, the description usefully enumerates the returned state fields and identifies the endpoint, which is enough for an agent to call this correctly. It could add a note on what happens when the id does not resolve, but the essential information is present.
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 a single required parameter fully documented as 'The lock id (numeric)'. The description's 'by id' adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"One lock/door by id" states a specific verb (retrieve) and resource (lock/door), and the enumerated fields (online/unlocked/locked-down state, place, floor, settings) confirm it is a single-entity fetch. It implicitly distinguishes itself from kisi_list_locks via 'one ... by id', but never names that sibling 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 'by id' phrasing and the closing 'GET /locks/{id}' imply when this is used (single-record lookup by identifier), but there is no explicit statement of when to choose this over kisi_list_locks or kisi_list_group_locks, and no prerequisites or exclusions given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The current Kisi organization (name, domain, settings summary). GET /organization.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered and the description does not contradict it. The description adds the return-field summary (name, domain, settings summary) plus the underlying GET /organization endpoint, which is useful for a tool without an output schema, but it says nothing about auth requirements, rate limits, or scoping.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence plus the endpoint reference; every element earns its place and nothing is padded. The resource is stated before the parenthetical details.
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 singleton getter with annotations covering read-only safety, the description supplies the resource identity and a summary of returned fields, which is what an agent needs since there is no output schema. Only minor gaps remain (unknown whether the response is scoped by API key/tenant, no auth note).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema carries no parameter semantics to document and the baseline of 4 applies. Nothing in the description misleads about inputs, and there are no fields an agent could get wrong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (get) and resource (the current Kisi organization), and parenthetically names the kind of data returned (name, domain, settings summary). It is distinguishable from siblings like kisi_get_current_user or kisi_get_group by resource, though it never explicitly contrasts itself with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: it is the singleton-organization getter with no parameters, so an agent can infer it is the general-purpose org lookup. There is no explicit when-to-use guidance, no prerequisite/concurrency notes, and no named alternative (e.g. vs. kisi_get_current_user).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One place by id, including lockdown state. GET /places/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| place_id | Yes | The place id (numeric). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds one piece of behavioral value — that the response includes lockdown state — but says nothing about pagination, error behavior, or authorization beyond what the endpoint path implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the resource and scope front-loaded before the endpoint reference. Nothing padded, though the endpoint string is arguably redundant with the tool name.
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 single-parameter read tool with annotations covering the safety profile, this is close to complete, and the lockdown-state hint partially compensates for the missing output schema. However, with no output schema the description could say more about what a place record contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: place_id is typed as a positive integer with that stated in the schema itself. The description only restates 'by id' and adds no syntax, range, or format detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('One place by id') and contrasts implicitly with the sibling list tool kisi_list_places by specifying a single record. It also names the underlying endpoint. It stops short of explicitly routing the agent away from kisi_list_places, but the singular scope 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?
'One place by id' implies the usage condition (you already have a numeric place id and want a single record), but there is no explicit when-to-use guidance or exclusion relative to siblings like kisi_list_places. Adequate but inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One user by id. GET /users/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | The user id (numeric). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing beyond that — no note on permissions, missing-user behavior, or response scope — so it earns little credit beyond the GET path.
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 terse fragments with no filler and the key qualifier ('one user', 'by id') front-loaded. It is telegraphic rather than well-formed prose, which slightly limits readability but wastes nothing.
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 single-parameter read tool with annotations covering safety and a fully documented schema, the essentials are present. With no output schema, however, an agent gets no hint about what a user record contains or what happens for an unknown id.
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 is fully documented in the schema (numeric, positive). 'By id' merely restates the schema, so the baseline 3 applies with no added format or constraint detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (retrieve a single user) and constrains it to lookup by id, which implicitly distinguishes it from kisi_list_users. It does not name the sibling explicitly, 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?
There is no statement of when to use this versus kisi_list_users or kisi_get_current_user. The 'by id' phrasing implies you need a known numeric id, but that condition is left for the agent to infer rather than being stated as guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List access cards with status (activated/deactivated/unassigned), assignee and last use. GET /cards.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Comma-separated list of ids to fetch. | |
| sort | No | Sort by last use. | |
| limit | No | Max results to return (1-250). | |
| offset | No | Results to skip (offset paging; use pagination.next_offset). | |
| status | No | Filter by status. | |
| user_id | No | Only cards of this user. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful value beyond that by disclosing the return data shape (status, assignee, last use) in the absence of an output schema, plus the underlying endpoint. It still omits pagination/rate-limit behavior, which the schema only partially hints at.
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 resource and returned fields front-loaded; nothing is padded. The trailing "GET /cards" is marginal filler for an MCP agent 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?
For a 6-parameter, all-optional list tool with full schema coverage and annotations covering safety, the description supplies the one thing structured data lacks — the fields returned by each card. Pagination semantics live in the schema (pagination.next_offset referenced in offset), so little is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents ids, sort, limit, offset, status, and user_id thoroughly. The description only echoes the status enum values, adding no syntax or behavioral detail beyond the schema — baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ("List") and resource ("access cards") and even enumerates the returned attributes (status, assignee, last use), so the agent knows exactly what it gets back. It does not explicitly differentiate itself from siblings, but "cards" is a distinct resource from locks, users, groups, etc., so disambiguation is easy.
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 when-to-use or when-not-to-use guidance, no mention of prerequisites or alternatives, and no statement about filtering behavior beyond what the schema already lists. The listing intent is only implied by the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Kisi controllers (door hardware hubs) with online/offline status. Filter by place, lock or status. GET /controllers.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (1-250). | |
| query | No | Free-text search over name, device id and token. | |
| offset | No | Results to skip (offset paging; use pagination.next_offset). | |
| status | No | Filter by status. | |
| lock_id | No | Only the controller of this lock. | |
| place_id | No | Only controllers in this place. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safe read-only profile is structured data, not description value. The description adds only that results carry online/offline status; nothing about permissions, throttling, or result shape.
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 clauses, front-loaded with what the resource is before the filtering options. The trailing 'GET /controllers.' is marginally useful for agents mapping to the REST surface but is slight 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 full schema coverage and annotations carrying the safety profile, the description is sufficient. Pagination is only hinted at through the schema's offset description, and there is no output schema, but nothing critical to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters (limit, query, offset, status, lock_id, place_id) are already documented in the schema. The description restates three of the filters without adding syntax or format detail, so 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 ('Kisi controllers') and usefully glosses the domain term as 'door hardware hubs', which helps an agent distinguish it from kisi_list_readers and kisi_list_locks. It does not explicitly name those siblings, so differentiation is implied rather than stated.
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 'Filter by place, lock or status' implies when the tool is useful, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many list_* siblings. Usage is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All event type names usable as the type filter of kisi_search_events (e.g. lock.unlock). GET /events/types.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context beyond that: the shape/format of the values returned (e.g. lock.unlock) and the underlying endpoint GET /events/types, which tells the agent this is a static, org-level enumeration.
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 clauses: the payload's purpose and an example value, followed by the endpoint reference. Front-loaded with the highest-value information and no wasted wording.
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, and the description compensates by giving an example value format so the agent knows what the returned strings look like. Nothing critical is missing for a zero-parameter enumeration tool, though it could note that the list is complete/static.
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 nothing needs documenting and the schema is trivially complete; baseline is 4. The description appropriately says nothing about parameters because there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb and resource: it returns the set of event type names, and it explicitly ties them to the type filter of kisi_search_events. The example value (lock.unlock) and the endpoint reference make the purpose unambiguous relative to siblings like kisi_search_events or kisi_list_presences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the context of use: these names are what you feed into kisi_search_events' type filter, which is an explicit routing to the sibling tool. It does not state any when-not-to-use condition, but for a static enumeration helper that is largely unnecessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The locks/doors an access group opens. GET /group_locks?group_id=.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (1-250). | |
| query | No | Free-text search over lock name. | |
| offset | No | Results to skip (offset paging; use pagination.next_offset). | |
| group_id | Yes | The group id (numeric). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the GET endpoint mapping, consistent with the read-only annotation, but says nothing about pagination behavior, result volume, or what the returned lock objects contain.
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 with no filler, and the core resource statement is front-loaded. The trailing 'GET /group_locks?group_id=.' is a truncated endpoint snippet that contributes little, but the overall footprint is tight.
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 four-parameter read tool with full schema coverage and annotations covering safety, this is adequate but thin. With no output schema, the description could say what the returned locks include (name, place, door state) and confirm pagination, neither of which it addresses.
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 limit, query, offset, and group_id are all documented in the schema itself (including the pagination.next_offset hint on offset). The description only repeats group_id via the URL template, adding no syntax or format 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?
The description names a specific resource and relationship: 'the locks/doors an access group opens', which is more informative than the bare tool name because it conveys the group-to-lock mapping. It does not, however, explicitly distinguish itself from the sibling kisi_list_locks (all locks) or explain how the two differ.
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 kisi_list_locks, kisi_get_lock, or kisi_list_groups, and no exclusions or preconditions beyond the implicit required group_id. The REST endpoint string hints at the call shape but provides no selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List access groups (who-can-open-what bundles of doors). Filter by place or by a lock to see which groups open that door. GET /groups.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Comma-separated list of ids to fetch. | |
| sort | No | Sort order. | |
| limit | No | Max results to return (1-250). | |
| query | No | Free-text search over group name. | |
| scope | No | Organization-wide or place-scoped groups. | |
| offset | No | Results to skip (offset paging; use pagination.next_offset). | |
| lock_id | No | Only groups that include this lock. | |
| place_id | No | Only groups of this place. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds only the HTTP route ('GET /groups'), and says nothing about pagination behavior, result volume, or ordering defaults that would deepen behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with purpose, then the filtering semantics, then the endpoint. There is essentially no padding; the trailing 'GET /groups' is only mildly redundant.
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 endpoint with full schema coverage and no output schema, the description covers what the resource is and how the two key filters work, which is adequate to call it correctly. Remaining gaps (sorting/paging behavior, result shape) are minor and largely handled by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all eight parameters (ids, sort, limit, query, scope, offset, lock_id, place_id) are already documented in the schema. The description's mention of filtering by place or lock is only a partial restatement of place_id/lock_id and adds no syntax or format 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+resource ('List access groups') and even glosses the resource ('who-can-open-what bundles of doors'), which helps an agent understand the domain object. It does not explicitly contrast with the single-item sibling kisi_get_group or with kisi_list_group_locks, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The sentence 'Filter by place or by a lock to see which groups open that door' gives implied usage for the place_id and lock_id filters, but there is no guidance on when to prefer this tool over kisi_get_group, kisi_list_group_locks, or the other list endpoints, and no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List locks/doors with their state: online, unlocked, locked_down, configured, place and floor. Filter to find offline or locked-down doors. GET /locks.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Comma-separated list of ids to fetch. | |
| sort | No | Sort order. | |
| limit | No | Max results to return (1-250). | |
| query | No | Free-text search over lock name. | |
| offset | No | Results to skip (offset paging; use pagination.next_offset). | |
| online | No | Filter by online (true) / offline (false). | |
| floor_id | No | Only locks on this floor. | |
| place_id | No | Only locks in this place. | |
| unlocked | No | Filter by currently unlocked (true) / locked (false). | |
| configured | No | Filter by whether the lock is configured. | |
| locked_down | No | Filter by lockdown state. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds value the annotations do not: it enumerates the state attributes present in each returned lock and maps the tool to GET /locks, which matters because there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with what is listed and returned, followed by the filter use case and the HTTP mapping. No filler, no restatement of the title beyond the parenthetical door clarification.
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 11 optional parameters fully documented in the schema and annotations covering the read-only safety profile, the description only needs to supply the response shape, which it does by listing state fields. It stops short of describing pagination behavior, though the offset parameter already points at pagination.next_offset.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 11 parameters (ids, sort, limit, query, offset, online, floor_id, place_id, unlocked, configured, locked_down) are already documented in the schema. The description only gestures at filtering generally without adding syntax, defaults, or interaction rules (e.g. combining filters), 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 ('List locks/doors') and enumerates the state fields returned (online, unlocked, locked_down, configured, place, floor), so the agent knows exactly what this returns. It is implicitly distinguishable from the singular sibling kisi_get_lock and from kisi_list_readers/controllers, though it never names those siblings directly.
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?
'Filter to find offline or locked-down doors' gives one concrete use case, which implies the tool's role in auditing/remediation workflows. However, it offers no explicit when-not guidance and does not route the agent to alternatives like kisi_get_lock for a single door or kisi_list_group_locks for group-scoped views.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List places (sites/buildings) in the organization with address, time zone and lock/member counts. GET /places.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Comma-separated list of ids to fetch. | |
| sort | No | Sort order. | |
| limit | No | Max results to return (1-250). | |
| query | No | Free-text search over place name. | |
| offset | No | Results to skip (offset paging; use pagination.next_offset). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, which fully covers the safety profile. The description adds the returned field set (address, time zone, lock/member counts) and the underlying endpoint, but says nothing about pagination behavior, result caps, or organization scoping. With annotations carrying the safety burden, 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?
A single dense sentence front-loads the verb and the clarifying parenthetical, with no filler. The trailing 'GET /places' adds a modest amount of value as an API mapping but is arguably redundant.
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 five-parameter, optional-args list tool with no output schema, the description usefully enumerates the main returned fields, which compensates for the missing response schema. It omits pagination semantics and list-vs-get routing, leaving a small but real gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so ids, sort, limit, query, and offset are all documented in the schema itself. The description contributes only the implicit 'in the organization' scope and does not explain parameter interaction (e.g., ids vs query). Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List places') and disambiguates the domain term by equating a place with sites/buildings, then names the fields returned. It does not explicitly differentiate from the sibling kisi_get_place, which is the one distinction an agent could get wrong here, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no statement of when to prefer kisi_get_place for a single place, and no mention of how the filter/paging parameters should be combined. The imperative 'List places' only weakly implies usage, and no exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who was present at a place on a given day (derived from unlocks): actor, first/last unlock, last door. GET /presences.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | The day: a date (2026-10-08) or an RFC 3339 date-time with offset (2026-10-08T09:00:00+02:00). Kisi reads it as a day in the place's time zone; a bare date is sent as noon UTC of that day. | |
| limit | No | Max results to return (1-250). | |
| offset | No | Results to skip (offset paging; use pagination.next_offset). | |
| place_id | Yes | The place id (numeric). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by disclosing that presences are derived from unlocks and listing the returned fields. It does not cover pagination behavior or auth requirements, but it exceeds what the annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence followed by the endpoint. Every phrase earns its place: it names the subject, scope, derivation, and returned fields without filler. It is appropriately sized for a list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with full parameter documentation and safety annotations, the description is nearly complete: it states the data source and returned fields, compensating for the absence of an output schema. It omits pagination behavior, but the schema covers limit/offset with descriptions. A minor gap keeps it from 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (date, limit, offset, place_id) are fully documented in the input schema. The description only implicitly references 'place' and 'day' and does not add syntax or format details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (list/who was present), resource (presences at a place), and scope (on a given day), and adds the data derivation (derived from unlocks) plus returned fields (actor, first/last unlock, last door). This distinguishes it from sibling tools like kisi_search_events or kisi_list_users without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrase 'Who was present at a place on a given day', which signals the tool's context clearly. However, there is no explicit when-to-use, when-not-to-use, or named alternative such as kisi_search_events. It is the minimum viable guidance rather than a strong routing instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Kisi readers (card/phone readers at doors) with model and online/offline status. GET /readers.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (1-250). | |
| query | No | Free-text search over name, device id and token. | |
| offset | No | Results to skip (offset paging; use pagination.next_offset). | |
| status | No | Filter by status. | |
| lock_id | No | Only readers of this lock. | |
| place_id | No | Only readers in this place. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that readers report model and online/offline status and that it maps to GET /readers, which is useful but modest; nothing is said about pagination limits or result 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 short sentences, front-loaded with the resource identity and details. Every clause carries information and nothing is padded.
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 partially compensates by naming returned attributes (model, status), and the tool is a simple filtered list whose parameters are fully documented in the schema. Missing pagination behavior detail (offset/limit semantics are only in the schema) keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters (limit, query, offset, status, lock_id, place_id) are already documented with constraints and one enum. The description adds only an indirect nod to status via "online/offline status" and supplies no syntax or filtering guidance 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?
Names the resource precisely (readers) and even explains what a reader is ("card/phone readers at doors"), plus the fields returned (model, online/offline status) and the backing endpoint GET /readers. It does not differentiate from sibling list tools such as kisi_list_locks or kisi_list_controllers, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus alternatives, no prerequisite context, and no exclusions. The filters exist in the schema but the description never hints at scoping by lock, place, or status, so the caller gets no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who holds which role where: a user/team/guest's role on the organization, a place or a group (group members = door access). Filter by user, group, place or role. GET /role_assignments.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (1-250). | |
| query | No | Free-text search over user email and name. | |
| scope | No | Filter by scope. | |
| offset | No | Results to skip (offset paging; use pagination.next_offset). | |
| role_id | No | Filter by role id, e.g. group_basic, group_manager, place_owner, organization_administrator. | |
| user_id | No | Only assignments of this user. | |
| group_id | No | Only assignments on this group. | |
| place_id | No | Only assignments on this place. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful domain context (the role-on-scope model and the door-access equivalence) but says nothing about pagination behavior or result shape beyond what the schema already implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact clauses that front-load the core question ('Who holds which role where') before the filtering note and endpoint. Little waste, though the endpoint string 'GET /role_assignments' is decorative for an agent that cannot issue raw HTTP.
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 whose annotations carry the safety profile and with no output schema to explain, the description supplies the conceptual model (roles bound to organization/place/group, group membership equating to door access) an agent needs to route and interpret results 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 the schema already documents all 8 parameters, including enum values and pagination. The description's 'filter by user, group, place or role' only restates the filter surface at a high level and adds no syntax or format 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 resource and, crucially, the exact semantics of what it returns: 'Who holds which role where' with roles on organization/place/group. The clarification that 'group members = door access' meaningfully distinguishes this from the sibling list_groups, even though no sibling is named 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?
Usage is only implied by the phrase 'Filter by user, group, place or role' — the agent must infer that this is the tool for role/access-right queries rather than, say, kisi_list_groups or kisi_list_users. No when-to-use condition or explicit alternative is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Time rules: when a group's access is allowed, when doors auto-unlock (unlock timer), first-to-arrive, elevator permit timers. Filter by consequence or by the group/lock it applies to. GET /schedules.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Comma-separated list of ids to fetch. | |
| limit | No | Max results to return (1-250). | |
| offset | No | Results to skip (offset paging; use pagination.next_offset). | |
| consequence | No | Filter by what the schedule does. | |
| scheduleable_id | No | Id of the group/lock/elevator stop (use with scheduleable_type). | |
| scheduleable_type | No | Type of the object (use with scheduleable_id). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds genuine domain context by describing the data the schedules encode and their endpoint, but says nothing about result volume, pagination behavior beyond the schema's offset note, or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences plus an endpoint tag, with the core domain meaning front-loaded and no filler. The noun-phrase style is efficient though slightly telegraphic, which keeps it just short of ideal.
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, zero-required list tool with no output schema, the description covers what schedules are, the two filter axes, and the endpoint. It omits any mention of pagination workflow or the shape of returned schedules, which the absence of an output schema makes more noticeable.
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 every one of the six parameters carries its own schema description, including the enum meanings and the ids pairing. The description's filtering sentence loosely maps to consequence and scheduleable_id/type but adds no syntax or format detail beyond the schema, so the baseline of 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?
The description states a specific resource (schedules) and goes further by enumerating what a schedule actually is - access windows, door auto-unlock/unlock timers, first-to-arrive, elevator permit timers - which is real domain meaning beyond the title 'List schedules'. It does not explicitly distinguish itself from siblings like kisi_list_event_types or kisi_search_events, but the domain definition is strong enough for an agent to know when this tool applies.
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?
'Filter by consequence or by the group/lock it applies to' gives implied usage context for the two filtering axes, and the consequence enum values in the schema reinforce this. However, there is no explicit when-to-use, no when-not-to-use, and no named alternative among the many list_* and search_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List users (members) of the organization. Filter by group or place (users with access there), email, or free text over name/email/notes. Sort by last unlock. GET /users.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Comma-separated list of ids to fetch. | |
| sort | No | Sort order; 'unlock' = by last unlock. | |
| No | Exact email filter. | ||
| limit | No | Max results to return (1-100). | |
| query | No | Free-text search over user email, name and notes. | |
| offset | No | Results to skip (offset paging; use pagination.next_offset). | |
| group_id | No | Only members of this group. | |
| place_id | No | Only users with access to this place. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /users) and clarifies filter semantics, but says nothing about pagination limits, rate limits, or result shape beyond what schema fields already state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action before filters, sorting, and endpoint. Little waste, though the trailing 'GET /users' is of marginal value to an agent selecting the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with a fully documented schema and annotations covering safety, the description covers filtering, searching, and sorting adequately. It lacks any note on pagination behavior at the description level, but the schema's offset field carries that hint.
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 eight parameters are already documented, including the sort enum and offset paging hint. The description restates filters (group/place/email/free text) and the 'last unlock' sort without adding syntax or format detail beyond the schema, so 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 ('List users (members) of the organization') and describes the filterable dimensions. It implicitly contrasts with the singular kisi_get_user sibling, but never names it explicitly, so sibling differentiation is left 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?
The description conveys implied usage through its filter/sort enumeration, so an agent can guess how to narrow results. It gives no explicit when-to-use guidance or conditions for choosing this over kisi_get_user or other list tools, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the access log (unlocks, denied attempts, lockdowns, admin changes) and return the first page. This CREATES a temporary saved search in Kisi (an event set, cursor-paginated, kept ~24 h); it changes no door, user or access right. Defaults to the past 90 days, the maximum width. If status is still in_progress or cursor is set, call kisi_get_event_set with the returned id. POST /event_sets.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Event type(s), comma-separated, e.g. lock.unlock (see kisi_list_event_types). | |
| success | No | Only successful (true) or failed/denied (false) events. | |
| actor_id | No | Only events by this actor (e.g. a user id). | |
| interval | No | ISO 8601 interval on event time, max 90 days: start/end (2026-10-01T00:00:00Z/2026-10-08T00:00:00Z), start/duration (2026-10-01T00:00:00Z/P7D) or duration/end (P1D/2026-10-08T00:00:00Z). | |
| place_id | No | Only events at this place. | |
| object_id | No | Only events about this object (e.g. a lock id). | |
| actor_type | No | Actor type (use with actor_id). | |
| object_type | No | Object type, e.g. Lock, Place, Group, User (use with object_id). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Resolves the apparent tension between a 'search' and readOnlyHint=false by explaining it creates a temporary saved search (an event set, cursor-paginated, kept ~24 h) without mutating doors/users/rights. That is real value beyond the annotations. It stops short of stating rate limits or whether concurrent searches accumulate, so not a full 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads what it searches, then the side effect, then the default and the routing rule, with no filler sentences. The parenthetical asides and trailing 'POST /event_sets' add slight density, but every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description describes the return shape (event set id, cursor pagination, ~24 h retention) and the follow-up call, which is what an agent needs to chain correctly. The 8 parameters are fully documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the description adds a default not present in the schema (past 90 days, the maximum width) and ties the interval semantics to the cursor continuation flow. It adds genuine meaning over the field-level descriptions without re-listing every filter.
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 ('Search the access log') and enumerates the event kinds covered (unlocks, denied attempts, lockdowns, admin changes), scoping it to the first page. This clearly separates it from kisi_get_event_set, which it names as the continuation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the default window (past 90 days, max width) and the exact condition for switching tools: 'If status is still in_progress or cursor is set, call kisi_get_event_set with the returned id.' It also pre-empts misuse by noting no door, user or access right is changed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse OfficeRnD members, bookings, memberships, invoices and tickets, with optional write access.
Read PaySpace employees, organization, payroll runs, payslips and leave records. Read-only.
Read Checkout.com payments, disputes, reports and payouts.
Read Homebase locations, employees, shifts, timecards, labor costs and time clock status.
Add one secure layer between your agents and this server.