RemoteLock MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds genuinely non-structured facts: the reply contains the PIN, and times are interpreted in the lock's local time zone. The 'WRITE:' prefix is redundant with the 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?

Three short sentences, front-loaded with the mutation intent, then the constraint, then the follow-up routing. The 'WRITE:' prefix and the raw 'POST /access_persons' endpoint add little for an agent but are not costly.

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 stating the reply includes the PIN. Combined with the full schema coverage, an agent has enough to call this correctly; only the guest-vs-user distinction is left implicit.

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 in the schema, including PIN generation and local-time formatting. The description reinforces the local-time semantics of starts_at/ends_at but supplies no additional syntax or constraints, 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 ('creates an access guest') and defines the scope precisely: a PIN/card valid only between starts_at and ends_at. This clearly separates it from remotelock_create_access_user and from granting access.

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 routes the agent: 'It creates the person only; use remotelock_grant_access to give them doors.' That is a real when-to-use-which-tool statement. It does not state when to prefer this over remotelock_create_access_user, which is the adjacent sibling.

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 'WRITE:' prefix and 'The reply includes the PIN' disclose the mutation and a non-obvious output consequence, and the duplicate warning signals the non-idempotent behavior declared in annotations. It stops short of covering auth/permission prerequisites or whether the PIN is retrievable later. Annotations already cover the safety profile, so this is a solid additive disclosure rather than a gap.

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?

Four short sentences, front-loaded with the 'WRITE:' signal and the core verb+resource. Every sentence contributes: scope, the person-vs-doors boundary, the return value, the duplicate guard, and the endpoint. 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 7-param mutation with no output schema, the description covers the write, the two-step workflow, the duplicate check, and the key return value (PIN). The one omission is that the reply also presumably carries the created person's identifier needed for the follow-up grant call, which would close the loop.

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 seven parameters are already documented, including the pin/generate_pin interaction. The description adds only that a PIN and/or card are optional inputs ('with a PIN and/or card'), which the schema's required list already implies. 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 ('creates a permanent access user'), names the person categories it covers, and explicitly distinguishes scope from a sibling ('creates the person only; use remotelock_grant_access to give them doors'). An agent can separate it from remotelock_create_access_guest and remotelock_grant_access without opening 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?

Gives concrete when-to-use routing ('use remotelock_grant_access to give them doors'), a pre-call check ('Check remotelock_list_access_persons first to avoid duplicates'), and the alternative for PIN generation via the pin/generate_pin pair. No inference is required to pick this tool or a sibling.

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 flag destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the description is not the sole source of the risk profile. It still adds real context beyond them: the blast radius ('every door'), the fact the person record is retained rather than deleted, and the underlying PUT endpoint. It omits permission/auth requirements and how to undo, which keeps it short of a 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?

Three short sentences, front-loaded with 'WRITE:' and the effect, followed by the retention clarification and the endpoint. Nothing is redundant or 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?

For a one-parameter mutation with no output schema, the description covers what changes, what does not change, and the API path — enough to call it correctly. Minor gaps remain around where the ID comes from and confirmation/permission expectations.

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?

There is a single required parameter and schema description coverage is 100%, with the schema already stating it is a RemoteLock access person UUID. The description adds no format, sourcing, or lookup guidance (e.g. obtain via list_access_persons), 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?

A specific verb ('deactivates'), resource ('access user or guest') and concrete effect ('PIN/card stops working on every door') are all stated. The clause 'stays in the account (status deactivated) and is not deleted' distinguishes it from a delete operation, though it never names the closest sibling (remotelock_revoke_access) to sharpen the boundary.

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?

'Only do it when the user asked' gives a safety guardrail but not operational selection criteria. It does not tell the agent when to pick this over remotelock_revoke_access (revoking one grant) or when to prefer edit/reactivation instead, 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?

Annotations already establish that this is a read-only, non-destructive, open-world operation. The description adds useful behavioral context by stating that the response includes status, validity window, and PIN/card number, which goes beyond the annotations and 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?

The description is two compact sentences with zero wasted language. The resource and id scope are front-loaded, followed by the returned fields and endpoint.

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 one-parameter read tool with annotations and full schema coverage, the description is nearly complete and usefully lists the returned fields despite no output schema. It does not mention not-found behavior or authentication expectations, leaving a minor contextual 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?

