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

The annotation readOnlyHint=true covers the safety profile. The description adds meaningful behavioral details beyond the annotation: events are returned newest first, and each event includes both an ISO timestamp and raw epoch seconds. This helps the agent understand the ordering and timestamp format. It does not mention pagination limits or filtering, but those are captured in the input schema, so the description need not repeat them. 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?

The description is a single, well-structured sentence that front-loads the action and key behaviors (ordering, content) and provides useful detail about timestamps. Every clause earns its place, and there is no verbosity or redundant information. This is a model of conciseness.

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

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

Given there is no output schema, the description does the work of explaining the return format — at least the timestamp aspect. It also lists event types and order. The input schema covers parameters thoroughly, and the annotation covers safety. What is missing is a fuller description of the event object's fields (beyond timestamps) and any behavior around the num_events default or from_timestamp filtering, but those are partially in schema. Overall, it is reasonably complete for a read-only listing tool, though it could be slightly richer on the response structure.

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 all four parameters (sid, event_type, num_events, from_timestamp) are already documented with descriptions in the schema. The tool description adds no parameter-specific meaning beyond what the schema provides. Per the rubric, when schema coverage is high, the baseline is 3. No additional context is offered, so a 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 clearly states the action ('Get recent events'), the resource ('recorded by the base station'), and specifies the content (arm/disarm, sensor opens, locks, alarms, errors) plus ordering (newest first). This distinguishes it from sibling tools like simplisafe_list_sensors and simplisafe_list_locks, which target different resources. The verb is specific and 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?

The description implicitly defines when to use this tool — when you need recent event history from the base station — and lists the event categories. It does not explicitly state exclusions or alternatives, but the clear resource focus makes it obvious that this is for events rather than sensors/locks. The context from sibling names reinforces this. Slightly lacking explicit 'when not to use' guidance, but adequate.

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?

The readOnlyHint annotation already covers the read-only nature. The description adds value by listing the exact scope of returned data (settings and health) and explicitly stating what is excluded (PINs). This goes beyond annotations without contradicting them, though it doesn't discuss other behavioral aspects like error conditions 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?

The description is two sentences with no fluff. The core purpose and content are front-loaded, and the exclusion/alternative is stated efficiently at the end. Every phrase contributes value, making it highly concise and well-structured.

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?

Since there is no output schema, the description carries the burden of explaining what is returned, which it does thoroughly by listing the settings and health items. It also clarifies the scope (not PINs). The only minor gap is not addressing the relationship with simplisafe_healthcheck, but for a simple read tool, this is largely sufficient.

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

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

The input schema provides full coverage of the single parameter 'sid' with a clear description, so the baseline is 3. The tool description does not add any additional meaning or context about the parameter, leaving it 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?

The description clearly states the tool's purpose: 'Get base-station settings for a system' and enumerates the specific items included (entry/exit delays, alarm volume, etc.). It also explicitly differentiates from simplisafe_get_pins by noting what it does not include, giving strong 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 description provides an explicit exclusion and alternative for PINs ('Does not include PINs — use simplisafe_get_pins for those'). However, it does not address potential overlap with simplisafe_healthcheck (which may also cover health status) or when to prefer this over simplisafe_get_system. So guidance is present but not exhaustive.

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

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

The readOnlyHint annotation already establishes that this is a safe read, and the description adds the specific categories of state the agent can expect. It does not add details about auth, failure behavior, polling, or response format, but for an annotated read-only tool the main behavioral disclosure is covered.

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 that names the operation and lists exactly what state is included, with no filler or repetition. Every listed item—alarm state, alarming, connectivity, power/battery, base-station messages—earns its place.

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

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

For a simple one-optional-parameter, read-only tool, the description plus schema is nearly complete: the description identifies the returned state categories and the schema resolves the sid optionality. A small gap is the absence of any hint about the response structure, but the listed fields compensate because there is no output 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?

The input schema already documents the single sid parameter at 100% coverage, including the optional-when-one-system / required-when-multiple rule. The description only reinforces 'one system' and adds no new 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 names the specific operation (get current state) and the resource (one SimpliSafe system) and enumerates the state components: alarm state, alarming, connectivity, power/battery, and base-station messages. This clearly differentiates it from siblings like simplisafe_list_systems or simplisafe_get_settings, even without naming 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?

The wording implies this is for fetching a live snapshot of a single system rather than listing systems or changing settings, so the intended use is inferable. However, the description never states when to prefer this over siblings or when not to use it, leaving routing to the agent's 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?

The readOnlyHint annotation already marks this as safe, and the description adds useful behavioral context beyond that: it reports whether the refresh token is configured/working, the resolved user ID, and the number of active systems. This tells the agent what diagnostic information it will receive without promising any mutations or side effects.

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 sentences: the first defines the operation, the second enumerates the outputs, and the final usage cue 'Start here when other tools fail' earns its place. It is front-loaded with action and purpose, with no filler or repetition.

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

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

