sn_state

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description does not need to restate basic safety. It adds important context that all writes are local and do not affect the ServiceNow instance. It does not disclose persistence, lifecycle, or the consequences of note_delete/cache_put, which is a meaningful gap for a multi-action write tool.

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

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

The description is short and front-loads the local-memory scope before listing actions. Every sentence earns its place in a limited sense, but the action list is a raw enumeration rather than a structured explanation. It is concise without being 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?

An output schema exists, so return-value explanation is not required. However, with 12 optional parameters and four actions, the description is far too sparse to support correct invocation. It does not explain action-specific parameters, deletion behavior, or caching semantics, leaving the agent with major operational 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 0%, and the tool has 12 parameters, so the description must compensate. It only names the four action values and gives no meaning for key, body, payload, table, fields, sys_id, encoded_query, and the other parameters, nor which parameters apply to which action. The action list adds minimal value over the schema enum.

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: write to the server's own local memory. It also distinguishes itself from the ServiceNow-facing siblings by saying 'Nothing here touches the ServiceNow instance.' However, bundling four distinct actions into one tool makes the core purpose somewhat broad.

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 when to use it: for local-memory writes rather than ServiceNow instance operations. It does not explain when to choose each of the four actions or when to prefer a sibling tool such as sn_journal or sn_write. The contrast with instance-touching tools is useful but incomplete.

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