The single parameter has 100% schema description coverage and is already documented as a RemoteLock access person UUID. The description adds no parameter-specific meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description names the specific resource ('access user or guest'), the retrieval scope ('by id'), and the endpoint ('GET /access_persons/{id}'). This clearly distinguishes the tool from sibling list and mutation tools such as list_access_persons and deactivate_access_person.

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 the tool should be used when a specific access person id is known, but the description does not explicitly say when to use this versus list_access_persons or how to obtain the id. Usage is implied rather than fully guided.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by enumerating the returned content (name, plan limits, settings) — meaningful because there is no output schema — and pinning the endpoint as GET /account.

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 purpose front-loaded and no filler. The trailing "GET /account" is marginally redundant with readOnlyHint but costs almost 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 zero-argument read tool with full annotation coverage, the description supplies purpose, return contents, and a call trigger — enough for correct invocation. The only soft spot is that it does not hint at response shape or whether limits are numeric caps versus policy text.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline applies. The credential-scoping note ("these credentials belong to") usefully implies the account is determined by auth rather than 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?

"The RemoteLock account these credentials belong to: name, plan limits and settings" names the specific resource and enumerates the fields returned, so an agent knows exactly what it gets. No sibling tool exposes account-level data, so it is implicitly distinct, but the description never uses a verb to frame the operation beyond the raw "GET /account."

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?

"Use it to confirm which account is connected" gives an explicit trigger for calling it, which is genuinely helpful context. There are no competing alternatives to rule out, so the absence of exclusions is not a real gap.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still adds real value by spelling out the state fields returned (connectivity, battery, auto-lock settings), which the annotations say nothing about. It stops short of mentioning error/not-found behavior or freshness of 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?

Two compact clauses — resource/scope and returned-state inventory — followed by the endpoint path. Front-loaded with the resource, zero filler, nothing repeated from 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?

There is no output schema, so the description carries the burden of describing the return value — and it does so concretely by listing the state categories. Combined with complete parameter documentation and read-only annotations, an agent has everything needed to call this correctly.

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

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

With a single parameter at 100% schema coverage and a schema description naming it a RemoteLock device UUID, the schema does the heavy lifting. The description only echoes 'by id' and adds no format, sourcing, or validation 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 ('get') and resource ('one device (lock) by id') and then enumerates exactly what the response contains: connectivity, battery/power, lock state, auto-lock settings, model, location. This clearly separates it from list_devices and the mutation siblings (lock_device/unlock_device).

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 — fetch a single lock when you already have its id — but there is no explicit guidance on when to prefer this over remotelock_list_devices for discovering ids, and no note about what happens with an unknown id. Adequate but with a clear gap.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds valuable non-obvious context: which fields are returned and that the PIN or card used is not returned, plus the underlying GET endpoint. It omits auth requirements and error 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 tightly written sentences plus the endpoint, with the key scoping phrase 'One event by id' front-loaded. No filler or redundant restatement.

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

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

For a simple single-resource read with annotation-backed safety, the description covers the return fields and one important exclusion. Without an output schema it does not explain error handling or why a missing or inaccessible event would look different, but it is otherwise complete enough to call correctly.

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

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

Schema coverage is 100%, and the single event_id parameter is documented as a RemoteLock UUID in the schema. The description reinforces that the id identifies one event but adds no format or syntax beyond the schema 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 and resource: fetch one event by id, and enumerates the returned fields (type, time, source, status, lock, person, method). It does not explicitly distinguish itself from the sibling list_notifications tool, but 'by id' and 'one event' make the scope clear.

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?

Says 'for example from a notification,' which implies when an agent has an event id, but it gives no explicit when-not guidance or named alternative such as list_notifications for browsing events.

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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the underlying endpoint (GET /locations/{id}), which reinforces the read nature but says nothing about auth requirements, 404 behavior for unknown ids, or rate limits.

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, both front-loaded and waste-free. Slightly telegraphic ('One location by id' lacks an article and verb), but nothing extraneous is present.

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 full schema coverage and annotations covering safety, this is close to adequate. The main gap is that no output shape is described and there is no output schema, so the agent cannot tell what a 'location' object 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 coverage is 100% and the single parameter is documented as a 'RemoteLock location id (UUID)' with length bounds. The description adds no format or sourcing guidance beyond that, 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 the verb (fetch) and resource (one location) precisely enough that an agent can distinguish it from the sibling remotelock_list_locations, which returns many. It never names that sibling explicitly, so the 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?