Given no output schema, the description adequately covers the return contract by listing the three key pieces of information the health check produces. It also provides a usage trigger. It could theoretically detail error behavior, but for a zero-parameter read-only healthcheck this is sufficiently 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?

There are zero parameters, and the empty schema is fully covered. The description need not add parameter-level detail because there is nothing to configure; the baseline of 4 for parameterless tools 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 action ('Check that the server can authenticate to SimpliSafe and reach the API') and resource, clearly distinguishing it from sibling tools that list systems, get sensor data, or change alarm state. It also specifies the outputs the agent can expect, making the tool's role unmistakable.

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 'Start here when other tools fail' gives an explicit when-to-use instruction, positioning this as a diagnostic entry point. It does not explicitly list exclusions or alternatives, but the context is clear enough for an agent to know this should precede troubleshooting on other SimpliSafe tools.

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

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

With `readOnlyHint: true` already present, the description adds valuable behavioral detail beyond the annotation: it discloses that the tool polls the base station fresh by default and explains the rationale that stale lock status is worse than a slower response. This gives the agent important expectations about latency and data freshness without contradicting 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?

Two sentences with no filler. The first sentence states the tool's core output, the second explains a key behavioral default and its rationale. Every clause earns its place, and the most decision-relevant information is front-loaded.

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?

Although there is no output schema, the description enumerates the important return contents: lock state, battery status, keypad connectivity, and the serial for `simplisafe_set_lock_state`. Combined with full parameter schema coverage and the readOnly annotation, an agent has enough information to select and invoke the tool 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 baseline is 3. The description adds extra meaning for `force_update` by explaining why fresh polling is the default and why an agent may accept stale data for speed. That is meaningful semantic value beyond the schema, though `sid` remains adequately documented only in 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 clearly states the action ('List'), the resource ('smart locks on a system'), and the exact information returned: current lock state, battery status, keypad connectivity, and the serial for `simplisafe_set_lock_state`. This makes the tool's purpose unambiguous and distinguishes it from related siblings like `simplisafe_list_sensors` and `simplisafe_set_lock_state`.

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 context for when to use this tool: to inspect lock states and obtain the serial needed by `simplisafe_set_lock_state`. It also explains the default polling behavior and the tradeoff between freshness and speed. It does not explicitly name alternatives or state when not to use it, but the intended use is well 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?

The annotations declare readOnlyHint=true, and the description is consistent with that by describing a read-only listing operation. It adds useful contextual detail about the returned statuses and filtering behavior, but it does not disclose response shape, pagination, or side effects of force_update. No contradiction with annotations 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?

The description is two sentences with no wasted words: the verb and resource come first, followed by device categories, statuses, and filter syntax. It avoids repeating schema boilerplate and delivers the most important information in a compact, well-ordered format.

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 listing tool with zero required parameters and full schema coverage, the description is nearly complete: it names relevant device categories and statuses, and the schema fills in the remaining parameter details. The main gap is that it does not steer an agent away from the overlapping simplisafe_list_locks sibling, but this is not critical for actually invoking the tool 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 baseline is 3, but the description adds genuine value by explaining the type_name filter with concrete examples such as 'entry', 'motion_v2', and 'lock'. It also clarifies that the result includes battery, offline, and triggered status, which informs how problems_only is meant to be used. The force_update and problems_only parameters are not described in the main text, but the schema already documents them adequately.

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 object, 'List the sensors and devices paired to a system', and enumerates concrete device categories such as entry sensors, motion, glass break, smoke/CO, and locks. It clearly identifies what the tool returns, but it does not explicitly differentiate itself from the sibling simplisafe_list_locks, which overlaps with the locks category.

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 actionable filter guidance for type_name with concrete examples like 'entry' and 'motion_v2', which helps an agent narrow results. However, it never states when to prefer this tool over simplisafe_list_locks or simplisafe_get_system, nor does it provide any exclusions or alternative routing. Usage context is implied rather than explicit.

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

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

The readOnlyHint annotation already communicates that this is a read-only operation, and the description is consistent with that. It adds useful behavioral context by describing what data is returned, including alarm state values and connectivity/power status, and it explains that the returned sid is needed by other tools. This goes beyond the annotation without contradicting it.

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 sentences with no filler. It front-loads the action and resource, then adds only essential guidance about the sid. Every sentence earns its place.

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

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

For a parameterless list tool with no output schema, the description fully covers what the tool does, what fields are returned, and how the result is used by sibling tools. There is no critical missing context.

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 has zero parameters, so the schema carries no parameter burden. The description correctly notes that the tool lists systems for the account and provides the sid for downstream tools, which is the only meaningful semantic context needed 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?

The description states a specific verb and resource: 'List the SimpliSafe systems on this account.' It also names the key output fields (alarm state, alarming status, connectivity, power status), making the tool's purpose immediately clear. The closing 'Start here' helps distinguish it as the entry point from sibling tools that require an sid.

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 explicitly tells the agent to 'Start here to get the sid other tools take,' which is strong contextual guidance for when to call this tool before others. It does not provide explicit exclusions or alternatives, but the entry-point role is clearly communicated.

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.