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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral detail beyond that: results are newest-first, and each event carries both an ISO timestamp and raw epoch seconds, which matters for parsing. It omits rate limits or pagination/truncation behavior at the 50-event cap.

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, no filler, and the most decision-relevant content (what events, where from, ordering) is front-loaded before the return-format note. Every clause earns its place.

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

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

With no output schema, the description usefully describes the return shape (event categories, dual timestamp format, newest-first ordering), which compensates well. Authentication needs and the 50-event cap's implications are left to the schema and annotations, leaving only minor gaps.

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

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

Schema description coverage is 100%, so all four parameters (sid, event_type, num_events, from_timestamp) are already fully documented in the schema, including defaults, ranges, and the 50-event cap. The description adds no parameter-level detail, 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 ('Get') and resource ('recent events recorded by the base station'), then enumerates the event categories returned (arm/disarm, sensor opens, lock/unlock, alarms, errors) and the sort order. This is precise enough that an agent can distinguish it from state-listing siblings like simplisafe_list_sensors or simplisafe_get_system.

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 its usage context (retrieving recent event history, newest first) but never states when to prefer it over siblings such as simplisafe_get_system or simplisafe_list_sensors, nor any exclusions or prerequisites. Usage is inferable from purpose rather than explicitly 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?

Goes well beyond annotations by disclosing that PINs are live alarm codes, returned in cleartext, and become part of the conversation – a critical side effect. It also explains the two-step confirmation fallback and when data is actually fetched, matching and enriching the destructive/openWorld hints.

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 first states the core purpose, and the second contains the essential security/confirmation warning. All content earns its place; there is 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 sensitive read with no output schema, the description covers safety, confirmation flow, token semantics, and data exposure. An agent has enough to call it correctly and handle the fallback path.

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 input schema already covers both parameters fully (100% coverage), so the baseline is 3; the description adds meaningful behavior around confirmToken (phase-1 preview, no fetch, repeat call with token). It does not add extra meaning for sid, but none is needed.

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 action ('Read') and resource ('system's user PINs'), listing the categories (master, duress, named users) so an agent can distinguish it from sibling get/list tools. No ambiguity about what it retrieves.

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?

Makes clear this is the tool for reading PINs and provides the confirmation workflow for both supported clients and the fallback path. It does not explicitly name alternatives or when-not-to-use, but none of the siblings serve the same purpose, so the context is sufficient.

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 and openWorldHint, so the safety profile is covered. The description adds real content beyond that by scoping the returned data (settings plus wifi/cellular signal, wall power, backup battery, RF jamming) and by declaring what is deliberately omitted (PINs).

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, no filler, front-loaded with the core purpose before the field enumeration and the exclusion. 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?

With no output schema, the description compensates by enumerating the returned settings and health signals, and it covers the one ambiguity risk (PINs). Nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100% and the single sid parameter is fully documented in the schema, including the optional-when-single-system rule. The description adds nothing about the parameter, 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 (Get) and resource (base-station settings) and then enumerates the actual settings and health fields returned, so an agent knows exactly what comes back. The explicit exclusion of PINs and the pointer to simplisafe_get_pins distinguishes it from a plausible sibling.

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

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

Gives an explicit negative boundary ('Does not include PINs — use simplisafe_get_pins for those'), which routes the agent to the right alternative for the adjacent use case. It does not distinguish this from simplisafe_get_system, which is the other obvious confusion risk, so it falls 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a non-mutating call against an external service. The description usefully adds what state is actually surfaced (including pending base-station messages), but says nothing about auth requirements, rate limits, or freshness of the returned snapshot. With annotations carrying the safety profile, this is adequate but not rich.

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

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

One sentence, front-loaded with the verb and scope, with the returned-state list following. No filler, no repetition of the tool name, and every clause conveys information.

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

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

There is no output schema, and the description compensates by enumerating the state categories returned, which is the key thing an agent needs to decide whether to call it. The only gap is operational context such as whether the snapshot is cached or how it differs from get_settings/get_events.

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 sid parameter is fully documented there, including the optional-when-one-system / required-when-many rule. The description adds nothing about sid, so the baseline 3 for schema-covered parameters is correct.

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

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

States a specific verb (get) and resource (one SimpliSafe system's current state), then enumerates the exact fields returned: alarm state, alarming flag, base-station connectivity, power/battery, and pending messages. This distinguishes it from siblings like simplisafe_list_systems (enumeration) and simplisafe_get_settings (configuration) without needing to open 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?

Usage is only implied: the agent can infer it should call this for a live status snapshot of a single system. There is no explicit when-to-use guidance, no mention of how it relates to simplisafe_get_settings, simplisafe_get_events, or simplisafe_healthcheck, and no note about polling or staleness.

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 cover readOnly and openWorld, and the description adds real context beyond them: it authenticates to SimpliSafe, verifies the refresh token is configured and working, and summarizes account state. It stops short of describing failure/report formats or rate-limit behavior, but the auth and connectivity semantics are well disclosed.

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, each earning its place: what it checks, what it returns, and when to invoke it. The invocation guidance is front-loaded after the purpose statement.

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 compensates by enumerating the reported fields (token status, user id, active system count). For a zero-parameter read-only diagnostic with annotations covering safety, nothing an agent needs is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. No parameter information is needed or missing.

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 (check) and resource (server authentication/API reachability) and enumerates exactly what it reports: refresh token status, resolved user id, and active system count. This is clearly distinguishable from the sibling list/get/set tools, none of which are diagnostics.

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?

"Start here when other tools fail" gives an explicit trigger condition that routes the agent to this tool first on failure. It does not name specific alternatives or exclusions, but for a diagnostic entry point the when-to-use guidance is concrete.

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 and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: the default fresh re-poll of the base station, the cost of that poll, and the fact that readings can be stale if force_update is disabled. It stops short of noting rate limits or multi-system 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?

Three sentences, front-loaded with what is returned and followed by the one non-obvious behavior (default polling). The quoted rationale is slightly chatty but earns its place by justifying the default. 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?

With no output schema, the description compensates by enumerating the returned fields and the key `serial` identifier. Annotations cover the read-only profile, and the parameter contract is documented in the schema, so 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 description coverage is 100%, so both `sid` and `force_update` are fully documented structurally, which sets the baseline at 3. The description reinforces the fresh-poll default for `force_update` but adds no syntax, format, or edge-case detail the schema lacks.

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 smart locks on a system') plus exactly what each entry contains: state (locked/unlocked/jammed), lock and keypad battery, and keypad connectivity. It also cross-references the sibling it feeds into by naming the `serial` that simplisafe_set_lock_state consumes, which differentiates it from simplisafe_list_sensors and friends.

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 freshness tradeoff explicitly ('Polls the base station fresh by default, because a stale answer to "is my door locked?" is worse than a slow one') and tells the agent when to override it. It does not name an alternative tool for cached reads or state any exclusions, so it falls just short of the explicit when/when-not/alternatives bar.

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 openWorldHint=true, so safety and network reach are covered. The description usefully discloses that battery, offline and triggered status are returned, but adds nothing about auth, rate limits, or the cost implied by `force_update` polling beyond what the schema says.

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 core action and resource before the filter hint. It is efficient, though the long device-type enumeration could be trimmed without losing meaning.

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 carries the burden of describing what comes back and it does list the status fields. Combined with a fully-covered input schema and read-only annotations, an agent has enough to invoke it correctly; only the relationship to list_locks and pagination/count behavior is unaddressed.

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 four parameters, including sid optionality and force_update behavior. The description only reinforces `type_name` with a couple of extra example values ('motion_v2'), a marginal addition over structured data — 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?

The description states a specific verb ('List') and resource ('sensors and devices paired to a system'), then enumerates the covered device classes and the returned status fields. It is distinguishable from siblings like simplisafe_list_systems and even clarifies it covers locks, which overlaps with simplisafe_list_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?

It explains the filtering use case via `type_name` and names example values, which implies when to narrow results. However, it never states when to prefer this tool over simplisafe_list_locks or simplisafe_get_system, and gives no exclusions or prerequisites — the usage context is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. Because there is no output schema, the description usefully carries the return-value burden by naming the fields surfaced per system (alarm state, alarming status, connectivity, power) and the sid hand-off to downstream tools.

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

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

Two tight sentences with no filler. The capability statement comes first and the routing hint ('Start here...') is front-loaded at the end of the opening sentence pair, so both key facts are immediately visible.

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

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

For a parameterless read-only list tool with no output schema, the description covers purpose, returned fields, and the sid hand-off well. It omits any note on account scoping, pagination, or behavior when no systems exist, which are minor gaps.

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

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

The tool takes zero parameters, so the schema has nothing to document and the baseline for this dimension is 4. The description correctly adds no parameter guidance, which is appropriate here.

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 SimpliSafe systems on this account') and enumerates what is returned: alarm state, alarming status, connectivity, power. The 'Start here' clause distinguishes it from siblings like simplisafe_get_system and simplisafe_list_sensors, so an agent can tell them apart without opening schemas.

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 positions this as the entry point: 'Start here to get the `sid` other tools take', which tells the agent when this tool is the right first call. It does not name an alternative to avoid or state exclusion conditions, so it stops 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?

The description goes well beyond annotations by disclosing the two-phase confirmation flow, the confirmToken fallback, the physical consequences of disarming or arming, and the post-execution verification. This gives the agent critical risk awareness that readOnlyHint and destructiveHint alone would not provide. No contradiction with annotations was found.

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 front-loaded with the core action and states, then adds necessary warnings and confirmation behavior. Every sentence carries meaning: what the states mean, how confirmation works, what consequences are, and what happens after execution. No filler or redundancy.

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

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

For a destructive, physically impactful tool with 3 parameters and no output schema, the description covers the essential context: target states, confirmation requirements, token fallback, real-world consequences, and verification after execution. An agent has enough to invoke it safely and 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. The description adds meaning beyond the schema by explaining 'home' as 'perimeter only' and 'away' as 'all sensors', and it reinforces the confirmToken lifecycle. These additions are useful but modest compared to the already-detailed schema descriptions.

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 opens with a specific verb phrase, 'Arm or disarm the alarm system', and enumerates the three target states with their meanings. It is clearly distinct from siblings like simplisafe_set_lock_state and the read-only get/list tools.

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 makes it clear this tool is for changing alarm state, and its confirmation and consequences imply it should be used deliberately rather than casually. It does not explicitly name alternatives or state when not to use it, but the purpose is unambiguous enough that an agent can select it correctly.

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?

Beyond the annotations, it discloses that the tool prompts for user confirmation, that unlocking physically opens a door lock, that the fallback requires a phase-1 preview and confirmToken before a repeat call proceeds, and that results are verified by re-reading lock state. These details materially affect how an agent sequences calls and are not derivable from readOnlyHint or destructiveHint alone. No contradiction with 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?

Four sentences, each earning its place: core operation, confirmation protocol, security rationale for gating, and post-execution verification. The confirmToken mechanics are dense and reference external MCP_CONFIRM_MODE, but the structure is front-loaded and efficient.

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 gated mutation with no output schema, the description covers the essential behavioral contract: confirmation modes, physical consequences, token reuse rules, and verification behavior. The main gap is the exact response shape of phase-1 and phase-2 beyond 'preview and confirmToken,' but the reference to MCP_CONFIRM_MODE partially fills that.

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 schema already documents all four parameters, so the baseline is 3. The description adds significant semantics for confirmToken: it must come from the same tool's phase-1 response, only after explicit user approval, never on the first call, never invented, and never reused. This is critical guidance beyond the schema's field descriptions.

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 opens with a specific verb and resource, 'Lock or unlock a SimpliSafe smart lock,' which makes the operation unambiguous and distinguishes it from siblings like simplisafe_set_alarm_state. The follow-up detail about confirmation and verification does not blur the core purpose.

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 gives clear procedural context for the confirmation flow and the confirmToken fallback, and it makes clear that unlocking is gated. However, it never explicitly names alternative tools or states when not to use this tool, so an agent must infer that alarm-related changes belong to simplisafe_set_alarm_state.

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