'One location by id' implies retrieval of a single record when the id is known, which is the implicit alternative to listing. No explicit when-to-use, when-not-to-use, or prerequisites are given.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds genuinely new behavior — that RemoteLock syncs the code down to the physical lock(s) after the call — which tells the agent about an asynchronous side effect on hardware. It stops short of saying what happens on partial sync failure or when access already exists.

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

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

Front-loaded with the write marker and the core effect, then optional parameters, then the endpoint — a sensible ordering with no wasted clauses. The guest-hours distinction is repeated from the schema, which is minor 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 6-parameter mutation with full schema coverage and annotations, the description covers purpose, side effect, and parameter distinctions adequately. The main omissions are return/response expectations and error behavior on duplicate grants, which are small given no output schema exists.

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 schema descriptions already explain guest_start_time/guest_end_time as time-of-day overrides and access_schedule_id as recurring hours. The description restates this almost verbatim, adding little beyond what the schema provides, 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 (gives access), the resource (lock, door group, location), and the observable effect (PIN/card opens it). The 'WRITE:' prefix and the endpoint line make it immediately distinguishable from read siblings and from remotelock_revoke_access.

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 grant scenario is clear and the schedule-vs-guest-window choice is explained, but there is no statement of prerequisites (the access_person_id must already exist — see create_access_user/create_access_guest) and no explicit pointer to revoke_access as the inverse. Usage is implied rather than routed.

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, openWorldHint=true and destructiveHint=false, so safety is covered; the description adds real value by disclosing the implicit status filter that silently hides expired and deactivated people unless overridden. That default-hiding behavior is the most important non-obvious trait for correct use, though result format and pagination behavior are left to the 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?

Two sentences plus the endpoint, with the resource scope front-loaded and the default/override rule second. No restatement of the title 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?

There is no output schema, so the description carries the return-shape burden and does so by enumerating the useful fields (name, email, status, validity window, PIN/card number). Combined with the default-filter disclosure and the fully documented 5-parameter schema, an agent has what it needs to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it ties 'access users (permanent)' vs 'access guests (time-limited)' to the type enum, and clarifies that status is an opt-in widening of a default rather than a required filter. Page/per_page/sort are left entirely to 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 and resource (list access persons) and immediately disambiguates the two entity kinds it returns — permanent access users vs. time-limited access guests — plus the fields included. It also names the backing endpoint (GET /access_persons), so an agent can distinguish it from list_person_accesses and list_device_accesses without opening a schema.

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

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

Explains the default scope ('only current and upcoming people') and the override path ('pass status to include expired or deactivated'), which is the main selection decision for this tool. It does not explicitly route to siblings such as get_access_person for single-record detail, so it falls short of full 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.

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

Annotations already declare read-only, non-destructive, open-world behavior. The description adds a useful behavioral detail (whether the PIN is synced) and the underlying endpoint, but says nothing about pagination, result volume, or ordering, which matters for a list operation.

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 core purpose. The endpoint reference is mildly redundant for an agent but cheap and occasionally useful for error mapping.

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?

Adequate for a simple read tool covered by annotations, but two gaps remain: no mention that results are paginated (page/per_page exist) and no differentiation from the closely named sibling remotelock_list_person_accesses.

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 device_id, page, per_page, and person_type are all documented in the schema. The description's 'users and guests' hints at person_type but adds no syntax or filtering semantics beyond what the schema already provides. Baseline 3.

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

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

States a specific verb and resource ('List the access users and guests who have access to one lock') and adds a differentiating detail about PIN sync. This implicitly contrasts with remotelock_list_person_accesses (people→locks), though the sibling is never named, so the distinction must be inferred.

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 versus remotelock_list_access_persons, remotelock_list_person_accesses, or remotelock_get_access_person. The agent has to reason about directionality (per-lock vs per-person) on its own.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context about returned device fields and the GET /devices endpoint, but does not discuss pagination behavior, rate limits, or response semantics beyond field names.

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

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

Two sentences, front-loaded with the operation and returned data, followed by filtering behavior and the endpoint. There is no filler, and every sentence contributes to invocation.

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?

The description covers device categories, returned attributes, and core filtering, which is important because there is no output schema. Pagination and sorting are left entirely to the schema, but they are well documented there, so the definition is nearly complete for correct use.

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 six parameters are already fully documented, including pagination, sorting, and type enums. The description reinforces that type and location filters exist, but adds no syntax or meaning 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?

The description states a specific verb and resource ("List devices") and enumerates the device categories and returned fields, making the scope clear. It implicitly distinguishes list from sibling get_device by verb, but does not explicitly name alternatives or boundaries.

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 tells the agent that results can be filtered by type or location, which implies typical usage. However, it does not say when to choose this over get_device or list_locations, nor does it state prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is fully covered structurally. The description adds useful domain context (what a door group is and its role in one-step access granting) but says nothing about pagination behavior, result ordering, or what a caller receives — modest added value beyond the 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?

A single sentence plus the endpoint, with the core purpose front-loaded and the explanatory parenthetical earning its place by clarifying a non-obvious domain term. 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 read-only list tool with full parameter documentation and clear safety annotations, the description covers the essential identity of the resource. It lacks any note on what a group record contains, but with no output schema that is a minor gap rather than a blocking one.

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 all three parameters (page, sort, per_page) are documented in the schema including defaults and the next_page chaining hint. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

The description pairs a specific verb ('List') with a specific resource ('door groups') and even defines the domain concept via a parenthetical ('named sets of locks you can grant access to in one step'), which disambiguates it from siblings like list_group_items or list_devices. It stops short of explicitly naming a sibling it should be preferred over, keeping it at 4 rather than 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?

Usage is only implied — an agent can infer you call this when you need door groups to grant access, but the description never states when to use it, when not to use it, or which sibling to pick (e.g., list_group_items vs list_door_groups). No explicit routing guidance is present.

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, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond restating the HTTP verb and path, which duplicates the read-only hint, and says nothing about empty groups, pagination behavior, or result ordering.

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 no filler; the resource scope comes first and the endpoint reference is a compact secondary detail.

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 paginated read endpoint with full schema coverage and complete annotations, the definition covers what an agent needs to call it. Minor gap: it never signals that results are paginated or what to do when a group is empty, though the schema implies pagination.

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%: group_id is documented as a RemoteLock door group UUID, and page/per_page include defaults and ranges plus the 'pass the previous reply's next_page' hint. The description adds no parameter meaning 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 ('List the items (locks) that belong to one door group'), which lets an agent distinguish this from remotelock_list_door_groups (lists groups, not their members). It does not explicitly contrast with remotelock_list_devices, which is the nearest ambiguous alternative for enumerating locks.

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: the parenthetical '(locks)' and the 'GET /groups/{id}/items' path make clear this is the membership lookup for a group, so an agent can infer it is used after obtaining a group_id. There is no explicit statement of when to prefer this over remotelock_list_devices or remotelock_list_door_groups.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the surface response contents (address, time zone) and the raw endpoint, which is largely redundant with readOnlyHint. Pagination behavior, which matters for a list endpoint, is left entirely to the 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?

Two short, front-loaded sentences that lead with what is listed and follow with the practical use. The trailing "GET /locations" is minor redundancy but not harmful.

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 documentation and annotations carrying the safety profile; the description covers what is returned and why. The only real gap is that pagination (following next_page) is not mentioned in prose, though the schema covers 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 page/per_page/sort each documented including defaults and the leading-dash sort convention. The description adds no parameter meaning of its own, 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 the account's locations") and disambiguates the domain term with "(properties/sites)" plus the returned fields (address, time zone). It implicitly contrasts with the singular remotelock_get_location sibling but never names 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?

"Use the ids to filter devices" gives a downstream-usage hint, which implies when you'd call this (to obtain location ids for device filtering). However, it never states when to prefer this over remotelock_get_location for a single site, nor any prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: results are scoped to active subscriptions rather than all events, and it sketches the shape of each record (lock, event type, event_id) even though no output schema exists.

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

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

Three tight sentences: purpose plus return fields first, then the filtering constraint, then the sibling route-out, then the endpoint. Nothing is repeated from the title and no sentence is 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 read-only list tool with no output schema, the description covers scope, record shape, event-type examples and the detail alternative. Minor omissions (no note about empty results when no subscription matches, no pagination hint) are covered 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%, and both parameters (page, per_page) are documented in the schema including the next_page chaining convention. The description says nothing about pagination, so it adds no meaning beyond structured data and 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 a specific verb and resource ('List notifications sent by notification subscriptions') and immediately enumerates the returned fields (lock/publisher, event type, event_id). It also differentiates itself from the sibling remotelock_get_event by pointing that tool at detail retrieval, so an agent can pick the right one without opening a schema.

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

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

States the selection condition ('Only events that match a subscription appear') and names the alternative for detail ('Get details with remotelock_get_event'). It gives clear context for use but no explicit exclusions against the many other list_* siblings (devices, locations, persons), which an agent must infer.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that each entry includes per-device sync state, which is useful context, but says nothing about result volume, pagination behavior, or error cases — with annotations carrying the safety burden, this is adequate rather than 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 compact sentences: the payload scope first, the endpoint second. No filler, no repetition of the title, and the most important information leads.

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 covers what the resource is, what it returns conceptually, and the endpoint. The only gap is the absence of any routing hint toward the inverse sibling tool, which keeps it short of 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 access_person_id, page, and per_page are all documented in the schema; baseline 3 applies. The description adds one small clarification — that the person may be an access user or a guest — but nothing about ID format or pagination semantics 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 (list) and a precise resource (doors, door groups, locations a single access user/guest can open), plus the underlying endpoint. The direction of the relationship (person -> devices) clearly separates it from the inverse sibling remotelock_list_device_accesses without needing to name 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 description implies the use case (finding what a specific person can open) but never states when to prefer it over remotelock_list_device_accesses, remotelock_get_access_person, or remotelock_list_group_items. No exclusions or prerequisites are given, so selection 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.

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true, so the safety profile is structured. The description's 'WRITE' prefix and the no-op-on-already-locked note add useful semantic reinforcement of idempotency (safe retry), but it never addresses the destructiveHint implication of locking someone out, nor what happens if the device is offline.

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 an operation-type marker, then the effect, then the idempotency caveat. The endpoint path is arguably redundant but harmless and 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 one-parameter, no-output-schema tool whose annotations already cover safety and idempotency, this covers the essentials. The remaining gap is failure behavior (offline lock, permission errors), which the agent would need when invoking it in practice.

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

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

With a single parameter at 100% schema description coverage, the schema already explains that device_id is a RemoteLock UUID. The description adds no format, source, or constraint detail beyond that, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('sends the lock command to a lock') and clarifies the real-world effect ('it locks the door'). It implicitly contrasts with the sibling unlock_device through the verb choice, though it 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?

Usage is only implied: an agent infers you call this when you want a door locked. There is no explicit statement of when to use this over remotelock_unlock_device or remotelock_grant_access, and no prerequisites such as device reachability.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false, so the description isn't carrying the safety burden alone; it still adds real value by spelling out the effect ("the person's PIN/card no longer opens that door, door group or location"), the persistence of the person, and the underlying DELETE call. It doesn't say whether the grant can be re-created or what the response contains, which keeps it at 4.

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

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

Three short sentences with the mutation type front-loaded as "WRITE:", followed by effect, guardrail, and endpoint. Nothing is redundant and the highest-value constraint appears first.

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 2-parameter, fully documented mutation with no output schema and rich annotations, the description covers what it unlocks, what it preserves, and when it is permitted. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and both properties already document themselves, including that access_id is an item id from remotelock_list_person_accesses. The description repeats that mapping but adds no format, constraint, or edge-case guidance 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 ("removes one access grant") and immediately scopes it: the grant goes, "the person itself stays." That contrast cleanly separates it from the sibling remotelock_deactivate_access_person and from remotelock_grant_access 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?

Gives an explicit precondition ("Only do it when the user asked") and points to remotelock_list_person_accesses as the source of the access_id, plus the implicit contrast that the person record survives. It never names an explicit "when not to use / use X instead" alternative, so it stops short of the top band.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by explaining the real-world effect (a door physically unlocks) and the user-consent requirement behind confirm. It does not describe the response or failure semantics for a rejected unlock, keeping it below 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?

One compact sentence with the most important signal ('WRITE, SECURITY-SENSITIVE') front-loaded, followed by the use condition, the parameter instruction, and the endpoint. No wasted 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?

For a two-parameter destructive mutation, the description covers purpose, consent gating, and the underlying endpoint. It omits any mention of the return payload or what a failed/unauthorized unlock looks like, which would be useful given there is no output schema, but the essential calling 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 coverage is 100%: both device_id (UUID) and confirm (const true) are fully documented in the schema. The description's 'set confirm to true' reinforces the consent contract but adds no format or syntax detail beyond what the schema already states, 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 ('sends the unlock command to a lock, which physically unlocks the door') plus the underlying endpoint PUT /devices/{id}/unlock. The physical-unlock consequence makes it trivially distinguishable from the sibling remotelock_lock_device.

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

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

Gives an explicit precondition ('only call it when the user explicitly asked to unlock this specific door') and a required confirmation gate. It stops short of naming the inverse sibling (remotelock_lock_device) as an alternative, so it earns a 4 rather than a 5.

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